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 0.15
10

SYNOPSIS

12       Test commands that come with your Alien:
13
14        use Test2::Bundle::Extended;
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::Bundle::Extended;
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::Bundle::Extended;
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       See Test::Alien::Synthetic for more details.
158
159   run_ok
160        my $run = run_ok $command;
161        my $run = run_ok $command, $message;
162
163       Runs the given command, falling back on any "Alien::Base#bin_dir"
164       methods provided by Alien modules specified with "alien_ok".
165
166       $command can be either a string or an array reference.
167
168       Only fails if the command cannot be found, or if it is killed by a
169       signal!  Returns a Test::Alien::Run object, which you can use to test
170       the exit status, output and standard error.
171
172       Always returns an instance of Test::Alien::Run, even if the command
173       could not be found.
174
175   xs_ok
176        xs_ok $xs;
177        xs_ok $xs, $message;
178
179       Compiles, links the given "XS" code and attaches to Perl.
180
181       If you use the special module name "TA_MODULE" in your "XS" code, it
182       will be replaced by an automatically generated package name.  This can
183       be useful if you want to pass the same "XS" code to multiple calls to
184       "xs_ok" without subsequent calls replacing previous ones.
185
186       $xs may be either a string containing the "XS" code, or a hash
187       reference with these keys:
188
189       xs  The XS code.  This is the only required element.
190
191       pxs The ExtUtils::ParseXS arguments passes as a hash reference.
192
193       verbose
194           Spew copious debug information via test note.
195
196       You can use the "with_subtest" keyword to conditionally run a subtest
197       if the "xs_ok" call succeeds.  If "xs_ok" does not work, then the
198       subtest will automatically be skipped.  Example:
199
200        xs_ok $xs, with_subtest {
201          # skipped if $xs fails for some reason
202          my($module) = @_;
203          plan 1;
204          is $module->foo, 1;
205        };
206
207       The module name detected during the XS parsing phase will be passed in
208       to the subtest.  This is helpful when you are using a generated module
209       name.
210
211   ffi_ok
212        ffi_ok;
213        ffi_ok \%opt;
214        ffi_ok \%opt, $message;
215
216       Test that FFI::Platypus works.
217
218       "\%opt" is a hash reference with these keys (all optional):
219
220       symbols
221           List references of symbols that must be found for the test to
222           succeed.
223
224       ignore_not_found
225           Ignores symbols that aren't found.  This affects functions accessed
226           via FFI::Platypus#attach and FFI::Platypus#function methods, and
227           does not influence the "symbols" key above.
228
229       lang
230           Set the language.  Used primarily for language specific native
231           types.
232
233       As with "xs_ok" above, you can use the "with_subtest" keyword to
234       specify a subtest to be run if "ffi_ok" succeeds (it will skip
235       otherwise).  The FFI::Platypus instance is passed into the subtest as
236       the first argument.  For example:
237
238        ffi_ok with_subtest {
239          my($ffi) = @_;
240          is $ffi->function(foo => [] => 'void')->call, 42;
241        };
242

SEE ALSO

244       Alien
245       Alien::Base
246       Alien::Build
247       alienfile
248       Test2
249       Test::Alien::Run
250       Test::Alien::CanCompile
251       Test::Alien::CanPlatypus
252       Test::Alien::Synthetic
253

AUTHOR

255       Graham Ollis <plicease@cpan.org>
256
258       This software is copyright (c) 2015 by Graham Ollis.
259
260       This is free software; you can redistribute it and/or modify it under
261       the same terms as the Perl 5 programming language system itself.
262
263
264
265perl v5.30.0                      2019-07-26                    Test::Alien(3)
Impressum