--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.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. | will give a
+.\" real vertical bar. \*(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-|\(bv\*(Tr
+.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\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" 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 "Test::More 3"
+.TH Test::More 3 "2009-09-02" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Test::More \- yet another framework for writing test scripts
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 5
+\& use Test::More tests => 23;
+\& # or
+\& use Test::More skip_all => $reason;
+\& # or
+\& use Test::More; # see done_testing()
+.Ve
+.PP
+.Vb 2
+\& BEGIN { use_ok( 'Some::Module' ); }
+\& require_ok( 'Some::Module' );
+.Ve
+.PP
+.Vb 2
+\& # Various ways to say "ok"
+\& ok($got eq $expected, $test_name);
+.Ve
+.PP
+.Vb 2
+\& is ($got, $expected, $test_name);
+\& isnt($got, $expected, $test_name);
+.Ve
+.PP
+.Vb 2
+\& # Rather than print STDERR "# here's what went wrong\en"
+\& diag("here's what went wrong");
+.Ve
+.PP
+.Vb 2
+\& like ($got, qr/expected/, $test_name);
+\& unlike($got, qr/expected/, $test_name);
+.Ve
+.PP
+.Vb 1
+\& cmp_ok($got, '==', $expected, $test_name);
+.Ve
+.PP
+.Vb 1
+\& is_deeply($got_complex_structure, $expected_complex_structure, $test_name);
+.Ve
+.PP
+.Vb 2
+\& SKIP: {
+\& skip $why, $how_many unless $have_some_feature;
+.Ve
+.PP
+.Vb 3
+\& ok( foo(), $test_name );
+\& is( foo(42), 23, $test_name );
+\& };
+.Ve
+.PP
+.Vb 2
+\& TODO: {
+\& local $TODO = $why;
+.Ve
+.PP
+.Vb 3
+\& ok( foo(), $test_name );
+\& is( foo(42), 23, $test_name );
+\& };
+.Ve
+.PP
+.Vb 2
+\& can_ok($module, @methods);
+\& isa_ok($object, $class);
+.Ve
+.PP
+.Vb 2
+\& pass($test_name);
+\& fail($test_name);
+.Ve
+.PP
+.Vb 1
+\& BAIL_OUT($why);
+.Ve
+.PP
+.Vb 2
+\& # UNIMPLEMENTED!!!
+\& my @status = Test::More::status;
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fB\s-1STOP\s0!\fR If you're just getting started writing tests, have a look at
+Test::Simple first. This is a drop in replacement for Test::Simple
+which you can switch to once you get the hang of basic testing.
+.PP
+The purpose of this module is to provide a wide range of testing
+utilities. Various ways to say \*(L"ok\*(R" with better diagnostics,
+facilities to skip tests, test future features and compare complicated
+data structures. While you can do almost anything with a simple
+\&\f(CW\*(C`ok()\*(C'\fR function, it doesn't provide good diagnostic output.
+.Sh "I love it when a plan comes together"
+.IX Subsection "I love it when a plan comes together"
+Before anything else, you need a testing plan. This basically declares
+how many tests your script is going to run to protect against premature
+failure.
+.PP
+The preferred way to do this is to declare a plan when you \f(CW\*(C`use Test::More\*(C'\fR.
+.PP
+.Vb 1
+\& use Test::More tests => 23;
+.Ve
+.PP
+There are cases when you will not know beforehand how many tests your
+script is going to run. In this case, you can declare your tests at
+the end.
+.PP
+.Vb 1
+\& use Test::More;
+.Ve
+.PP
+.Vb 1
+\& ... run your tests ...
+.Ve
+.PP
+.Vb 1
+\& done_testing( $number_of_tests_run );
+.Ve
+.PP
+Sometimes you really don't know how many tests were run, or it's too
+difficult to calculate. In which case you can leave off
+\&\f(CW$number_of_tests_run\fR.
+.PP
+In some cases, you'll want to completely skip an entire testing script.
+.PP
+.Vb 1
+\& use Test::More skip_all => $skip_reason;
+.Ve
+.PP
+Your script will declare a skip with the reason why you skipped and
+exit immediately with a zero (success). See Test::Harness for
+details.
+.PP
+If you want to control what functions Test::More will export, you
+have to use the 'import' option. For example, to import everything
+but 'fail', you'd do:
+.PP
+.Vb 1
+\& use Test::More tests => 23, import => ['!fail'];
+.Ve
+.PP
+Alternatively, you can use the \fIplan()\fR function. Useful for when you
+have to calculate the number of tests.
+.PP
+.Vb 2
+\& use Test::More;
+\& plan tests => keys %Stuff * 3;
+.Ve
+.PP
+or for deciding between running the tests at all:
+.PP
+.Vb 7
+\& use Test::More;
+\& if( $^O eq 'MacOS' ) {
+\& plan skip_all => 'Test irrelevant on MacOS';
+\& }
+\& else {
+\& plan tests => 42;
+\& }
+.Ve
+.IP "\fBdone_testing\fR" 4
+.IX Item "done_testing"
+.Vb 2
+\& done_testing();
+\& done_testing($number_of_tests);
+.Ve
+.Sp
+If you don't know how many tests you're going to run, you can issue
+the plan when you're done running tests.
+.Sp
+$number_of_tests is the same as \fIplan()\fR, it's the number of tests you
+expected to run. You can omit this, in which case the number of tests
+you ran doesn't matter, just the fact that your tests ran to
+conclusion.
+.Sp
+This is safer than and replaces the \*(L"no_plan\*(R" plan.
+.Sh "Test names"
+.IX Subsection "Test names"
+By convention, each test is assigned a number in order. This is
+largely done automatically for you. However, it's often very useful to
+assign a name to each test. Which would you rather see:
+.PP
+.Vb 3
+\& ok 4
+\& not ok 5
+\& ok 6
+.Ve
+.PP
+or
+.PP
+.Vb 3
+\& ok 4 \- basic multi\-variable
+\& not ok 5 \- simple exponential
+\& ok 6 \- force == mass * acceleration
+.Ve
+.PP
+The later gives you some idea of what failed. It also makes it easier
+to find the test in your script, simply search for \*(L"simple
+exponential\*(R".
+.PP
+All test functions take a name argument. It's optional, but highly
+suggested that you use it.
+.Sh "I'm ok, you're not ok."
+.IX Subsection "I'm ok, you're not ok."
+The basic purpose of this module is to print out either \*(L"ok #\*(R" or \*(L"not
+ok #\*(R" depending on if a given test succeeded or failed. Everything
+else is just gravy.
+.PP
+All of the following print \*(L"ok\*(R" or \*(L"not ok\*(R" depending on if the test
+succeeded or failed. They all also return true or false,
+respectively.
+.IP "\fBok\fR" 4
+.IX Item "ok"
+.Vb 1
+\& ok($got eq $expected, $test_name);
+.Ve
+.Sp
+This simply evaluates any expression (\f(CW\*(C`$got eq $expected\*(C'\fR is just a
+simple example) and uses that to determine if the test succeeded or
+failed. A true expression passes, a false one fails. Very simple.
+.Sp
+For example:
+.Sp
+.Vb 4
+\& ok( $exp{9} == 81, 'simple exponential' );
+\& ok( Film\->can('db_Main'), 'set_db()' );
+\& ok( $p\->tests == 4, 'saw tests' );
+\& ok( !grep !defined $_, @items, 'items populated' );
+.Ve
+.Sp
+(Mnemonic: \*(L"This is ok.\*(R")
+.Sp
+$test_name is a very short description of the test that will be printed
+out. It makes it very easy to find a test in your script when it fails
+and gives others an idea of your intentions. \f(CW$test_name\fR is optional,
+but we \fBvery\fR strongly encourage its use.
+.Sp
+Should an \fIok()\fR fail, it will produce some diagnostics:
+.Sp
+.Vb 3
+\& not ok 18 \- sufficient mucus
+\& # Failed test 'sufficient mucus'
+\& # in foo.t at line 42.
+.Ve
+.Sp
+This is the same as Test::Simple's \fIok()\fR routine.
+.IP "\fBis\fR" 4
+.IX Item "is"
+.PD 0
+.IP "\fBisnt\fR" 4
+.IX Item "isnt"
+.PD
+.Vb 2
+\& is ( $got, $expected, $test_name );
+\& isnt( $got, $expected, $test_name );
+.Ve
+.Sp
+Similar to \fIok()\fR, \fIis()\fR and \fIisnt()\fR compare their two arguments
+with \f(CW\*(C`eq\*(C'\fR and \f(CW\*(C`ne\*(C'\fR respectively and use the result of that to
+determine if the test succeeded or failed. So these:
+.Sp
+.Vb 2
+\& # Is the ultimate answer 42?
+\& is( ultimate_answer(), 42, "Meaning of Life" );
+.Ve
+.Sp
+.Vb 2
+\& # $foo isn't empty
+\& isnt( $foo, '', "Got some foo" );
+.Ve
+.Sp
+are similar to these:
+.Sp
+.Vb 2
+\& ok( ultimate_answer() eq 42, "Meaning of Life" );
+\& ok( $foo ne '', "Got some foo" );
+.Ve
+.Sp
+(Mnemonic: \*(L"This is that.\*(R" \*(L"This isn't that.\*(R")
+.Sp
+So why use these? They produce better diagnostics on failure. \fIok()\fR
+cannot know what you are testing for (beyond the name), but \fIis()\fR and
+\&\fIisnt()\fR know what the test was and why it failed. For example this
+test:
+.Sp
+.Vb 2
+\& my $foo = 'waffle'; my $bar = 'yarblokos';
+\& is( $foo, $bar, 'Is foo the same as bar?' );
+.Ve
+.Sp
+Will produce something like this:
+.Sp
+.Vb 5
+\& not ok 17 \- Is foo the same as bar?
+\& # Failed test 'Is foo the same as bar?'
+\& # in foo.t at line 139.
+\& # got: 'waffle'
+\& # expected: 'yarblokos'
+.Ve
+.Sp
+So you can figure out what went wrong without rerunning the test.
+.Sp
+You are encouraged to use \fIis()\fR and \fIisnt()\fR over \fIok()\fR where possible,
+however do not be tempted to use them to find out if something is
+true or false!
+.Sp
+.Vb 2
+\& # XXX BAD!
+\& is( exists $brooklyn{tree}, 1, 'A tree grows in Brooklyn' );
+.Ve
+.Sp
+This does not check if \f(CW\*(C`exists $brooklyn{tree}\*(C'\fR is true, it checks if
+it returns 1. Very different. Similar caveats exist for false and 0.
+In these cases, use \fIok()\fR.
+.Sp
+.Vb 1
+\& ok( exists $brooklyn{tree}, 'A tree grows in Brooklyn' );
+.Ve
+.Sp
+A simple call to \fIisnt()\fR usually does not provide a strong test but there
+are cases when you cannot say much more about a value than that it is
+different from some other value:
+.Sp
+.Vb 1
+\& new_ok $obj, "Foo";
+.Ve
+.Sp
+.Vb 2
+\& my $clone = $obj\->clone;
+\& isa_ok $obj, "Foo", "Foo\->clone";
+.Ve
+.Sp
+.Vb 1
+\& isnt $obj, $clone, "clone() produces a different object";
+.Ve
+.Sp
+For those grammatical pedants out there, there's an \f(CW\*(C`isn't()\*(C'\fR
+function which is an alias of \fIisnt()\fR.
+.IP "\fBlike\fR" 4
+.IX Item "like"
+.Vb 1
+\& like( $got, qr/expected/, $test_name );
+.Ve
+.Sp
+Similar to \fIok()\fR, \fIlike()\fR matches \f(CW$got\fR against the regex \f(CW\*(C`qr/expected/\*(C'\fR.
+.Sp
+So this:
+.Sp
+.Vb 1
+\& like($got, qr/expected/, 'this is like that');
+.Ve
+.Sp
+is similar to:
+.Sp
+.Vb 1
+\& ok( $got =~ /expected/, 'this is like that');
+.Ve
+.Sp
+(Mnemonic \*(L"This is like that\*(R".)
+.Sp
+The second argument is a regular expression. It may be given as a
+regex reference (i.e. \f(CW\*(C`qr//\*(C'\fR) or (for better compatibility with older
+perls) as a string that looks like a regex (alternative delimiters are
+currently not supported):
+.Sp
+.Vb 1
+\& like( $got, '/expected/', 'this is like that' );
+.Ve
+.Sp
+Regex options may be placed on the end (\f(CW'/expected/i'\fR).
+.Sp
+Its advantages over \fIok()\fR are similar to that of \fIis()\fR and \fIisnt()\fR. Better
+diagnostics on failure.
+.IP "\fBunlike\fR" 4
+.IX Item "unlike"
+.Vb 1
+\& unlike( $got, qr/expected/, $test_name );
+.Ve
+.Sp
+Works exactly as \fIlike()\fR, only it checks if \f(CW$got\fR \fBdoes not\fR match the
+given pattern.
+.IP "\fBcmp_ok\fR" 4
+.IX Item "cmp_ok"
+.Vb 1
+\& cmp_ok( $got, $op, $expected, $test_name );
+.Ve
+.Sp
+Halfway between \fIok()\fR and \fIis()\fR lies \fIcmp_ok()\fR. This allows you to
+compare two arguments using any binary perl operator.
+.Sp
+.Vb 2
+\& # ok( $got eq $expected );
+\& cmp_ok( $got, 'eq', $expected, 'this eq that' );
+.Ve
+.Sp
+.Vb 2
+\& # ok( $got == $expected );
+\& cmp_ok( $got, '==', $expected, 'this == that' );
+.Ve
+.Sp
+.Vb 3
+\& # ok( $got && $expected );
+\& cmp_ok( $got, '&&', $expected, 'this && that' );
+\& ...etc...
+.Ve
+.Sp
+Its advantage over \fIok()\fR is when the test fails you'll know what \f(CW$got\fR
+and \f(CW$expected\fR were:
+.Sp
+.Vb 5
+\& not ok 1
+\& # Failed test in foo.t at line 12.
+\& # '23'
+\& # &&
+\& # undef
+.Ve
+.Sp
+It's also useful in those cases where you are comparing numbers and
+\&\fIis()\fR's use of \f(CW\*(C`eq\*(C'\fR will interfere:
+.Sp
+.Vb 1
+\& cmp_ok( $big_hairy_number, '==', $another_big_hairy_number );
+.Ve
+.Sp
+It's especially useful when comparing greater-than or smaller-than
+relation between values:
+.Sp
+.Vb 1
+\& cmp_ok( $some_value, '<=', $upper_limit );
+.Ve
+.IP "\fBcan_ok\fR" 4
+.IX Item "can_ok"
+.Vb 2
+\& can_ok($module, @methods);
+\& can_ok($object, @methods);
+.Ve
+.Sp
+Checks to make sure the \f(CW$module\fR or \f(CW$object\fR can do these \f(CW@methods\fR
+(works with functions, too).
+.Sp
+.Vb 1
+\& can_ok('Foo', qw(this that whatever));
+.Ve
+.Sp
+is almost exactly like saying:
+.Sp
+.Vb 4
+\& ok( Foo\->can('this') &&
+\& Foo\->can('that') &&
+\& Foo\->can('whatever')
+\& );
+.Ve
+.Sp
+only without all the typing and with a better interface. Handy for
+quickly testing an interface.
+.Sp
+No matter how many \f(CW@methods\fR you check, a single \fIcan_ok()\fR call counts
+as one test. If you desire otherwise, use:
+.Sp
+.Vb 3
+\& foreach my $meth (@methods) {
+\& can_ok('Foo', $meth);
+\& }
+.Ve
+.IP "\fBisa_ok\fR" 4
+.IX Item "isa_ok"
+.Vb 3
+\& isa_ok($object, $class, $object_name);
+\& isa_ok($subclass, $class, $object_name);
+\& isa_ok($ref, $type, $ref_name);
+.Ve
+.Sp
+Checks to see if the given \f(CW\*(C`$object\->isa($class)\*(C'\fR. Also checks to make
+sure the object was defined in the first place. Handy for this sort
+of thing:
+.Sp
+.Vb 2
+\& my $obj = Some::Module\->new;
+\& isa_ok( $obj, 'Some::Module' );
+.Ve
+.Sp
+where you'd otherwise have to write
+.Sp
+.Vb 2
+\& my $obj = Some::Module\->new;
+\& ok( defined $obj && $obj\->isa('Some::Module') );
+.Ve
+.Sp
+to safeguard against your test script blowing up.
+.Sp
+You can also test a class, to make sure that it has the right ancestor:
+.Sp
+.Vb 1
+\& isa_ok( 'Vole', 'Rodent' );
+.Ve
+.Sp
+It works on references, too:
+.Sp
+.Vb 1
+\& isa_ok( $array_ref, 'ARRAY' );
+.Ve
+.Sp
+The diagnostics of this test normally just refer to 'the object'. If
+you'd like them to be more specific, you can supply an \f(CW$object_name\fR
+(for example 'Test customer').
+.IP "\fBnew_ok\fR" 4
+.IX Item "new_ok"
+.Vb 3
+\& my $obj = new_ok( $class );
+\& my $obj = new_ok( $class => \e@args );
+\& my $obj = new_ok( $class => \e@args, $object_name );
+.Ve
+.Sp
+A convenience function which combines creating an object and calling
+\&\fIisa_ok()\fR on that object.
+.Sp
+It is basically equivalent to:
+.Sp
+.Vb 2
+\& my $obj = $class\->new(@args);
+\& isa_ok $obj, $class, $object_name;
+.Ve
+.Sp
+If \f(CW@args\fR is not given, an empty list will be used.
+.Sp
+This function only works on \fInew()\fR and it assumes \fInew()\fR will return
+just a single object which isa \f(CW$class\fR.
+.IP "\fBsubtest\fR" 4
+.IX Item "subtest"
+.Vb 1
+\& subtest $name => \e&code;
+.Ve
+.Sp
+\&\fIsubtest()\fR runs the &code as its own little test with its own plan and
+its own result. The main test counts this as a single test using the
+result of the whole subtest to determine if its ok or not ok.
+.Sp
+For example...
+.Sp
+.Vb 1
+\& use Test::More tests => 3;
+.Ve
+.Sp
+.Vb 1
+\& pass("First test");
+.Ve
+.Sp
+.Vb 2
+\& subtest 'An example subtest' => sub {
+\& plan tests => 2;
+.Ve
+.Sp
+.Vb 3
+\& pass("This is a subtest");
+\& pass("So is this");
+\& };
+.Ve
+.Sp
+.Vb 1
+\& pass("Third test");
+.Ve
+.Sp
+This would produce.
+.Sp
+.Vb 7
+\& 1..3
+\& ok 1 \- First test
+\& 1..2
+\& ok 1 \- This is a subtest
+\& ok 2 \- So is this
+\& ok 2 \- An example subtest
+\& ok 3 \- Third test
+.Ve
+.Sp
+A subtest may call \*(L"skip_all\*(R". No tests will be run, but the subtest is
+considered a skip.
+.Sp
+.Vb 4
+\& subtest 'skippy' => sub {
+\& plan skip_all => 'cuz I said so';
+\& pass('this test will never be run');
+\& };
+.Ve
+.Sp
+Returns true if the subtest passed, false otherwise.
+.IP "\fBpass\fR" 4
+.IX Item "pass"
+.PD 0
+.IP "\fBfail\fR" 4
+.IX Item "fail"
+.PD
+.Vb 2
+\& pass($test_name);
+\& fail($test_name);
+.Ve
+.Sp
+Sometimes you just want to say that the tests have passed. Usually
+the case is you've got some complicated condition that is difficult to
+wedge into an \fIok()\fR. In this case, you can simply use \fIpass()\fR (to
+declare the test ok) or fail (for not ok). They are synonyms for
+\&\fIok\fR\|(1) and \fIok\fR\|(0).
+.Sp
+Use these very, very, very sparingly.
+.Sh "Module tests"
+.IX Subsection "Module tests"
+You usually want to test if the module you're testing loads ok, rather
+than just vomiting if its load fails. For such purposes we have
+\&\f(CW\*(C`use_ok\*(C'\fR and \f(CW\*(C`require_ok\*(C'\fR.
+.IP "\fBuse_ok\fR" 4
+.IX Item "use_ok"
+.Vb 2
+\& BEGIN { use_ok($module); }
+\& BEGIN { use_ok($module, @imports); }
+.Ve
+.Sp
+These simply use the given \f(CW$module\fR and test to make sure the load
+happened ok. It's recommended that you run \fIuse_ok()\fR inside a \s-1BEGIN\s0
+block so its functions are exported at compile-time and prototypes are
+properly honored.
+.Sp
+If \f(CW@imports\fR are given, they are passed through to the use. So this:
+.Sp
+.Vb 1
+\& BEGIN { use_ok('Some::Module', qw(foo bar)) }
+.Ve
+.Sp
+is like doing this:
+.Sp
+.Vb 1
+\& use Some::Module qw(foo bar);
+.Ve
+.Sp
+Version numbers can be checked like so:
+.Sp
+.Vb 2
+\& # Just like "use Some::Module 1.02"
+\& BEGIN { use_ok('Some::Module', 1.02) }
+.Ve
+.Sp
+Don't try to do this:
+.Sp
+.Vb 2
+\& BEGIN {
+\& use_ok('Some::Module');
+.Ve
+.Sp
+.Vb 3
+\& ...some code that depends on the use...
+\& ...happening at compile time...
+\& }
+.Ve
+.Sp
+because the notion of \*(L"compile\-time\*(R" is relative. Instead, you want:
+.Sp
+.Vb 2
+\& BEGIN { use_ok('Some::Module') }
+\& BEGIN { ...some code that depends on the use... }
+.Ve
+.IP "\fBrequire_ok\fR" 4
+.IX Item "require_ok"
+.Vb 2
+\& require_ok($module);
+\& require_ok($file);
+.Ve
+.Sp
+Like \fIuse_ok()\fR, except it requires the \f(CW$module\fR or \f(CW$file\fR.
+.Sh "Complex data structures"
+.IX Subsection "Complex data structures"
+Not everything is a simple eq check or regex. There are times you
+need to see if two data structures are equivalent. For these
+instances Test::More provides a handful of useful functions.
+.PP
+\&\fB\s-1NOTE\s0\fR I'm not quite sure what will happen with filehandles.
+.IP "\fBis_deeply\fR" 4
+.IX Item "is_deeply"
+.Vb 1
+\& is_deeply( $got, $expected, $test_name );
+.Ve
+.Sp
+Similar to \fIis()\fR, except that if \f(CW$got\fR and \f(CW$expected\fR are references, it
+does a deep comparison walking each data structure to see if they are
+equivalent. If the two structures are different, it will display the
+place where they start differing.
+.Sp
+\&\fIis_deeply()\fR compares the dereferenced values of references, the
+references themselves (except for their type) are ignored. This means
+aspects such as blessing and ties are not considered \*(L"different\*(R".
+.Sp
+\&\fIis_deeply()\fR currently has very limited handling of function reference
+and globs. It merely checks if they have the same referent. This may
+improve in the future.
+.Sp
+Test::Differences and Test::Deep provide more in-depth functionality
+along these lines.
+.Sh "Diagnostics"
+.IX Subsection "Diagnostics"
+If you pick the right test function, you'll usually get a good idea of
+what went wrong when it failed. But sometimes it doesn't work out
+that way. So here we have ways for you to write your own diagnostic
+messages which are safer than just \f(CW\*(C`print STDERR\*(C'\fR.
+.IP "\fBdiag\fR" 4
+.IX Item "diag"
+.Vb 1
+\& diag(@diagnostic_message);
+.Ve
+.Sp
+Prints a diagnostic message which is guaranteed not to interfere with
+test output. Like \f(CW\*(C`print\*(C'\fR \f(CW@diagnostic_message\fR is simply concatenated
+together.
+.Sp
+Returns false, so as to preserve failure.
+.Sp
+Handy for this sort of thing:
+.Sp
+.Vb 2
+\& ok( grep(/foo/, @users), "There's a foo user" ) or
+\& diag("Since there's no foo, check that /etc/bar is set up right");
+.Ve
+.Sp
+which would produce:
+.Sp
+.Vb 4
+\& not ok 42 \- There's a foo user
+\& # Failed test 'There's a foo user'
+\& # in foo.t at line 52.
+\& # Since there's no foo, check that /etc/bar is set up right.
+.Ve
+.Sp
+You might remember \f(CW\*(C`ok() or diag()\*(C'\fR with the mnemonic \f(CW\*(C`open() or
+die()\*(C'\fR.
+.Sp
+\&\fB\s-1NOTE\s0\fR The exact formatting of the diagnostic output is still
+changing, but it is guaranteed that whatever you throw at it it won't
+interfere with the test.
+.IP "\fBnote\fR" 4
+.IX Item "note"
+.Vb 1
+\& note(@diagnostic_message);
+.Ve
+.Sp
+Like \fIdiag()\fR, except the message will not be seen when the test is run
+in a harness. It will only be visible in the verbose \s-1TAP\s0 stream.
+.Sp
+Handy for putting in notes which might be useful for debugging, but
+don't indicate a problem.
+.Sp
+.Vb 1
+\& note("Tempfile is $tempfile");
+.Ve
+.IP "\fBexplain\fR" 4
+.IX Item "explain"
+.Vb 1
+\& my @dump = explain @diagnostic_message;
+.Ve
+.Sp
+Will dump the contents of any references in a human readable format.
+Usually you want to pass this into \f(CW\*(C`note\*(C'\fR or \f(CW\*(C`diag\*(C'\fR.
+.Sp
+Handy for things like...
+.Sp
+.Vb 1
+\& is_deeply($have, $want) || diag explain $have;
+.Ve
+.Sp
+or
+.Sp
+.Vb 2
+\& note explain \e%args;
+\& Some::Class\->method(%args);
+.Ve
+.Sh "Conditional tests"
+.IX Subsection "Conditional tests"
+Sometimes running a test under certain conditions will cause the
+test script to die. A certain function or method isn't implemented
+(such as \fIfork()\fR on MacOS), some resource isn't available (like a
+net connection) or a module isn't available. In these cases it's
+necessary to skip tests, or declare that they are supposed to fail
+but will work in the future (a todo test).
+.PP
+For more details on the mechanics of skip and todo tests see
+Test::Harness.
+.PP
+The way Test::More handles this is with a named block. Basically, a
+block of tests which can be skipped over or made todo. It's best if I
+just show you...
+.IP "\fB\s-1SKIP:\s0 \s-1BLOCK\s0\fR" 4
+.IX Item "SKIP: BLOCK"
+.Vb 2
+\& SKIP: {
+\& skip $why, $how_many if $condition;
+.Ve
+.Sp
+.Vb 2
+\& ...normal testing code goes here...
+\& }
+.Ve
+.Sp
+This declares a block of tests that might be skipped, \f(CW$how_many\fR tests
+there are, \f(CW$why\fR and under what \f(CW$condition\fR to skip them. An example is
+the easiest way to illustrate:
+.Sp
+.Vb 2
+\& SKIP: {
+\& eval { require HTML::Lint };
+.Ve
+.Sp
+.Vb 1
+\& skip "HTML::Lint not installed", 2 if $@;
+.Ve
+.Sp
+.Vb 2
+\& my $lint = new HTML::Lint;
+\& isa_ok( $lint, "HTML::Lint" );
+.Ve
+.Sp
+.Vb 3
+\& $lint\->parse( $html );
+\& is( $lint\->errors, 0, "No errors found in HTML" );
+\& }
+.Ve
+.Sp
+If the user does not have HTML::Lint installed, the whole block of
+code \fIwon't be run at all\fR. Test::More will output special ok's
+which Test::Harness interprets as skipped, but passing, tests.
+.Sp
+It's important that \f(CW$how_many\fR accurately reflects the number of tests
+in the \s-1SKIP\s0 block so the # of tests run will match up with your plan.
+If your plan is \f(CW\*(C`no_plan\*(C'\fR \f(CW$how_many\fR is optional and will default to 1.
+.Sp
+It's perfectly safe to nest \s-1SKIP\s0 blocks. Each \s-1SKIP\s0 block must have
+the label \f(CW\*(C`SKIP\*(C'\fR, or Test::More can't work its magic.
+.Sp
+You don't skip tests which are failing because there's a bug in your
+program, or for which you don't yet have code written. For that you
+use \s-1TODO\s0. Read on.
+.IP "\fB\s-1TODO:\s0 \s-1BLOCK\s0\fR" 4
+.IX Item "TODO: BLOCK"
+.Vb 2
+\& TODO: {
+\& local $TODO = $why if $condition;
+.Ve
+.Sp
+.Vb 2
+\& ...normal testing code goes here...
+\& }
+.Ve
+.Sp
+Declares a block of tests you expect to fail and \f(CW$why\fR. Perhaps it's
+because you haven't fixed a bug or haven't finished a new feature:
+.Sp
+.Vb 2
+\& TODO: {
+\& local $TODO = "URI::Geller not finished";
+.Ve
+.Sp
+.Vb 2
+\& my $card = "Eight of clubs";
+\& is( URI::Geller\->your_card, $card, 'Is THIS your card?' );
+.Ve
+.Sp
+.Vb 4
+\& my $spoon;
+\& URI::Geller\->bend_spoon;
+\& is( $spoon, 'bent', "Spoon bending, that's original" );
+\& }
+.Ve
+.Sp
+With a todo block, the tests inside are expected to fail. Test::More
+will run the tests normally, but print out special flags indicating
+they are \*(L"todo\*(R". Test::Harness will interpret failures as being ok.
+Should anything succeed, it will report it as an unexpected success.
+You then know the thing you had todo is done and can remove the
+\&\s-1TODO\s0 flag.
+.Sp
+The nice part about todo tests, as opposed to simply commenting out a
+block of tests, is it's like having a programmatic todo list. You know
+how much work is left to be done, you're aware of what bugs there are,
+and you'll know immediately when they're fixed.
+.Sp
+Once a todo test starts succeeding, simply move it outside the block.
+When the block is empty, delete it.
+.IP "\fBtodo_skip\fR" 4
+.IX Item "todo_skip"
+.Vb 2
+\& TODO: {
+\& todo_skip $why, $how_many if $condition;
+.Ve
+.Sp
+.Vb 2
+\& ...normal testing code...
+\& }
+.Ve
+.Sp
+With todo tests, it's best to have the tests actually run. That way
+you'll know when they start passing. Sometimes this isn't possible.
+Often a failing test will cause the whole program to die or hang, even
+inside an \f(CW\*(C`eval BLOCK\*(C'\fR with and using \f(CW\*(C`alarm\*(C'\fR. In these extreme
+cases you have no choice but to skip over the broken tests entirely.
+.Sp
+The syntax and behavior is similar to a \f(CW\*(C`SKIP: BLOCK\*(C'\fR except the
+tests will be marked as failing but todo. Test::Harness will
+interpret them as passing.
+.IP "When do I use \s-1SKIP\s0 vs. \s-1TODO\s0?" 4
+.IX Item "When do I use SKIP vs. TODO?"
+\&\fBIf it's something the user might not be able to do\fR, use \s-1SKIP\s0.
+This includes optional modules that aren't installed, running under
+an \s-1OS\s0 that doesn't have some feature (like \fIfork()\fR or symlinks), or maybe
+you need an Internet connection and one isn't available.
+.Sp
+\&\fBIf it's something the programmer hasn't done yet\fR, use \s-1TODO\s0. This
+is for any code you haven't written yet, or bugs you have yet to fix,
+but want to put tests in your testing script (always a good idea).
+.Sh "Test control"
+.IX Subsection "Test control"
+.IP "\fB\s-1BAIL_OUT\s0\fR" 4
+.IX Item "BAIL_OUT"
+.Vb 1
+\& BAIL_OUT($reason);
+.Ve
+.Sp
+Indicates to the harness that things are going so badly all testing
+should terminate. This includes the running any additional test scripts.
+.Sp
+This is typically used when testing cannot continue such as a critical
+module failing to compile or a necessary external utility not being
+available such as a database connection failing.
+.Sp
+The test will exit with 255.
+.Sp
+For even better control look at Test::Most.
+.Sh "Discouraged comparison functions"
+.IX Subsection "Discouraged comparison functions"
+The use of the following functions is discouraged as they are not
+actually testing functions and produce no diagnostics to help figure
+out what went wrong. They were written before \fIis_deeply()\fR existed
+because I couldn't figure out how to display a useful diff of two
+arbitrary data structures.
+.PP
+These functions are usually used inside an \fIok()\fR.
+.PP
+.Vb 1
+\& ok( eq_array(\e@got, \e@expected) );
+.Ve
+.PP
+\&\f(CW\*(C`is_deeply()\*(C'\fR can do that better and with diagnostics.
+.PP
+.Vb 1
+\& is_deeply( \e@got, \e@expected );
+.Ve
+.PP
+They may be deprecated in future versions.
+.IP "\fBeq_array\fR" 4
+.IX Item "eq_array"
+.Vb 1
+\& my $is_eq = eq_array(\e@got, \e@expected);
+.Ve
+.Sp
+Checks if two arrays are equivalent. This is a deep check, so
+multi-level structures are handled correctly.
+.IP "\fBeq_hash\fR" 4
+.IX Item "eq_hash"
+.Vb 1
+\& my $is_eq = eq_hash(\e%got, \e%expected);
+.Ve
+.Sp
+Determines if the two hashes contain the same keys and values. This
+is a deep check.
+.IP "\fBeq_set\fR" 4
+.IX Item "eq_set"
+.Vb 1
+\& my $is_eq = eq_set(\e@got, \e@expected);
+.Ve
+.Sp
+Similar to \fIeq_array()\fR, except the order of the elements is \fBnot\fR
+important. This is a deep check, but the irrelevancy of order only
+applies to the top level.
+.Sp
+.Vb 1
+\& ok( eq_set(\e@got, \e@expected) );
+.Ve
+.Sp
+Is better written:
+.Sp
+.Vb 1
+\& is_deeply( [sort @got], [sort @expected] );
+.Ve
+.Sp
+\&\fB\s-1NOTE\s0\fR By historical accident, this is not a true set comparison.
+While the order of elements does not matter, duplicate elements do.
+.Sp
+\&\fB\s-1NOTE\s0\fR \fIeq_set()\fR does not know how to deal with references at the top
+level. The following is an example of a comparison which might not work:
+.Sp
+.Vb 1
+\& eq_set([\e1, \e2], [\e2, \e1]);
+.Ve
+.Sp
+Test::Deep contains much better set comparison functions.
+.Sh "Extending and Embedding Test::More"
+.IX Subsection "Extending and Embedding Test::More"
+Sometimes the Test::More interface isn't quite enough. Fortunately,
+Test::More is built on top of Test::Builder which provides a single,
+unified backend for any test library to use. This means two test
+libraries which both use Test::Builder \fBcan be used together in the
+same program\fR.
+.PP
+If you simply want to do a little tweaking of how the tests behave,
+you can access the underlying Test::Builder object like so:
+.IP "\fBbuilder\fR" 4
+.IX Item "builder"
+.Vb 1
+\& my $test_builder = Test::More\->builder;
+.Ve
+.Sp
+Returns the Test::Builder object underlying Test::More for you to play
+with.
+.SH "EXIT CODES"
+.IX Header "EXIT CODES"
+If all your tests passed, Test::Builder will exit with zero (which is
+normal). If anything failed it will exit with how many failed. If
+you run less (or more) tests than you planned, the missing (or extras)
+will be considered failures. If no tests were ever run Test::Builder
+will throw a warning and exit with 255. If the test died, even after
+having successfully completed all its tests, it will still be
+considered a failure and will exit with 255.
+.PP
+So the exit codes are...
+.PP
+.Vb 3
+\& 0 all tests successful
+\& 255 test died or all passed but wrong # of tests run
+\& any other number how many failed (including missing or extras)
+.Ve
+.PP
+If you fail more than 254 tests, it will be reported as 254.
+.PP
+\&\fB\s-1NOTE\s0\fR This behavior may go away in future versions.
+.SH "CAVEATS and NOTES"
+.IX Header "CAVEATS and NOTES"
+.IP "Backwards compatibility" 4
+.IX Item "Backwards compatibility"
+Test::More works with Perls as old as 5.6.0.
+.ie n .IP "utf8 / ""Wide character in print""" 4
+.el .IP "utf8 / ``Wide character in print''" 4
+.IX Item "utf8 / Wide character in print"
+If you use utf8 or other non-ASCII characters with Test::More you
+might get a \*(L"Wide character in print\*(R" warning. Using \f(CW\*(C`binmode
+STDOUT, ":utf8"\*(C'\fR will not fix it. Test::Builder (which powers
+Test::More) duplicates \s-1STDOUT\s0 and \s-1STDERR\s0. So any changes to them,
+including changing their output disciplines, will not be seem by
+Test::More.
+.Sp
+The work around is to change the filehandles used by Test::Builder
+directly.
+.Sp
+.Vb 4
+\& my $builder = Test::More\->builder;
+\& binmode $builder\->output, ":utf8";
+\& binmode $builder\->failure_output, ":utf8";
+\& binmode $builder\->todo_output, ":utf8";
+.Ve
+.IP "Overloaded objects" 4
+.IX Item "Overloaded objects"
+String overloaded objects are compared \fBas strings\fR (or in \fIcmp_ok()\fR's
+case, strings or numbers as appropriate to the comparison op). This
+prevents Test::More from piercing an object's interface allowing
+better blackbox testing. So if a function starts returning overloaded
+objects instead of bare strings your tests won't notice the
+difference. This is good.
+.Sp
+However, it does mean that functions like \fIis_deeply()\fR cannot be used to
+test the internals of string overloaded objects. In this case I would
+suggest Test::Deep which contains more flexible testing functions for
+complex data structures.
+.IP "Threads" 4
+.IX Item "Threads"
+Test::More will only be aware of threads if \*(L"use threads\*(R" has been done
+\&\fIbefore\fR Test::More is loaded. This is ok:
+.Sp
+.Vb 2
+\& use threads;
+\& use Test::More;
+.Ve
+.Sp
+This may cause problems:
+.Sp
+.Vb 2
+\& use Test::More
+\& use threads;
+.Ve
+.Sp
+5.8.1 and above are supported. Anything below that has too many bugs.
+.SH "HISTORY"
+.IX Header "HISTORY"
+This is a case of convergent evolution with Joshua Pritikin's Test
+module. I was largely unaware of its existence when I'd first
+written my own \fIok()\fR routines. This module exists because I can't
+figure out how to easily wedge test names into Test's interface (along
+with a few other problems).
+.PP
+The goal here is to have a testing utility that's simple to learn,
+quick to use and difficult to trip yourself up with while still
+providing more flexibility than the existing Test.pm. As such, the
+names of the most common routines are kept tiny, special cases and
+magic side-effects are kept to a minimum. \s-1WYSIWYG\s0.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Test::Simple if all this confuses you and you just want to write
+some tests. You can upgrade to Test::More later (it's forward
+compatible).
+.PP
+Test::Harness is the test runner and output interpreter for Perl.
+It's the thing that powers \f(CW\*(C`make test\*(C'\fR and where the \f(CW\*(C`prove\*(C'\fR utility
+comes from.
+.PP
+Test::Legacy tests written with Test.pm, the original testing
+module, do not play well with other testing libraries. Test::Legacy
+emulates the Test.pm interface and does play well with others.
+.PP
+Test::Differences for more ways to test complex data structures.
+And it plays well with Test::More.
+.PP
+Test::Class is like xUnit but more perlish.
+.PP
+Test::Deep gives you more powerful complex data structure testing.
+.PP
+Test::Inline shows the idea of embedded testing.
+.PP
+Bundle::Test installs a whole bunch of useful test modules.
+.SH "AUTHORS"
+.IX Header "AUTHORS"
+Michael G Schwern <schwern@pobox.com> with much inspiration
+from Joshua Pritikin's Test module and lots of help from Barrie
+Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and
+the perl-qa gang.
+.SH "BUGS"
+.IX Header "BUGS"
+See \fIhttp://rt.cpan.org\fR to report and view bugs.
+.SH "SOURCE"
+.IX Header "SOURCE"
+The source code repository for Test::More can be found at
+\&\fIhttp://github.com/schwern/test\-more/\fR.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright 2001\-2008 by Michael G Schwern <schwern@pobox.com>.
+.PP
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.PP
+See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR
projects / catagits/Gitalist.git / blobdiff