Commit | Line | Data |
---|---|---|
4dd974da JH |
1 | package Test::Simple; |
2 | ||
518760d9 | 3 | use 5.008001; |
4dd974da | 4 | |
ccbd73a4 | 5 | use strict; |
518760d9 | 6 | use warnings; |
ccbd73a4 | 7 | |
518760d9 | 8 | our $VERSION = '1.301001_071'; |
ccbd73a4 | 9 | $VERSION = eval $VERSION; ## no critic (BuiltinFunctions::ProhibitStringyEval) |
d020a79a | 10 | |
518760d9 CG |
11 | use Test::Stream 1.301001_071 '-internal'; |
12 | use Test::Stream::Toolset; | |
13 | ||
14 | use Test::Stream::Exporter; | |
15 | default_exports qw/ok/; | |
16 | Test::Stream::Exporter->cleanup; | |
17 | ||
18 | sub before_import { | |
19 | my $class = shift; | |
20 | my ($importer, $list) = @_; | |
21 | ||
22 | my $meta = init_tester($importer); | |
23 | my $context = context(1); | |
24 | my $idx = 0; | |
25 | my $other = []; | |
26 | while ($idx <= $#{$list}) { | |
27 | my $item = $list->[$idx++]; | |
28 | ||
29 | if (defined $item and $item eq 'no_diag') { | |
30 | Test::Stream->shared->set_no_diag(1); | |
31 | } | |
32 | elsif ($item eq 'tests') { | |
33 | $context->plan($list->[$idx++]); | |
34 | } | |
35 | elsif ($item eq 'skip_all') { | |
36 | $context->plan(0, 'SKIP', $list->[$idx++]); | |
37 | } | |
38 | elsif ($item eq 'no_plan') { | |
39 | $context->plan(0, 'NO PLAN'); | |
40 | } | |
41 | elsif ($item eq 'import') { | |
42 | push @$other => @{$list->[$idx++]}; | |
43 | } | |
44 | else { | |
45 | $context->throw("Unknown option: $item"); | |
46 | } | |
47 | } | |
48 | ||
49 | @$list = @$other; | |
50 | ||
51 | return; | |
52 | } | |
53 | ||
54 | sub ok ($;$) { ## no critic (Subroutines::ProhibitSubroutinePrototypes) | |
55 | my $ctx = context(); | |
56 | return $ctx->ok(@_); | |
57 | return $_[0] ? 1 : 0; | |
58 | } | |
4dd974da | 59 | |
518760d9 CG |
60 | 1; |
61 | ||
62 | __END__ | |
4dd974da | 63 | |
4dd974da JH |
64 | =head1 NAME |
65 | ||
66 | Test::Simple - Basic utilities for writing tests. | |
67 | ||
68 | =head1 SYNOPSIS | |
69 | ||
70 | use Test::Simple tests => 1; | |
71 | ||
72 | ok( $foo eq $bar, 'foo is bar' ); | |
73 | ||
4dd974da JH |
74 | =head1 DESCRIPTION |
75 | ||
ca5d3bff | 76 | ** If you are unfamiliar with testing B<read L<Test::Tutorial> first!> ** |
d020a79a | 77 | |
4dd974da | 78 | This is an extremely simple, extremely basic module for writing tests |
d020a79a JH |
79 | suitable for CPAN modules and other pursuits. If you wish to do more |
80 | complicated testing, use the Test::More module (a drop-in replacement | |
81 | for this one). | |
4dd974da JH |
82 | |
83 | The basic unit of Perl testing is the ok. For each thing you want to | |
84 | test your program will print out an "ok" or "not ok" to indicate pass | |
ca5d3bff | 85 | or fail. You do this with the C<ok()> function (see below). |
4dd974da | 86 | |
9631ec48 | 87 | The only other constraint is you must pre-declare how many tests you |
4dd974da JH |
88 | plan to run. This is in case something goes horribly wrong during the |
89 | test and your test program aborts, or skips a test or whatever. You | |
90 | do this like so: | |
91 | ||
92 | use Test::Simple tests => 23; | |
93 | ||
94 | You must have a plan. | |
95 | ||
96 | ||
97 | =over 4 | |
98 | ||
99 | =item B<ok> | |
100 | ||
101 | ok( $foo eq $bar, $name ); | |
102 | ok( $foo eq $bar ); | |
103 | ||
ca5d3bff | 104 | C<ok()> is given an expression (in this case C<$foo eq $bar>). If it's |
89c1e84a | 105 | true, the test passed. If it's false, it didn't. That's about it. |
4dd974da | 106 | |
ca5d3bff | 107 | C<ok()> prints out either "ok" or "not ok" along with a test number (it |
4dd974da JH |
108 | keeps track of that for you). |
109 | ||
110 | # This produces "ok 1 - Hell not yet frozen over" (or not ok) | |
111 | ok( get_temperature($hell) > 0, 'Hell not yet frozen over' ); | |
112 | ||
113 | If you provide a $name, that will be printed along with the "ok/not | |
114 | ok" to make it easier to find your test when if fails (just search for | |
115 | the name). It also makes it easier for the next guy to understand | |
89c1e84a | 116 | what your test is for. It's highly recommended you use test names. |
4dd974da JH |
117 | |
118 | All tests are run in scalar context. So this: | |
119 | ||
120 | ok( @stuff, 'I have some stuff' ); | |
121 | ||
d020a79a | 122 | will do what you mean (fail if stuff is empty) |
4dd974da | 123 | |
4dd974da JH |
124 | =back |
125 | ||
126 | Test::Simple will start by printing number of tests run in the form | |
127 | "1..M" (so "1..5" means you're going to run 5 tests). This strange | |
ca5d3bff | 128 | format lets L<Test::Harness> know how many tests you plan on running in |
4dd974da JH |
129 | case something goes horribly wrong. |
130 | ||
131 | If all your tests passed, Test::Simple will exit with zero (which is | |
132 | normal). If anything failed it will exit with how many failed. If | |
133 | you run less (or more) tests than you planned, the missing (or extras) | |
134 | will be considered failures. If no tests were ever run Test::Simple | |
135 | will throw a warning and exit with 255. If the test died, even after | |
136 | having successfully completed all its tests, it will still be | |
137 | considered a failure and will exit with 255. | |
138 | ||
139 | So the exit codes are... | |
140 | ||
141 | 0 all tests successful | |
b1ddf169 | 142 | 255 test died or all passed but wrong # of tests run |
4dd974da JH |
143 | any other number how many failed (including missing or extras) |
144 | ||
145 | If you fail more than 254 tests, it will be reported as 254. | |
146 | ||
4dd974da | 147 | This module is by no means trying to be a complete testing system. |
89c1e84a | 148 | It's just to get you started. Once you're off the ground its |
4dd974da JH |
149 | recommended you look at L<Test::More>. |
150 | ||
151 | ||
152 | =head1 EXAMPLE | |
153 | ||
154 | Here's an example of a simple .t file for the fictional Film module. | |
155 | ||
156 | use Test::Simple tests => 5; | |
157 | ||
158 | use Film; # What you're testing. | |
159 | ||
160 | my $btaste = Film->new({ Title => 'Bad Taste', | |
161 | Director => 'Peter Jackson', | |
162 | Rating => 'R', | |
163 | NumExplodingSheep => 1 | |
164 | }); | |
809046db | 165 | ok( defined($btaste) && ref $btaste eq 'Film', 'new() works' ); |
4dd974da JH |
166 | |
167 | ok( $btaste->Title eq 'Bad Taste', 'Title() get' ); | |
d020a79a | 168 | ok( $btaste->Director eq 'Peter Jackson', 'Director() get' ); |
4dd974da JH |
169 | ok( $btaste->Rating eq 'R', 'Rating() get' ); |
170 | ok( $btaste->NumExplodingSheep == 1, 'NumExplodingSheep() get' ); | |
171 | ||
172 | It will produce output like this: | |
173 | ||
174 | 1..5 | |
175 | ok 1 - new() works | |
176 | ok 2 - Title() get | |
177 | ok 3 - Director() get | |
178 | not ok 4 - Rating() get | |
b1ddf169 RGS |
179 | # Failed test 'Rating() get' |
180 | # in t/film.t at line 14. | |
4dd974da | 181 | ok 5 - NumExplodingSheep() get |
d020a79a | 182 | # Looks like you failed 1 tests of 5 |
4dd974da JH |
183 | |
184 | Indicating the Film::Rating() method is broken. | |
185 | ||
186 | ||
187 | =head1 CAVEATS | |
188 | ||
189 | Test::Simple will only report a maximum of 254 failures in its exit | |
190 | code. If this is a problem, you probably have a huge test script. | |
191 | Split it into multiple files. (Otherwise blame the Unix folks for | |
192 | using an unsigned short integer as the exit status). | |
193 | ||
d020a79a JH |
194 | Because VMS's exit codes are much, much different than the rest of the |
195 | universe, and perl does horrible mangling to them that gets in my way, | |
196 | it works like this on VMS. | |
197 | ||
198 | 0 SS$_NORMAL all tests successful | |
199 | 4 SS$_ABORT something went wrong | |
200 | ||
201 | Unfortunately, I can't differentiate any further. | |
202 | ||
203 | ||
204 | =head1 NOTES | |
205 | ||
2c4d5b9b | 206 | Test::Simple is B<explicitly> tested all the way back to perl 5.6.0. |
d020a79a | 207 | |
2c4d5b9b | 208 | Test::Simple is thread-safe in perl 5.8.1 and up. |
4dd974da JH |
209 | |
210 | =head1 HISTORY | |
211 | ||
212 | This module was conceived while talking with Tony Bowden in his | |
213 | kitchen one night about the problems I was having writing some really | |
214 | complicated feature into the new Testing module. He observed that the | |
215 | main problem is not dealing with these edge cases but that people hate | |
216 | to write tests B<at all>. What was needed was a dead simple module | |
217 | that took all the hard work out of testing and was really, really easy | |
218 | to learn. Paul Johnson simultaneously had this idea (unfortunately, | |
219 | he wasn't in Tony's kitchen). This is it. | |
220 | ||
221 | ||
4dd974da JH |
222 | =head1 SEE ALSO |
223 | ||
224 | =over 4 | |
225 | ||
226 | =item L<Test::More> | |
227 | ||
228 | More testing functions! Once you outgrow Test::Simple, look at | |
ca5d3bff CBW |
229 | L<Test::More>. Test::Simple is 100% forward compatible with L<Test::More> |
230 | (i.e. you can just use L<Test::More> instead of Test::Simple in your | |
4dd974da JH |
231 | programs and things will still work). |
232 | ||
4dd974da JH |
233 | =back |
234 | ||
ca5d3bff | 235 | Look in L<Test::More>'s SEE ALSO for more testing modules. |
ccbd73a4 | 236 | |
9631ec48 | 237 | |
518760d9 | 238 | =encoding utf8 |
07308ed1 | 239 | |
518760d9 CG |
240 | =head1 SOURCE |
241 | ||
242 | The source code repository for Test::More can be found at | |
243 | F<http://github.com/Test-More/test-more/>. | |
3709f1d4 | 244 | |
518760d9 | 245 | =head1 MAINTAINER |
07308ed1 CG |
246 | |
247 | =over 4 | |
248 | ||
249 | =item Chad Granum E<lt>exodist@cpan.orgE<gt> | |
250 | ||
07308ed1 CG |
251 | =back |
252 | ||
518760d9 CG |
253 | =head1 AUTHORS |
254 | ||
255 | The following people have all contributed to the Test-More dist (sorted using | |
256 | VIM's sort function). | |
257 | ||
258 | =over 4 | |
259 | ||
260 | =item Chad Granum E<lt>exodist@cpan.orgE<gt> | |
261 | ||
262 | =item Fergal Daly E<lt>fergal@esatclear.ie>E<gt> | |
263 | ||
264 | =item Mark Fowler E<lt>mark@twoshortplanks.comE<gt> | |
265 | ||
266 | =item Michael G Schwern E<lt>schwern@pobox.comE<gt> | |
267 | ||
268 | =item 唐鳳 | |
269 | ||
270 | =back | |
271 | ||
9631ec48 JH |
272 | =head1 COPYRIGHT |
273 | ||
518760d9 CG |
274 | There has been a lot of code migration between modules, |
275 | here are all the original copyrights together: | |
276 | ||
277 | =over 4 | |
278 | ||
279 | =item Test::Stream | |
280 | ||
281 | =item Test::Stream::Tester | |
282 | ||
283 | Copyright 2014 Chad Granum E<lt>exodist7@gmail.comE<gt>. | |
284 | ||
285 | This program is free software; you can redistribute it and/or | |
286 | modify it under the same terms as Perl itself. | |
287 | ||
288 | See F<http://www.perl.com/perl/misc/Artistic.html> | |
289 | ||
290 | =item Test::Simple | |
291 | ||
292 | =item Test::More | |
293 | ||
294 | =item Test::Builder | |
295 | ||
296 | Originally authored by Michael G Schwern E<lt>schwern@pobox.comE<gt> with much | |
297 | inspiration from Joshua Pritikin's Test module and lots of help from Barrie | |
298 | Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and the perl-qa | |
299 | gang. | |
300 | ||
301 | Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern | |
302 | E<lt>schwern@pobox.comE<gt>, wardrobe by Calvin Klein. | |
303 | ||
ccbd73a4 | 304 | Copyright 2001-2008 by Michael G Schwern E<lt>schwern@pobox.comE<gt>. |
9631ec48 | 305 | |
518760d9 | 306 | This program is free software; you can redistribute it and/or |
9631ec48 JH |
307 | modify it under the same terms as Perl itself. |
308 | ||
a9153838 | 309 | See F<http://www.perl.com/perl/misc/Artistic.html> |
11d55ae1 | 310 | |
518760d9 | 311 | =item Test::use::ok |
07308ed1 | 312 | |
518760d9 CG |
313 | To the extent possible under law, 唐鳳 has waived all copyright and related |
314 | or neighboring rights to L<Test-use-ok>. | |
315 | ||
316 | This work is published from Taiwan. | |
317 | ||
318 | L<http://creativecommons.org/publicdomain/zero/1.0> | |
319 | ||
320 | =item Test::Tester | |
321 | ||
322 | This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some parts | |
323 | are based on other people's work. | |
324 | ||
325 | Under the same license as Perl itself | |
326 | ||
327 | See http://www.perl.com/perl/misc/Artistic.html | |
328 | ||
329 | =item Test::Builder::Tester | |
330 | ||
331 | Copyright Mark Fowler E<lt>mark@twoshortplanks.comE<gt> 2002, 2004. | |
332 | ||
333 | This program is free software; you can redistribute it | |
334 | and/or modify it under the same terms as Perl itself. | |
335 | ||
336 | =back |