README

   1 NAME
   2     Test::Leaner - A slimmer Test::More for when you favor performance over
   3     completeness.
   4
   5 VERSION
   6     Version 0.05
   7
   8 SYNOPSIS
   9         use Test::Leaner tests => 10_000;
  10         for (1 .. 10_000) {
  11          ...
  12          is $one, 1, "checking situation $_";
  13         }
  14
  15 DESCRIPTION
  16     When profiling some Test::More-based test script that contained about 10
  17     000 unit tests, I realized that 60% of the time was spent in
  18     Test::Builder itself, even though every single test actually involved a
  19     costly "eval STRING".
  20
  21     This module aims to be a partial replacement to Test::More in those
  22     situations where you want to run a large number of simple tests. Its
  23     functions behave the same as their Test::More counterparts, except for
  24     the following differences :
  25
  26     *   Stringification isn't forced on the test operands. However, "ok"
  27         honors 'bool' overloading, "is" and "is_deeply" honor 'eq'
  28         overloading (and just that one), "isnt" honors 'ne' overloading, and
  29         "cmp_ok" honors whichever overloading category corresponds to the
  30         specified operator.
  31
  32     *   "pass", "fail", "ok", "is", "isnt", "like", "unlike", "cmp_ok" and
  33         "is_deeply" are all guaranteed to return the truth value of the
  34         test.
  35
  36     *   "isn't" (the sub "t" in package "isn") is not aliased to "isnt".
  37
  38     *   "like" and "unlike" don't special case regular expressions that are
  39         passed as '/.../' strings. A string regexp argument is always
  40         treated as the source of the regexp, making "like $text, $rx" and
  41         "like $text, qr[$rx]" equivalent to each other and to "cmp_ok $text,
  42         '=~', $rx" (and likewise for "unlike").
  43
  44     *   "cmp_ok" throws an exception if the given operator isn't a valid
  45         Perl binary operator (except '=' and variants). It also tests in
  46         scalar context, so '..' will be treated as the flip-flop operator
  47         and not the range operator.
  48
  49     *   "is_deeply" doesn't guard for memory cycles. If the two first
  50         arguments present parallel memory cycles, the test may result in an
  51         infinite loop.
  52
  53     *   The tests don't output any kind of default diagnostic in case of
  54         failure ; the rationale being that if you have a large number of
  55         tests and a lot of them are failing, then you don't want to be
  56         flooded by diagnostics. Moreover, this allows a much faster variant
  57         of "is_deeply".
  58
  59     *   "use_ok", "require_ok", "can_ok", "isa_ok", "new_ok", "subtest",
  60         "explain", "TODO" blocks and "todo_skip" are not implemented.
  61
  62 ENVIRONMENT
  63   "PERL_TEST_LEANER_USES_TEST_MORE"
  64     If this environment variable is set, Test::Leaner will replace its
  65     functions by those from Test::More. Moreover, the symbols that are
  66     imported when you "use Test::Leaner" will be those from Test::More, but
  67     you can still only import the symbols originally defined in Test::Leaner
  68     (hence the functions from Test::More that are not implemented in
  69     Test::Leaner will not be imported). If your version of Test::More is too
  70     old and doesn't have some symbols (like "note" or "done_testing"), they
  71     will be replaced in Test::Leaner by croaking stubs.
  72
  73     This may be useful if your Test::Leaner-based test script fails and you
  74     want extra diagnostics.
  75
  76 FUNCTIONS
  77     The following functions from Test::More are implemented and exported by
  78     default.
  79
  80   "plan"
  81         plan tests => $count;
  82         plan 'no_plan';
  83         plan skip_all => $reason;
  84
  85     See "plan" in Test::More.
  86
  87   "skip"
  88         skip $reason => $count;
  89
  90     See "skip" in Test::More.
  91
  92   "done_testing"
  93         done_testing;
  94         done_testing $count;
  95
  96     See "done_testing" in Test::More.
  97
  98   "ok"
  99         ok $ok;
 100         ok $ok, $desc;
 101
 102     See "ok" in Test::More.
 103
 104   "pass"
 105         pass;
 106         pass $desc;
 107
 108     See "pass" in Test::More.
 109
 110   "fail"
 111         fail;
 112         fail $desc;
 113
 114     See "fail" in Test::More.
 115
 116   "is"
 117         is $got, $expected;
 118         is $got, $expected, $desc;
 119
 120     See "is" in Test::More.
 121
 122   "isnt"
 123         isnt $got, $expected;
 124         isnt $got, $expected, $desc;
 125
 126     See "isnt" in Test::More.
 127
 128   "like"
 129         like $got, $regexp_expected;
 130         like $got, $regexp_expected, $desc;
 131
 132     See "like" in Test::More.
 133
 134   "unlike"
 135         unlike $got, $regexp_expected;
 136         unlike $got, $regexp_expected, $desc;
 137
 138     See "unlike" in Test::More.
 139
 140   "cmp_ok"
 141         cmp_ok $got, $op, $expected;
 142         cmp_ok $got, $op, $expected, $desc;
 143
 144     See "cmp_ok" in Test::More.
 145
 146   "is_deeply"
 147         is_deeply $got, $expected;
 148         is_deeply $got, $expected, $desc;
 149
 150     See "is_deeply" in Test::More.
 151
 152   "diag"
 153         diag @lines;
 154
 155     See "diag" in Test::More.
 156
 157   "note"
 158         note @lines;
 159
 160     See "note" in Test::More.
 161
 162   "BAIL_OUT"
 163         BAIL_OUT;
 164         BAIL_OUT $desc;
 165
 166     See "BAIL_OUT" in Test::More.
 167
 168     Test::Leaner also provides some functions of its own, which are never
 169     exported.
 170
 171   "tap_stream"
 172         my $tap_fh = tap_stream;
 173         tap_stream $fh;
 174
 175     Read/write accessor for the filehandle to which the tests are outputted.
 176     On write, it also turns autoflush on onto $fh.
 177
 178     Note that it can only be used as a write accessor before you start any
 179     thread, as threads::shared cannot reliably share filehandles.
 180
 181     Defaults to "STDOUT".
 182
 183   "diag_stream"
 184         my $diag_fh = diag_stream;
 185         diag_stream $fh;
 186
 187     Read/write accessor for the filehandle to which the diagnostics are
 188     printed. On write, it also turns autoflush on onto $fh.
 189
 190     Just like "tap_stream", it can only be used as a write accessor before
 191     you start any thread, as threads::shared cannot reliably share
 192     filehandles.
 193
 194     Defaults to "STDERR".
 195
 196   "THREADSAFE"
 197     This constant evaluates to true if and only if Test::Leaner is
 198     thread-safe, i.e. when this version of "perl" is at least 5.8, has been
 199     compiled with "useithreads" defined, and threads has been loaded before
 200     Test::Leaner. In that case, it also needs a working threads::shared.
 201
 202 DEPENDENCIES
 203     perl 5.6.
 204
 205     Exporter, Test::More.
 206
 207 AUTHOR
 208     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 209
 210     You can contact me by mail or on "irc.perl.org" (vincent).
 211
 212 BUGS
 213     Please report any bugs or feature requests to "bug-test-leaner at
 214     rt.cpan.org", or through the web interface at
 215     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Leaner>. I will be
 216     notified, and then you'll automatically be notified of progress on your
 217     bug as I make changes.
 218
 219 SUPPORT
 220     You can find documentation for this module with the perldoc command.
 221
 222         perldoc Test::Leaner
 223
 224 COPYRIGHT & LICENSE
 225     Copyright 2010,2011,2013 Vincent Pit, all rights reserved.
 226
 227     This program is free software; you can redistribute it and/or modify it
 228     under the same terms as Perl itself.
 229
 230     Except for the fallback implementation of the internal "_reftype"
 231     function, which has been taken from Scalar::Util and is
 232
 233     Copyright 1997-2007 Graham Barr, all rights reserved.
 234
 235     This program is free software; you can redistribute it and/or modify it
 236     under the same terms as Perl itself.
 237