cpan/Test-Simple/lib/Test/Simple.pm

   1 package Test::Simple;
   2
   3 use 5.008001;
   4
   5 use strict;
   6 use warnings;
   7
   8 our $VERSION = '1.301001_075';
   9 $VERSION = eval $VERSION;    ## no critic (BuiltinFunctions::ProhibitStringyEval)
  10
  11 use Test::Stream 1.301001_075 '-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 }
  59
  60 1;
  61
  62 __END__
  63
  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
  74 =head1 DESCRIPTION
  75
  76 ** If you are unfamiliar with testing B<read L<Test::Tutorial> first!> **
  77
  78 This is an extremely simple, extremely basic module for writing tests
  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).
  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
  85 or fail.  You do this with the C<ok()> function (see below).
  86
  87 The only other constraint is you must pre-declare how many tests you
  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
 104 C<ok()> is given an expression (in this case C<$foo eq $bar>).  If it's
 105 true, the test passed.  If it's false, it didn't.  That's about it.
 106
 107 C<ok()> prints out either "ok" or "not ok" along with a test number (it
 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
 116 what your test is for.  It's highly recommended you use test names.
 117
 118 All tests are run in scalar context.  So this:
 119
 120     ok( @stuff, 'I have some stuff' );
 121
 122 will do what you mean (fail if stuff is empty)
 123
 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
 128 format lets L<Test::Harness> know how many tests you plan on running in
 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
 142     255                 test died or all passed but wrong # of tests run
 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
 147 This module is by no means trying to be a complete testing system.
 148 It's just to get you started.  Once you're off the ground its
 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                            });
 165     ok( defined($btaste) && ref $btaste eq 'Film',     'new() works' );
 166
 167     ok( $btaste->Title      eq 'Bad Taste',     'Title() get'    );
 168     ok( $btaste->Director   eq 'Peter Jackson', 'Director() get' );
 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
 179     #   Failed test 'Rating() get'
 180     #   in t/film.t at line 14.
 181     ok 5 - NumExplodingSheep() get
 182     # Looks like you failed 1 tests of 5
 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
 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
 206 Test::Simple is B<explicitly> tested all the way back to perl 5.6.0.
 207
 208 Test::Simple is thread-safe in perl 5.8.1 and up.
 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
 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
 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
 231 programs and things will still work).
 232
 233 =back
 234
 235 Look in L<Test::More>'s SEE ALSO for more testing modules.
 236
 237
 238 =encoding utf8
 239
 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/>.
 244
 245 =head1 MAINTAINER
 246
 247 =over 4
 248
 249 =item Chad Granum E<lt>exodist@cpan.orgE<gt>
 250
 251 =back
 252
 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
 272 =head1 COPYRIGHT
 273
 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
 304 Copyright 2001-2008 by Michael G Schwern E<lt>schwern@pobox.comE<gt>.
 305
 306 This program is free software; you can redistribute it and/or
 307 modify it under the same terms as Perl itself.
 308
 309 See F<http://www.perl.com/perl/misc/Artistic.html>
 310
 311 =item Test::use::ok
 312
 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