1Test::Alien(3) User Contributed Perl Documentation Test::Alien(3)
2
6 Test::Alien - Testing tools for Alien modules
7
9 version 2.47
10
12 Test commands that come with your Alien:
13 use Test2::V0;
15 use Test::Alien;
16 use Alien::patch;
17 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 done_testing;
26 Test that your library works with "XS":
28 use Test2::V0;
30 use Test::Alien;
31 use Alien::Editline;
32 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 done_testing;
41 __DATA__
43 #include "EXTERN.h"
45 #include "perl.h"
46 #include "XSUB.h"
47 #include <editline/readline.h>
48 const char *
50 version(const char *class)
51 {
52 return rl_library_version;
53 }
54 MODULE = TA_MODULE PACKAGE = TA_MODULE
56 const char *version(class);
58 const char *class;
59 Test that your library works with FFI::Platypus:
61 use Test2::V0;
63 use Test::Alien;
64 use Alien::LibYAML;
65 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 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 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 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 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 cflags
117 String containing the compiler flags
118 libs
120 String containing the linker and library flags
121 dynamic_libs
123 List of dynamic libraries. Returns empty list if the Alien module
124 does not provide this.
125 bin_dir
127 Directory containing tool binaries. Returns empty list if the
128 Alien module does not provide this.
129 If your Alien module does not conform to this interface then you can
131 create a synthetic Alien module using the "synthetic" function.
132 synthetic
134 my $alien = synthetic \%config;
135 Create a synthetic Alien module which can be passed into "alien_ok".
137 "\%config" can contain these keys (all of which are optional):
138 cflags
140 String containing the compiler flags.
141 cflags_static
143 String containing the static compiler flags (optional).
144 libs
146 String containing the linker and library flags.
147 libs_static
149 String containing the static linker flags (optional).
150 dynamic_libs
152 List reference containing the dynamic libraries.
153 bin_dir
155 Tool binary directory.
156 runtime_prop
158 Runtime properties.
159 See Test::Alien::Synthetic for more details.
161 run_ok
163 my $run = run_ok $command;
164 my $run = run_ok $command, $message;
165 Runs the given command, falling back on any "Alien::Base#bin_dir"
167 methods provided by Alien modules specified with "alien_ok".
168 $command can be either a string or an array reference.
170 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 Always returns an instance of Test::Alien::Run, even if the command
176 could not be found.
177 xs_ok
179 xs_ok $xs;
180 xs_ok $xs, $message;
181 Compiles, links the given "XS" code and attaches to Perl.
183 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 $xs may be either a string containing the "XS" code, or a hash
190 reference with these keys:
191 xs The XS code. This is the only required element.
193 pxs Extra ExtUtils::ParseXS arguments passed in as a hash reference.
195 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 cbuilder_config
202 Hash to override values normally provided by "Config".
203 cbuilder_compile
205 Extra The ExtUtils::CBuilder arguments passed in as a hash
206 reference.
207 cbuilder_link
209 Extra The ExtUtils::CBuilder arguments passed in as a hash
210 reference.
211 verbose
213 Spew copious debug information via test note.
214 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 xs_ok $xs, with_subtest {
220 # skipped if $xs fails for some reason
221 my($module) = @_;
222 is $module->foo, 1;
223 };
224 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 If you need to test XS C++ interfaces, see Test::Alien::CPP.
230 ffi_ok
232 ffi_ok;
233 ffi_ok \%opt;
234 ffi_ok \%opt, $message;
235 Test that FFI::Platypus works.
237 "\%opt" is a hash reference with these keys (all optional):
239 symbols
241 List references of symbols that must be found for the test to
242 succeed.
243 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 lang
250 Set the language. Used primarily for language specific native
251 types.
252 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 use Test::Alien 1.90;
258 ...
259 ffi_ok ...;
260 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 ffi_ok with_subtest {
267 my($ffi) = @_;
268 is $ffi->function(foo => [] => 'void')->call, 42;
269 };
270 helper_ok
272 helper_ok $name;
273 helper_ok $name, $message;
274 Tests that the given helper has been defined.
276 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 Tests that the given template when evaluated with the appropriate
284 helpers will match either the given string or regular expression.
285
287 Alien
288 Alien::Base
289 Alien::Build
290 alienfile
291 Test2
292 Test::Alien::Run
293 Test::Alien::CanCompile
294 Test::Alien::CanPlatypus
295 Test::Alien::Synthetic
296 Test::Alien::CPP
297
299 Author: Graham Ollis <plicease@cpan.org>
300 Contributors:
302 Diab Jerius (DJERIUS)
304 Roy Storey (KIWIROY)
306 Ilya Pavlov
308 David Mertens (run4flat)
310 Mark Nunberg (mordy, mnunberg)
312 Christian Walde (Mithaldu)
314 Brian Wightman (MidLifeXis)
316 Zaki Mughal (zmughal)
318 mohawk (mohawk2, ETJ)
320 Vikas N Kumar (vikasnkumar)
322 Flavio Poletti (polettix)
324 Salvador Fandiño (salva)
326 Gianni Ceccarelli (dakkar)
328 Pavel Shaydo (zwon, trinitum)
330 Kang-min Liu (劉康民, gugod)
332 Nicholas Shipp (nshp)
334 Juan Julián Merelo Guervós (JJ)
336 Joel Berger (JBERGER)
338 Petr Písař (ppisar)
340 Lance Wicks (LANCEW)
342 Ahmad Fatoum (a3f, ATHREEF)
344 José Joaquín Atria (JJATRIA)
346 Duke Leto (LETO)
348 Shoichi Kaji (SKAJI)
350 Shawn Laffan (SLAFFAN)
352 Paul Evans (leonerd, PEVANS)
354 Håkon Hægland (hakonhagland, HAKONH)
356 nick nauwelaerts (INPHOBIA)
358
360 This software is copyright (c) 2011-2020 by Graham Ollis.
361 This is free software; you can redistribute it and/or modify it under
363 the same terms as the Perl 5 programming language system itself.
364perl v5.34.0 2022-03-07 Test::Alien(3)