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.38
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   ffi_ok
232        ffi_ok;
233        ffi_ok \%opt;
234        ffi_ok \%opt, $message;
235
236       Test that FFI::Platypus works.
237
238       "\%opt" is a hash reference with these keys (all optional):
239
240       symbols
241           List references of symbols that must be found for the test to
242           succeed.
243
244       ignore_not_found
245           Ignores symbols that aren't found.  This affects functions accessed
246           via FFI::Platypus#attach and FFI::Platypus#function methods, and
247           does not influence the "symbols" key above.
248
249       lang
250           Set the language.  Used primarily for language specific native
251           types.
252
253       api Set the API.  "api = 1" requires FFI::Platypus 0.99 or later.  This
254           option was added with Test::Alien version 1.90, so your use line
255           should include this version as a safeguard to make sure it works:
256
257            use Test::Alien 1.90;
258            ...
259            ffi_ok ...;
260
261       As with "xs_ok" above, you can use the "with_subtest" keyword to
262       specify a subtest to be run if "ffi_ok" succeeds (it will skip
263       otherwise).  The FFI::Platypus instance is passed into the subtest as
264       the first argument.  For example:
265
266        ffi_ok with_subtest {
267          my($ffi) = @_;
268          is $ffi->function(foo => [] => 'void')->call, 42;
269        };
270
271   helper_ok
272        helper_ok $name;
273        helper_ok $name, $message;
274
275       Tests that the given helper has been defined.
276
277   interpolate_template_is
278        interpolate_template_is $template, $string;
279        interpolate_template_is $template, $string, $message;
280        interpolate_template_is $template, $regex;
281        interpolate_template_is $template, $regex, $message;
282
283       Tests that the given template when evaluated with the appropriate
284       helpers will match either the given string or regular expression.
285

AUTHOR

299       Author: Graham Ollis <plicease@cpan.org>
300
301       Contributors:
302
303       Diab Jerius (DJERIUS)
304
305       Roy Storey (KIWIROY)
306
307       Ilya Pavlov
308
309       David Mertens (run4flat)
310
311       Mark Nunberg (mordy, mnunberg)
312
313       Christian Walde (Mithaldu)
314
315       Brian Wightman (MidLifeXis)
316
317       Zaki Mughal (zmughal)
318
319       mohawk (mohawk2, ETJ)
320
321       Vikas N Kumar (vikasnkumar)
322
323       Flavio Poletti (polettix)
324
325       Salvador Fandiño (salva)
326
327       Gianni Ceccarelli (dakkar)
328
329       Pavel Shaydo (zwon, trinitum)
330
331       Kang-min Liu (劉康民, gugod)
332
333       Nicholas Shipp (nshp)
334
335       Juan Julián Merelo Guervós (JJ)
336
337       Joel Berger (JBERGER)
338
339       Petr Pisar (ppisar)
340
341       Lance Wicks (LANCEW)
342
343       Ahmad Fatoum (a3f, ATHREEF)
344
345       José Joaquín Atria (JJATRIA)
346
347       Duke Leto (LETO)
348
349       Shoichi Kaji (SKAJI)
350
351       Shawn Laffan (SLAFFAN)
352
353       Paul Evans (leonerd, PEVANS)
354
355       Håkon Hægland (hakonhagland, HAKONH)
356

COPYRIGHT AND LICENSE

358       This software is copyright (c) 2011-2020 by Graham Ollis.
359
360       This is free software; you can redistribute it and/or modify it under
361       the same terms as the Perl 5 programming language system itself.
362
363
364
365perl v5.32.0                      2021-01-12                    Test::Alien(3)