1Test::Alien(3) User Contributed Perl Documentation Test::Alien(3)
2
3
4
6 Test::Alien - Testing tools for Alien modules
7
9 version 2.77
10
12 Test commands that come with your Alien:
13
14 use Test2::V0;
15 use Test::Alien;
16 use Alien::patch;
17
18 alien_ok 'Alien::patch';
19 run_ok([ 'patch', '--version' ])
20 ->success
21 # we only accept the version written
22 # by Larry ...
23 ->out_like(qr{Larry Wall});
24
25 done_testing;
26
27 Test that your library works with "XS":
28
29 use Test2::V0;
30 use Test::Alien;
31 use Alien::Editline;
32
33 alien_ok 'Alien::Editline';
34 my $xs = do { local $/; <DATA> };
35 xs_ok $xs, with_subtest {
36 my($module) = @_;
37 ok $module->version;
38 };
39
40 done_testing;
41
42 __DATA__
43
44 #include "EXTERN.h"
45 #include "perl.h"
46 #include "XSUB.h"
47 #include <editline/readline.h>
48
49 const char *
50 version(const char *class)
51 {
52 return rl_library_version;
53 }
54
55 MODULE = TA_MODULE PACKAGE = TA_MODULE
56
57 const char *version(class);
58 const char *class;
59
60 Test that your library works with FFI::Platypus:
61
62 use Test2::V0;
63 use Test::Alien;
64 use Alien::LibYAML;
65
66 alien_ok 'Alien::LibYAML';
67 ffi_ok { symbols => ['yaml_get_version'] }, with_subtest {
68 my($ffi) = @_;
69 my $get_version = $ffi->function(yaml_get_version => ['int*','int*','int*'] => 'void');
70 $get_version->call(\my $major, \my $minor, \my $patch);
71 like $major, qr{[0-9]+};
72 like $minor, qr{[0-9]+};
73 like $patch, qr{[0-9]+};
74 };
75
76 done_testing;
77
79 This module provides tools for testing Alien modules. It has hooks to
80 work easily with Alien::Base based modules, but can also be used via
81 the synthetic interface to test non Alien::Base based Alien modules.
82 It has very modest prerequisites.
83
84 Prior to this module the best way to test a Alien module was via
85 Test::CChecker. The main downside to that module is that it is heavily
86 influenced by and uses ExtUtils::CChecker, which is a tool for checking
87 at install time various things about your compiler. It was also
88 written before Alien::Base became as stable as it is today. In
89 particular, Test::CChecker does its testing by creating an executable
90 and running it. Unfortunately Perl uses extensions by creating dynamic
91 libraries and linking them into the Perl process, which is different in
92 subtle and error prone ways. This module attempts to test the
93 libraries in the way that they will actually be used, via either "XS"
94 or FFI::Platypus. It also provides a mechanism for testing binaries
95 that are provided by the various Alien modules (for example
96 Alien::gmake and Alien::patch).
97
98 Alien modules can actually be useable without a compiler, or without
99 FFI::Platypus (for example, if the library is provided by the system,
100 and you are using FFI::Platypus, or if you are building from source and
101 you are using "XS"), so tests with missing prerequisites are
102 automatically skipped. For example, "xs_ok" will automatically skip
103 itself if a compiler is not found, and "ffi_ok" will automatically skip
104 itself if FFI::Platypus is not installed.
105
107 alien_ok
108 alien_ok $alien, $message;
109 alien_ok $alien;
110
111 Load the given Alien instance or class. Checks that the instance or
112 class conforms to the same interface as Alien::Base. Will be used by
113 subsequent tests. The $alien module only needs to provide these
114 methods in order to conform to the Alien::Base interface:
115
116 cflags
117 String containing the compiler flags
118
119 libs
120 String containing the linker and library flags
121
122 dynamic_libs
123 List of dynamic libraries. Returns empty list if the Alien module
124 does not provide this.
125
126 bin_dir
127 Directory containing tool binaries. Returns empty list if the
128 Alien module does not provide this.
129
130 If your Alien module does not conform to this interface then you can
131 create a synthetic Alien module using the "synthetic" function.
132
133 synthetic
134 my $alien = synthetic \%config;
135
136 Create a synthetic Alien module which can be passed into "alien_ok".
137 "\%config" can contain these keys (all of which are optional):
138
139 cflags
140 String containing the compiler flags.
141
142 cflags_static
143 String containing the static compiler flags (optional).
144
145 libs
146 String containing the linker and library flags.
147
148 libs_static
149 String containing the static linker flags (optional).
150
151 dynamic_libs
152 List reference containing the dynamic libraries.
153
154 bin_dir
155 Tool binary directory.
156
157 runtime_prop
158 Runtime properties.
159
160 See Test::Alien::Synthetic for more details.
161
162 run_ok
163 my $run = run_ok $command;
164 my $run = run_ok $command, $message;
165
166 Runs the given command, falling back on any "Alien::Base#bin_dir"
167 methods provided by Alien modules specified with "alien_ok".
168
169 $command can be either a string or an array reference.
170
171 Only fails if the command cannot be found, or if it is killed by a
172 signal! Returns a Test::Alien::Run object, which you can use to test
173 the exit status, output and standard error.
174
175 Always returns an instance of Test::Alien::Run, even if the command
176 could not be found.
177
178 xs_ok
179 xs_ok $xs;
180 xs_ok $xs, $message;
181
182 Compiles, links the given "XS" code and attaches to Perl.
183
184 If you use the special module name "TA_MODULE" in your "XS" code, it
185 will be replaced by an automatically generated package name. This can
186 be useful if you want to pass the same "XS" code to multiple calls to
187 "xs_ok" without subsequent calls replacing previous ones.
188
189 $xs may be either a string containing the "XS" code, or a hash
190 reference with these keys:
191
192 xs The XS code. This is the only required element.
193
194 pxs Extra ExtUtils::ParseXS arguments passed in as a hash reference.
195
196 cbuilder_check
197 The compile check that should be done prior to attempting to build.
198 Should be one of "have_compiler" or "have_cplusplus". Defaults to
199 "have_compiler".
200
201 cbuilder_config
202 Hash to override values normally provided by "Config".
203
204 cbuilder_compile
205 Extra The ExtUtils::CBuilder arguments passed in as a hash
206 reference.
207
208 cbuilder_link
209 Extra The ExtUtils::CBuilder arguments passed in as a hash
210 reference.
211
212 verbose
213 Spew copious debug information via test note.
214
215 You can use the "with_subtest" keyword to conditionally run a subtest
216 if the "xs_ok" call succeeds. If "xs_ok" does not work, then the
217 subtest will automatically be skipped. Example:
218
219 xs_ok $xs, with_subtest {
220 # skipped if $xs fails for some reason
221 my($module) = @_;
222 is $module->foo, 1;
223 };
224
225 The module name detected during the XS parsing phase will be passed in
226 to the subtest. This is helpful when you are using a generated module
227 name.
228
229 If you need to test XS C++ interfaces, see Test::Alien::CPP.
230
231 Caveats: "xs_ok" uses ExtUtils::ParseXS, which may call "exit" under
232 certain error conditions. While this is not really good thing to
233 happen in the middle of a test, it usually indicates a real failure
234 condition, and it should return a failure condition so the test should
235 still fail overall.
236
237 [version 2.53]
238
239 As of version 2.53, "xs_ok" will only remove temporary generated files
240 if the test is successful by default. You can force either always or
241 never removing the temporary generated files using the
242 "TEST_ALIEN_ALWAYS_KEEP" environment variable (see "ENVIRONMENT"
243 below).
244
245 ffi_ok
246 ffi_ok;
247 ffi_ok \%opt;
248 ffi_ok \%opt, $message;
249
250 Test that FFI::Platypus works.
251
252 "\%opt" is a hash reference with these keys (all optional):
253
254 symbols
255 List references of symbols that must be found for the test to
256 succeed.
257
258 ignore_not_found
259 Ignores symbols that aren't found. This affects functions accessed
260 via FFI::Platypus#attach and FFI::Platypus#function methods, and
261 does not influence the "symbols" key above.
262
263 lang
264 Set the language. Used primarily for language specific native
265 types.
266
267 api Set the API. "api = 1" requires FFI::Platypus 0.99 or later. This
268 option was added with Test::Alien version 1.90, so your use line
269 should include this version as a safeguard to make sure it works:
270
271 use Test::Alien 1.90;
272 ...
273 ffi_ok ...;
274
275 As with "xs_ok" above, you can use the "with_subtest" keyword to
276 specify a subtest to be run if "ffi_ok" succeeds (it will skip
277 otherwise). The FFI::Platypus instance is passed into the subtest as
278 the first argument. For example:
279
280 ffi_ok with_subtest {
281 my($ffi) = @_;
282 is $ffi->function(foo => [] => 'void')->call, 42;
283 };
284
285 helper_ok
286 helper_ok $name;
287 helper_ok $name, $message;
288
289 Tests that the given helper has been defined.
290
291 plugin_ok
292 [version 2.52]
293
294 plugin_ok $plugin_name, $message;
295 plugin_ok [$plugin_name, @args], $message;
296
297 This applies an Alien::Build::Plugin to the interpolator used by
298 "helper_ok", "interpolate_template_is" and "interpolate_run_ok" so that
299 you can test with any helpers that plugin provides. Useful, for
300 example for getting "%{configure}" from
301 Alien::Build::Plugin::Build::Autoconf.
302
303 interpolate_template_is
304 interpolate_template_is $template, $string;
305 interpolate_template_is $template, $string, $message;
306 interpolate_template_is $template, $regex;
307 interpolate_template_is $template, $regex, $message;
308
309 Tests that the given template when evaluated with the appropriate
310 helpers will match either the given string or regular expression.
311
312 interpolate_run_ok
313 [version 2.52]
314
315 my $run = interpolate_run_ok $command;
316 my $run = interpolate_run_ok $command, $message;
317
318 This is the same as "run_ok" except it runs the command through the
319 interpolator first.
320
322 "TEST_ALIEN_ALWAYS_KEEP"
323 If this is defined then it will override the built in logic that
324 decides if the temporary files generated by "xs_ok" should be kept
325 when the test file terminates. If set to true the generated files
326 will always be kept. If set to false, then they will always be
327 removed.
328
329 "TEST_ALIEN_ALIENS_MISSING"
330 By default, this module will warn you if some tools are used
331 without first invoking "alien_ok". This is usually a mistake, but
332 if you really do want to use one of these tools with no aliens
333 loaded, you can set this environment variable to false.
334
336 Alien
337 Alien::Base
338 Alien::Build
339 alienfile
340 Test2
341 Test::Alien::Run
342 Test::Alien::CanCompile
343 Test::Alien::CanPlatypus
344 Test::Alien::Synthetic
345 Test::Alien::CPP
346
348 Author: Graham Ollis <plicease@cpan.org>
349
350 Contributors:
351
352 Diab Jerius (DJERIUS)
353
354 Roy Storey (KIWIROY)
355
356 Ilya Pavlov
357
358 David Mertens (run4flat)
359
360 Mark Nunberg (mordy, mnunberg)
361
362 Christian Walde (Mithaldu)
363
364 Brian Wightman (MidLifeXis)
365
366 Zaki Mughal (zmughal)
367
368 mohawk (mohawk2, ETJ)
369
370 Vikas N Kumar (vikasnkumar)
371
372 Flavio Poletti (polettix)
373
374 Salvador Fandiño (salva)
375
376 Gianni Ceccarelli (dakkar)
377
378 Pavel Shaydo (zwon, trinitum)
379
380 Kang-min Liu (劉康民, gugod)
381
382 Nicholas Shipp (nshp)
383
384 Juan Julián Merelo Guervós (JJ)
385
386 Joel Berger (JBERGER)
387
388 Petr Písař (ppisar)
389
390 Lance Wicks (LANCEW)
391
392 Ahmad Fatoum (a3f, ATHREEF)
393
394 José Joaquín Atria (JJATRIA)
395
396 Duke Leto (LETO)
397
398 Shoichi Kaji (SKAJI)
399
400 Shawn Laffan (SLAFFAN)
401
402 Paul Evans (leonerd, PEVANS)
403
404 Håkon Hægland (hakonhagland, HAKONH)
405
406 nick nauwelaerts (INPHOBIA)
407
408 Florian Weimer
409
411 This software is copyright (c) 2011-2022 by Graham Ollis.
412
413 This is free software; you can redistribute it and/or modify it under
414 the same terms as the Perl 5 programming language system itself.
415
416
417
418perl v5.36.0 2023-01-20 Test::Alien(3)