.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::Root::Test 3pm"
.TH Bio::Root::Test 3pm "2012-03-02" "perl v5.14.2" "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 \- A 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();
\&
\&  # carry out tests with Test::More, Test::Exception and Test::Warn 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::More, Test::Exception and Test::Warn (actually, a subclass
compatible with Bioperl warnings) prior to tests being run. 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 \fItest_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 \fItest_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 \fItest_network()\fR and
\&\fItest_debug()\fR.
.PP
Finally, it presents a consistent way of getting the path to input and output
files. See \fItest_input_file()\fR, \fItest_output_file()\fR and \fItest_output_dir()\fR.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to
the Bioperl mailing list.  Your participation is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and 
reponsive experts will be able look at the problem and quickly 
address it. Please include a thorough description of the problem 
with code and data examples if at all possible.
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
of the bugs and their resolution. Bug reports can be submitted via
the web:
.PP
.Vb 1
\&  https://redmine.open\-bio.org/projects/bioperl/
.Ve
.SH "AUTHOR \- Sendu Bala"
.IX Header "AUTHOR - Sendu Bala"
Email bix@sendu.me.uk
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.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 suppied, all tests
\&                                        will skip if running on that OS (eg.
\&                                        \*(Aqmswin\*(Aq))
\&           \-framework           => str (default \*(AqTest::More\*(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 4
\& 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 suppied, 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