The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
BioPerl-1.7.8
River stage two • 60 direct dependents • 65 total dependents
/ Bio::Root::Test

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 distribution

test_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    : none

test_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    : none

test_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    : none

test_email

Title   : test_email
Usage   : my $do_network_tests = test_email();
Function: Ask if email address provided
Returns : boolean
Args    : none

test_debug

Title   : test_debug
Usage   : my $output_debugging = test_debug();
Function: Ask if debugging information should be output.
Returns : boolean
Args    : none

float_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

_check_module