NAME
Bio::Root::Test - common base for all BioPerl test scripts
SYNOPSIS
use lib '.'; # (for core package tests only)
use Bio::Root::Test;
test_begin(-tests => 20,
-requires_modules => [qw(IO::String XML::Parser)],
-requires_networking => 1);
my $do_network_tests = test_network();
my $output_debugging = test_debug();
# Bio::Root::Test rewraps Test::Most, so one can carry out tests with
# Test::More, Test::Exception, Test::Warn, Test::Deep, Test::Diff syntax
SKIP: {
# these tests need version 2.6 of Optional::Module to work
test_skip(-tests => 10, -requires_module => 'Optional::Module 2.6');
use_ok('Optional::Module');
# 9 other optional tests that need Optional::Module
}
SKIP: {
test_skip(-tests => 10, -requires_networking => 1);
# 10 optional tests that require internet access (only makes sense in the
# context of a script that doesn't use -requires_networking in the call to
# &test_begin)
}
# in unix terms, we want to test with a file t/data/input_file.txt
my $input_file = test_input_file('input_file.txt');
# we want the name of a file we can write to, that will be automatically
# deleted when the test script finishes
my $output_file = test_output_file();
# we want the name of a directory we can store files in, that will be
# automatically deleted when the test script finishes
my $output_dir = test_output_dir();DESCRIPTION
This provides a common base for all BioPerl test scripts. It safely handles the loading of Test::Most, itself a simple wrapper around several highly used test modules: Test::More, Test::Exception, Test::Warn, Test::Deep, and Test::Diff. It also presents an interface to common needs such as skipping all tests if required modules aren't present or if network tests haven't been enabled. See test_begin().
In the same way, it allows you to skip just a subset of tests for those same reasons, in addition to requiring certain executables and environment variables. See test_skip().
It also has two further methods that let you decide if network tests should be run, and if debugging information should be printed. See test_network() and test_debug().
Finally, it presents a consistent way of getting the path to input and output files. See test_input_file(), test_output_file() and test_output_dir().
AUTHOR Sendu Bala
Chris Fields
test_begin
Title : test_begin
Usage : test_begin(-tests => 20);
Function: Begin your test script, setting up the plan (skip all tests, or run
them all)
Returns : True if tests should be run.
Args : -tests => int (REQUIRED, the number of tests that will
be run)
-requires_modules => [] (array ref of module names that are
required; if any don't load, all tests
will be skipped. To specify a required
version of a module, include the version
number after the module name, separated
by a space)
-requires_module => str (as above, but for just one module)
-requires_networking => 1|0 (default 0, if true all tests will be
skipped if network tests haven't been
enabled in Build.PL)
-requires_email => 1 (if true the desired number of tests will
be skipped if either network tests
haven't been enabled in Build.PL or an
email hasn't been entered)
-excludes_os => str (default none, if OS supplied, all tests
will skip if running on that OS (eg.
'mswin'))
-framework => str (default 'Test::Most', the Test module
to load. NB: experimental, avoid using)
Note, supplying -tests => 0 is possible, allowing you to skip all
tests in the case that a test script is testing deprecated modules
that have yet to be removed from the distributiontest_skip
Title : test_skip
Usage : SKIP: {
test_skip(-tests => 10,
-requires_module => 'Optional::Module 2.01');
# 10 tests that need v2.01 of Optional::Module
}
Function: Skip a subset of tests for one of several common reasons: missing one
or more optional modules, network tests haven't been enabled, a
required binary isn't present, or an environmental variable isn't set
Returns : n/a
Args : -tests => int (REQUIRED, the number of tests that are
to be skipped in the event one of the
following options isn't satisfied)
-requires_modules => [] (array ref of module names that are
required; if any don't load, the desired
number of tests will be skipped. To
specify a required version of a module,
include the version number after the
module name, separated by a space)
-requires_module => str (as above, but for just one module)
-requires_executable => Bio::Tools::Run::WrapperBase instance
(checks WrapperBase::executable for the
presence of a binary, skips if absent)
-requires_env => str (checks %ENV for a specific env. variable,
skips if absent)
-excludes_os => str (default none, if OS supplied, desired num
of tests will skip if running on that OS
(eg. 'mswin'))
-requires_networking => 1 (if true the desired number of tests will
be skipped if network tests haven't been
enabled in Build.PL)
-requires_email => 1 (if true the desired number of tests will
be skipped if either network tests
haven't been enabled in Build.PL or an
email hasn't been entered)test_output_file
Title : test_output_file
Usage : my $output_file = test_output_file();
Function: Get the full path of a file suitable for writing to.
When your test script ends, the file will be automatically deleted.
Returns : string (file path)
Args : nonetest_output_dir
Title : test_output_dir
Usage : my $output_dir = test_output_dir();
Function: Get the full path of a directory suitable for storing temporary files
in.
When your test script ends, the directory and its contents will be
automatically deleted.
Returns : string (path)
Args : nonetest_input_file
Title : test_input_file
Usage : my $input_file = test_input_file();
Function: Get the path of a desired input file stored in the standard location
(currently t/data), but correct for all platforms.
Returns : string (file path)
Args : list of strings (ie. at least the input filename, preceded by the
names of any subdirectories within t/data)
eg. for the file t/data/in.file pass 'in.file', for the file
t/data/subdir/in.file, pass ('subdir', 'in.file')test_network
Title : test_network
Usage : my $do_network_tests = test_network();
Function: Ask if network tests should be run.
Returns : boolean
Args : nonetest_email
Title : test_email
Usage : my $do_network_tests = test_email();
Function: Ask if email address provided
Returns : boolean
Args : nonetest_debug
Title : test_debug
Usage : my $output_debugging = test_debug();
Function: Ask if debugging information should be output.
Returns : boolean
Args : nonefloat_is
Title : float_is
Usage : float_is($val1, $val2);
Function: test two floating point values for equality
Returns : Boolean based on test (can use in combination with diag)
Args : two scalar values (floating point numbers) (required via prototype)
test message (optional)_skip
Decide if should skip and generate skip message