Bio::Root::Test(3pm)

💖 Bio::Root::Test 💖

okay bestie, you've found the manual for Bio::Root::Test — it's the common base for all BioPerl test scripts. No cap. Let's get into it. 💅

---

✨ 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 is the common base for every BioPerl test script. It safely handles loading Test::Most, which is itself a simple wrapper around several highly used test modules: Test::More, Test::Exception, Test::Warn, Test::Deep, and Test::Diff. It also gives you an interface for common needs like skipping all tests if required modules aren't present or if network tests haven't been enabled. See test_begin().

Same energy: it lets you skip just a subset of tests for those same reasons, plus 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

---

This page came from perl v5.32.1, dated 2021-08-15, and it's Bio::Root::Test(3pm). Byeeee, bestie 💖✨