Test2::Tools::LoadModule - Test whether a module can be successfully loaded.
use Test2::V0; use Test2::Tools::LoadModule; load_module_ok 'My::Module'; done_testing();
This Test2::Tools module tests whether a module can be loaded, and optionally whether it has at least a given version, and exports specified symbols. It can also skip tests, or skip all tests, based on these criteria.
Test2::Manual::Testing::Migrating deals with migrating from Test::More to Test2::V0. It states that instead of require_ok() you should simply use the require() built-in, since a failure to load the required module or file will cause the test script to fail anyway. The same is said for use_ok().
require_ok()
require()
use_ok()
In my perhaps-not-so-humble opinion this overlooks the fact that if you can not load the module you are testing, it may make sense to abort not just the individual test script but the entire test run. Put another way, the absence of an analogue to Test::More's require_ok() means there is no analogue to
require_ok( 'My::Module' ) or BAIL_OUT();
This module restores that functionality.
Note that if you are using this module with testing tools that are not based on Test2::V0 you may have to tweak the load order of modules. I ran into this in the early phases of implementation, and fixed it for my own use by initializing the testing system as late as possible, but I can not promise that all such problems have been eliminated.
Accurately testing whether a module can be loaded is more complicated than it might first appear. One known issue is that you can get a false pass if the module under test forgets to load a module it needs, but this module loads it for its own use.
Ideally this module would use nothing that Test2 does not, but that seems to require a fair amount of wheel-reinventing. What this module does try to do is to load the extra modules only if it really needs them. Specifically:
Test2
Getopt::Long is loaded only if arguments are passed to the use Test::Tools::LoadModule statement.
use Test::Tools::LoadModule
File::Find and File::Spec are loaded only if all_modules_tried_ok() is called.
Because Carp and Exporter are used by Test2::API (at least as of version 1.302181), this module makes no attempt to avoid their use.
1.302181
All subroutines documented below are exportable, either by name or using one of the following tags:
load_module_ok $module, $ver, $import, $name, @diag;
Prototype: (@).
(@)
This subroutine tests whether the specified module (not file) can be loaded. All arguments are optional. The arguments are:
This is the name of the module to be loaded. If unspecified or specified as undef, it defaults to the caller's CLASS if that exists; otherwise an exception is thrown.
undef
CLASS
If defined, the test fails if the installed module is not at least this version. An exception is thrown if the version number is invalid.
If undef, no version check is done.
This argument specifies the import list. undef means to import the default symbols, [] means not to import anything, and a non-empty array reference means to import the specified symbols.
[]
If undef, the name defaults to the code used to load the module. Note that this code, and therefore the default name, may change without notice.
Diagnostics are only issued on failure.
Argument validation failures are signalled by croak().
croak()
The module is loaded, and version checks and imports are done if specified. The test passes if all these succeed, and fails otherwise.
Note that any imports from the loaded module take place when this subroutine is called, which is normally at run time. Imported subroutines will be callable, provided you do not make use of prototypes or attributes.
If you want anything imported from the loaded module to be available for subsequent compilation (e.g. variables, subroutine prototypes) you will need to put the call to this subroutine in a BEGIN { } block:
BEGIN { }
BEGIN { load_module_ok 'My::Module'; }
By default, $@ is appended to the diagnostics issued in the event of a load failure. If you want to omit this, or embed the value in your own text, see CONFIGURATION, below.
$@
As a side effect, the names of all modules tried with this test are recorded, along with test results (pass/fail) for the use of all_modules_tried_ok().
load_module_or_skip $module, $ver, $import, $name, $num;
This subroutine performs the same loading actions as load_module_ok(), but no tests are performed. Instead, the specified number of tests is skipped if the load fails.
The arguments are the same as load_module_ok(), except that the fifth argument ($num in the example) is the number of tests to skip, defaulting to 1.
$num
1
The $name argument gives the skip message, and defaults to "Unable to ..." where the ellipsis is the code used to load the module.
$name
"Unable to ..."
load_module_or_skip_all $module, $ver, $import, $name;
This subroutine performs the same loading actions as load_module_ok(), but no tests are performed. Instead, all tests are skipped if any part of the load fails.
The arguments are the same as load_module_ok(), except for the fact that diagnostics are not specified.
This subroutine can be called either at the top level or in a subtest, but either way it must be called before any actual tests in the file or subtest.
all_modules_tried_ok
Added in version 0.002.
0.002
This test traverses any directories specified as arguments looking for Perl modules (defined as files whose names end in .pm). A failing test is generated for any such file not previously tested using load_module_ok().
If no directory is specified, the default is ( '/blib/lib', '/blib/arch' ) .
( '/blib/lib', '/blib/arch' )
NOTE that no attempt is made to parse the file and determine its module name. The module is assumed from the part of the file path below the specified directory. So an explicit specification of lib/ will work (if that is where the modules are stored) but an explicit blib/ will not.
clear_modules_tried
Prototype: ().
()
This is not a test. It clears the record of modules tried by load_module_ok().
require_ok $module;
Prototype: ($).
($)
This subroutine is more or less the same as the Test::More subroutine of the same name. The argument is the name of the module to load.
use_ok $module, @imports; use_ok $module, $version, @imports;
Prototype: ($;@).
($;@)
This subroutine is more or less the same as the Test::More subroutine of the same name. The arguments are the name of the module to load, and optional version (recognized by the equivalent of version::is_lax(), and optional imports.
version::is_lax()
The action of the load_module_*() subroutines is configurable using POSIX-style options. If used as subroutine arguments they apply only to that subroutine call. If used as arguments to use(), they apply to everything in the scope of the use(), though this requires Perl 5.10 or above, and you must specify any desired imports.
load_module_*()
use()
These options are parsed by Getopt::Long (q.v.) in POSIX mode, so they must appear before non-option arguments. They are all documented double-dashed. A single leading dash is tolerated except in the form --option=argument, where the double dash is required.
--option=argument
The following configuration options are available.
If asserted, this possibly-badly-named Boolean option specifies that an undef or unspecified import list imports nothing, while [] does the default import.
The default is -norequire, which is the other way around. This is the way use() works, which is what inspired the name of the option.
-norequire
This is just a shorter synonym for --require.
--load_error 'Error: %s'
This option specifies the formatting of the load error for those subroutines that append it to the diagnostics. The value is interpreted as follows:
'%s'
or anything that looks like an sprintf() string substitution is interpreted verbatim as the sprintf format to use to format the error;
sprintf()
specifies the default, '%s';
0
specifies that $@ should not be appended to the diagnostics at all.
For example, if you want your diagnostics to look like the Test::More require_ok() diagnostics, you can do something like this (at least under Perl 5.10 or above):
{ # Begin scope use Test2::Tools::LoadModule -load_error => 'Error: %s'; load_module_ok $my_module, undef, undef, "require $my_module;", "Tried to require '$my_module'."; ... } # -load_error reverts to whatever it was before.
If you want your code to work under Perl 5.8, you can equivalently do
load_module_ok -load_error => 'Error: %s', $my_module, undef, undef, "require $my_module;" "Tried to require '$my_module'.";
Note that, while you can specify options on your initial load, if you do so you must specify your desired imports explicitly, as (e.g.)
use Test2::Tools::LoadModule -load_error => 'Bummer! %s', ':default';
Test::More
Test2::V0
Test2::Require
Test2::Manual::Testing::Migrating
Test2::Plugin::BailOnFail
Support is by the author. Please file bug reports at https://rt.cpan.org/Public/Dist/Display.html?Name=Test2-Tools-LoadModule, https://github.com/trwyant/perl-Test2-Tools-LoadModule/issues, or in electronic mail to the author.
Thomas R. Wyant, III wyant at cpan dot org
Copyright (C) 2019-2022 by Thomas R. Wyant, III
This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
To install Test2::Tools::LoadModule, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test2::Tools::LoadModule
CPAN shell
perl -MCPAN -e shell install Test2::Tools::LoadModule
For more information on module installation, please visit the detailed CPAN module installation guide.