Test::Alien(3pm)

1Test::Alien(3)        User Contributed Perl Documentation       Test::Alien(3)
2
3
4

NAME

6       Test::Alien - Testing tools for Alien modules
7

VERSION

9       version 2.80
10

SYNOPSIS

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

DESCRIPTION

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

FUNCTIONS

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

ENVIRONMENT

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

AUTHOR

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

COPYRIGHT AND LICENSE

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.38.0                      2023-07-20                    Test::Alien(3)