Provided by: libbio-perl-perl_1.7.8-1_all bug

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