| 1 | package Acme::Test::Buffy; | ||||||||||||
| 2 | |||||||||||||
| 3 | # turn on strict. If this was perl 5.6.0 I'd turn on warnings too, but | ||||||||||||
| 4 | # testing scripts normally work on perls all the way back to 5.004 | ||||||||||||
| 5 | # so I can't say that. | ||||||||||||
| 6 | |||||||||||||
| 7 | 1 | ▶ | use strict; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 8 | #use warnings; | ||||||||||||
| 9 | |||||||||||||
| 10 | # declare the global vars for exporter and isa and stuff. If this | ||||||||||||
| 11 | # was 5.6.0 we could use our | ||||||||||||
| 12 | |||||||||||||
| 13 | 1 | ▶ | use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS); | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 14 | |||||||||||||
| 15 | # this is the first version of the module | ||||||||||||
| 16 | 1 | $VERSION = "0.02"; | |||||||||||
| 17 | |||||||||||||
| 18 | # load the test builder class. This class contains all the methods | ||||||||||||
| 19 | # that you use to emit test results. | ||||||||||||
| 20 | |||||||||||||
| 21 | 1 | ▶ | use Test::Builder; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 22 | |||||||||||||
| 23 | # get the tester. Despite being called 'new', this simply returns the | ||||||||||||
| 24 | # one and only tester object - this is what is known as a singleton | ||||||||||||
| 25 | # class. Essentially this means that all Test::Builder objects are | ||||||||||||
| 26 | # one and the same object, and this is what allows all classes that | ||||||||||||
| 27 | # make use of Test::Builder to print out "ok 1" "ok 2" etc without | ||||||||||||
| 28 | # getting in each other's way and mucking up the order of the numbers | ||||||||||||
| 29 | |||||||||||||
| 30 | 1 | my $Tester = Test::Builder->new(); | |||||||||||
| 31 | |||||||||||||
| 32 | # this is loading exporter. Exporter is used to export functions | ||||||||||||
| 33 | # from our namespace into the callers. i.e. it's a way to make | ||||||||||||
| 34 | # 'is_buffy' be able to be called from within a testing script | ||||||||||||
| 35 | |||||||||||||
| 36 | 1 | ▶ | use Exporter; # load the class | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 37 | 1 | @ISA = qw(Exporter); # set it as the base class | |||||||||||
| 38 | 1 | @EXPORT = qw(is_buffy); # want to export 'is_buffy' | |||||||||||
| 39 | 1 | @EXPORT_OK = qw(); # no other optional functions | |||||||||||
| 40 | 1 | %EXPORT_TAGS = qw(); # no groups of functions | |||||||||||
| 41 | |||||||||||||
| 42 | # write some pod documentation | ||||||||||||
| 43 | |||||||||||||
| 44 | =head1 NAME | ||||||||||||
| 45 | |||||||||||||
| 46 | Acme::Test::Buffy - example Test::Builder testing module | ||||||||||||
| 47 | |||||||||||||
| 48 | =head1 SYNOPSIS | ||||||||||||
| 49 | |||||||||||||
| 50 | use Test::More tests => 1; | ||||||||||||
| 51 | use Acme::Test::Buffy; | ||||||||||||
| 52 | |||||||||||||
| 53 | is_buffy($foo, "test foo is Buffy"); | ||||||||||||
| 54 | |||||||||||||
| 55 | =head1 DESCRIPTION | ||||||||||||
| 56 | |||||||||||||
| 57 | The reason for writing this module is to demonstrate how you | ||||||||||||
| 58 | can write testing modules that work together with B<Test::Builder>. | ||||||||||||
| 59 | It also shows how to test such modules with B<Test::Builder::Tester>. | ||||||||||||
| 60 | Look at the source code (which is heavily commented) for further | ||||||||||||
| 61 | enlightenment. | ||||||||||||
| 62 | |||||||||||||
| 63 | This module simply exports one testing function that tests if a string | ||||||||||||
| 64 | is the same as "Buffy" (case sensitive.) | ||||||||||||
| 65 | |||||||||||||
| 66 | =cut | ||||||||||||
| 67 | |||||||||||||
| 68 | # here's where we define the subroutine "is_buffy" that will be | ||||||||||||
| 69 | # exported. Note the prototype that does the right thing. More | ||||||||||||
| 70 | # can be found out about prototypes in the 'perlsub' perldoc. | ||||||||||||
| 71 | # This one simply says "one scalar argument and possibly another" | ||||||||||||
| 72 | |||||||||||||
| 73 | sub is_buffy($;$) | ||||||||||||
| 74 | 3 | ▶ | { | ||||||||||
|
Subroutine
is_buffy: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||
| 75 | # simply call the other subroutine. There's no reason why this | ||||||||||||
| 76 | # couldn't be done here, I just want to show how to call other | ||||||||||||
| 77 | # subroutines in this class. This supplied a default test | ||||||||||||
| 78 | # description | ||||||||||||
| 79 | 3 | ▶ | _do_buffy_test(shift(), shift() || "is 'Buffy'"); | ||||||||||
|
Condition100%2/2
shift() || q[is 'Buffy']
MC/DC100%1/1
shift() || q[is 'Buffy']
shift()
Truth table100%2/2
A
A= shift()
| |||||||||||||
| 80 | } | ||||||||||||
| 81 | |||||||||||||
| 82 | # this is a second subroutine that's used to demonstrate how you | ||||||||||||
| 83 | # should deal with calling subroutines. | ||||||||||||
| 84 | |||||||||||||
| 85 | sub _do_buffy_test | ||||||||||||
| 86 | 3 | ▶ | { | ||||||||||
|
Subroutine
_do_buffy_test: called CC=2 SCAR=6.9
| |||||||||||||
| 87 | # as we've entered another subroutine we need to increase the | ||||||||||||
| 88 | # counter that Test::Builder uses to state where the error | ||||||||||||
| 89 | # comes from (so we get an error at the line in your test | ||||||||||||
| 90 | # script not from within the call to this routine in 'is_buffy') | ||||||||||||
| 91 | # we use a local so that the level is returned to the previous | ||||||||||||
| 92 | # value when we exit the subroutine. Note that we can't use | ||||||||||||
| 93 | # the ++ operator here as it doesn't do what you might think. | ||||||||||||
| 94 | |||||||||||||
| 95 | 3 | local $Test::Builder::Level = $Test::Builder::Level + 1; | |||||||||||
| 96 | |||||||||||||
| 97 | # get the args | ||||||||||||
| 98 | 3 | my ($maybe_buffy, $text) = @_; | |||||||||||
| 99 | |||||||||||||
| 100 | # do the test | ||||||||||||
| 101 | 3 | ▶ | if ($maybe_buffy eq "Buffy") | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 102 | { | ||||||||||||
| 103 | # print okay with the right text ("ok <number> - <text>") | ||||||||||||
| 104 | 2 | $Tester->ok(1,$text); | |||||||||||
| 105 | |||||||||||||
| 106 | # return a true value (don't have to do this but it's nice) | ||||||||||||
| 107 | 2 | return 1; | |||||||||||
| 108 | } | ||||||||||||
| 109 | else | ||||||||||||
| 110 | { | ||||||||||||
| 111 | # We failed. We want to test Test::Builder to print something | ||||||||||||
| 112 | # like: | ||||||||||||
| 113 | # Failed test at line <line number> | ||||||||||||
| 114 | # Expected 'Buffy' but got '<what we got>' instead | ||||||||||||
| 115 | # that is to say we print failure first, _then_ the extra diag | ||||||||||||
| 116 | # stuff that will help people debug the code better. | ||||||||||||
| 117 | |||||||||||||
| 118 | # print not okay with the right text ("not ok <number> - <text>") | ||||||||||||
| 119 | 1 | $Tester->ok(0,$text); | |||||||||||
| 120 | |||||||||||||
| 121 | # print diagnostics of *why* it failed. Don't just print to | ||||||||||||
| 122 | # STDERR this is bad and wrong as it prevents the test output | ||||||||||||
| 123 | # being properly caught. Note the "\n" on the end of the | ||||||||||||
| 124 | # line. | ||||||||||||
| 125 | 1 | $Tester->diag("Expected 'Buffy' but got '$maybe_buffy' instead\n"); | |||||||||||
| 126 | |||||||||||||
| 127 | # return a false value (don't have to do this, but it's nice) | ||||||||||||
| 128 | 1 | return 0; | |||||||||||
| 129 | } | ||||||||||||
| 130 | } | ||||||||||||
| 131 | |||||||||||||
| 132 | =head1 BUGS | ||||||||||||
| 133 | |||||||||||||
| 134 | None known. Please report, including documentation bugs to | ||||||||||||
| 135 | the author. You may use the CPAN RT system. | ||||||||||||
| 136 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Acme-Test-Buffy> | ||||||||||||
| 137 | |||||||||||||
| 138 | =head1 AUTHOR | ||||||||||||
| 139 | |||||||||||||
| 140 | Copyright Mark Fowler | ||||||||||||
| 141 | E<lt>mark@twoshortplanks.comE<gt> 2002-2004 | ||||||||||||
| 142 | All rights reserved. | ||||||||||||
| 143 | |||||||||||||
| 144 | This program is free software; you can redistribute it | ||||||||||||
| 145 | and/or modify it under the same terms as Perl itself. | ||||||||||||
| 146 | |||||||||||||
| 147 | =head1 NOTES | ||||||||||||
| 148 | |||||||||||||
| 149 | Module also written to annoy Leon Brocard, who will have to update his | ||||||||||||
| 150 | YAPC::Europe talk slides to include it a mere ten minutes before his | ||||||||||||
| 151 | talk. | ||||||||||||
| 152 | |||||||||||||
| 153 | =head1 SEE ALSO | ||||||||||||
| 154 | |||||||||||||
| 155 | L<Test::Builder>, L<Test::Builder::Tester>, L<Test::More>. | ||||||||||||
| 156 | |||||||||||||
| 157 | =cut | ||||||||||||
| 158 | |||||||||||||
| 159 | # and return true | ||||||||||||
| 160 | 1 | 1; | |||||||||||