.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Root::Test 3pm"
.TH Bio::Root::Test 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Root::Test \- common base for all BioPerl test scripts
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use lib \*(Aq.\*(Aq; # (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 => \*(AqOptional::Module 2.6\*(Aq);
\&    use_ok(\*(AqOptional::Module\*(Aq);
\&
\&    # 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\*(Aqt 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(\*(Aqinput_file.txt\*(Aq);
\&
\&  # 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();
.Ve
.SH "DESCRIPTION"
.IX Header "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
\&\fBtest_begin()\fR.
.PP
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 \fBtest_skip()\fR.
.PP
It also has two further methods that let you decide if network tests should be
run, and if debugging information should be printed. See \fBtest_network()\fR and
\&\fBtest_debug()\fR.
.PP
Finally, it presents a consistent way of getting the path to input and output
files. See \fBtest_input_file()\fR, \fBtest_output_file()\fR and \fBtest_output_dir()\fR.
.SH "AUTHOR Sendu Bala"
.IX Header "AUTHOR Sendu Bala"
Chris Fields
.SS "test_begin"
.IX Subsection "test_begin"
.Vb 10
\& 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\*(Aqt 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\*(Aqt been
\&                                        enabled in Build.PL)
\&           \-requires_email      => 1   (if true the desired number of tests will
\&                                        be skipped if either network tests
\&                                        haven\*(Aqt been enabled in Build.PL or an
\&                                        email hasn\*(Aqt been entered)
\&           \-excludes_os         => str (default none, if OS supplied, all tests
\&                                        will skip if running on that OS (eg.
\&                                        \*(Aqmswin\*(Aq))
\&           \-framework           => str (default \*(AqTest::Most\*(Aq, 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
.Ve
.SS "test_skip"
.IX Subsection "test_skip"
.Vb 10
\& Title   : test_skip
\& Usage   : SKIP: {
\&                   test_skip(\-tests => 10,
\&                             \-requires_module => \*(AqOptional::Module 2.01\*(Aq);
\&                   # 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\*(Aqt been enabled, a
\&           required binary isn\*(Aqt present, or an environmental variable isn\*(Aqt 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\*(Aqt satisfied)
\&           \-requires_modules    => []  (array ref of module names that are
\&                                        required; if any don\*(Aqt 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. \*(Aqmswin\*(Aq))
\&           \-requires_networking => 1   (if true the desired number of tests will
\&                                        be skipped if network tests haven\*(Aqt been
\&                                        enabled in Build.PL)
\&           \-requires_email      => 1   (if true the desired number of tests will
\&                                        be skipped if either network tests
\&                                        haven\*(Aqt been enabled in Build.PL or an
\&                                        email hasn\*(Aqt been entered)
.Ve
.SS "test_output_file"
.IX Subsection "test_output_file"
.Vb 6
\& 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
.Ve
.SS "test_output_dir"
.IX Subsection "test_output_dir"
.Vb 8
\& 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
.Ve
.SS "test_input_file"
.IX Subsection "test_input_file"
.Vb 9
\& 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 \*(Aqin.file\*(Aq, for the file
\&           t/data/subdir/in.file, pass (\*(Aqsubdir\*(Aq, \*(Aqin.file\*(Aq)
.Ve
.SS "test_network"
.IX Subsection "test_network"
.Vb 5
\& Title   : test_network
\& Usage   : my $do_network_tests = test_network();
\& Function: Ask if network tests should be run.
\& Returns : boolean
\& Args    : none
.Ve
.SS "test_email"
.IX Subsection "test_email"
.Vb 5
\& Title   : test_email
\& Usage   : my $do_network_tests = test_email();
\& Function: Ask if email address provided
\& Returns : boolean
\& Args    : none
.Ve
.SS "test_debug"
.IX Subsection "test_debug"
.Vb 5
\& Title   : test_debug
\& Usage   : my $output_debugging = test_debug();
\& Function: Ask if debugging information should be output.
\& Returns : boolean
\& Args    : none
.Ve
.SS "float_is"
.IX Subsection "float_is"
.Vb 6
\& 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)
.Ve
.SS "_skip"
.IX Subsection "_skip"
Decide if should skip and generate skip message
.SS "_check_module"
.IX Subsection "_check_module"