X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FGitalist.git;a=blobdiff_plain;f=local-lib5%2Fman%2Fman3%2FTest%3A%3AMore.3pm;fp=local-lib5%2Fman%2Fman3%2FTest%3A%3AMore.3pm;h=8e00864ecf4cd0ab14e57d0073166b62b9a5ed56;hp=0000000000000000000000000000000000000000;hb=3fea05b9fbf95091f4522528b9980a33e0235603;hpb=af746827daa7a8feccee889e1d12ebc74cc9201e diff --git a/local-lib5/man/man3/Test::More.3pm b/local-lib5/man/man3/Test::More.3pm new file mode 100644 index 0000000..8e00864 --- /dev/null +++ b/local-lib5/man/man3/Test::More.3pm @@ -0,0 +1,1287 @@ +.\" 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 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 . +.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