Manpages - Test_Alien.3pm

alien_ok $alien, $message; alien_ok $alien;

Load the given Alien instance or class. Checks that the instance or class conforms to the same interface as Alien::Base. Will be used by subsequent tests. The $alien module only needs to provide these methods in order to conform to the Alien::Base interface:

cflags

String containing the compiler flags

libs

String containing the linker and library flags

dynamic_libs

List of dynamic libraries. Returns empty list if the Alien module does not provide this.

bin_dir

Directory containing tool binaries. Returns empty list if the Alien module does not provide this.

If your Alien module does not conform to this interface then you can create a synthetic Alien module using the synthetic function.

my $alien = synthetic \%config;

Create a synthetic Alien module which can be passed into alien_ok. \%config can contain these keys (all of which are optional):

cflags

String containing the compiler flags.

cflags_static

String containing the static compiler flags (optional).

libs

String containing the linker and library flags.

libs_static

String containing the static linker flags (optional).

dynamic_libs

List reference containing the dynamic libraries.

bin_dir

Tool binary directory.

runtime_prop

Runtime properties.

See Test::Alien::Synthetic for more details.

my $run = run_ok $command; my $run = run_ok $command, $message;

Runs the given command, falling back on any Alien::Base#bin_dir methods provided by Alien modules specified with alien_ok.

$command can be either a string or an array reference.

Only fails if the command cannot be found, or if it is killed by a signal! Returns a Test::Alien::Run object, which you can use to test the exit status, output and standard error.

Always returns an instance of Test::Alien::Run, even if the command could not be found.

xs_ok $xs; xs_ok $xs, $message;

Compiles, links the given XS code and attaches to Perl.

If you use the special module name TA_MODULE in your XS code, it will be replaced by an automatically generated package name. This can be useful if you want to pass the same XS code to multiple calls to xs_ok without subsequent calls replacing previous ones.

$xs may be either a string containing the XS code, or a hash reference with these keys:

xs

The XS code. This is the only required element.

pxs

Extra ExtUtils::ParseXS arguments passed in as a hash reference.

cbuilder_check

The compile check that should be done prior to attempting to build. Should be one of have_compiler or have_cplusplus. Defaults to have_compiler.

cbuilder_config

Hash to override values normally provided by Config.

cbuilder_compile

Extra The ExtUtils::CBuilder arguments passed in as a hash reference.

cbuilder_link

Extra The ExtUtils::CBuilder arguments passed in as a hash reference.

verbose

Spew copious debug information via test note.

You can use the with_subtest keyword to conditionally run a subtest if the xs_ok call succeeds. If xs_ok does not work, then the subtest will automatically be skipped. Example:

xs_ok $xs, with_subtest { # skipped if $xs fails for some reason my($module) = @_; is $module->foo, 1; };

The module name detected during the XS parsing phase will be passed in to the subtest. This is helpful when you are using a generated module name.

If you need to test XS C++ interfaces, see Test::Alien::CPP.

ffi_ok; ffi_ok \%opt; ffi_ok \%opt, $message;

Test that FFI::Platypus works.

\%opt is a hash reference with these keys (all optional):

symbols

List references of symbols that must be found for the test to succeed.

ignore_not_found

Ignores symbols that aren’t found. This affects functions accessed via FFI::Platypus#attach and FFI::Platypus#function methods, and does not influence the symbols key above.

lang

Set the language. Used primarily for language specific native types.

api

Set the API. api = 1 requires FFI::Platypus 0.99 or later. This option was added with Test::Alien version 1.90, so your use line should include this version as a safeguard to make sure it works: use Test::Alien 1.90; … ffi_ok …;

As with xs_ok above, you can use the with_subtest keyword to specify a subtest to be run if ffi_ok succeeds (it will skip otherwise). The FFI::Platypus instance is passed into the subtest as the first argument. For example:

ffi_ok with_subtest { my($ffi) = @_; is $ffi->function(foo => [] => void)->call, 42; };

helper_ok $name; helper_ok $name, $message;

Tests that the given helper has been defined.

interpolate_template_is $template, $string; interpolate_template_is $template, $string, $message; interpolate_template_is $template, $regex; interpolate_template_is $template, $regex, $message;

Tests that the given template when evaluated with the appropriate helpers will match either the given string or regular expression.