README

   1 NAME
   2     Test::Leaner - A slimmer Test::More for when you favor performance over
   3     completeness.
   4
   5 VERSION
   6     Version 0.04
   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 [ tests => $count | 'no_plan' | skip_all => $reason ]"
  81     See "plan" in Test::More.
  82
  83   "skip $reason => $count"
  84     See "skip" in Test::More.
  85
  86   "done_testing [ $count ]"
  87     See "done_testing" in Test::More.
  88
  89   "ok $ok [, $desc ]"
  90     See "ok" in Test::More.
  91
  92   "pass [ $desc ]"
  93     See "pass" in Test::More.
  94
  95   "fail [ $desc ]"
  96     See "fail" in Test::More.
  97
  98   "is $got, $expected [, $desc ]"
  99     See "is" in Test::More.
 100
 101   "isnt $got, $expected [, $desc ]"
 102     See "isnt" in Test::More.
 103
 104   "like $got, $regexp_expected [, $desc ]"
 105     See "like" in Test::More.
 106
 107   "unlike $got, $regexp_expected, [, $desc ]"
 108     See "unlike" in Test::More.
 109
 110   "cmp_ok $got, $op, $expected [, $desc ]"
 111     See "cmp_ok" in Test::More.
 112
 113   "is_deeply $got, $expected [, $desc ]"
 114     See "is_deeply" in Test::More.
 115
 116   "diag @text"
 117     See "diag" in Test::More.
 118
 119   "note @text"
 120     See "note" in Test::More.
 121
 122   "BAIL_OUT [ $desc ]"
 123     See "BAIL_OUT" in Test::More.
 124
 125     Test::Leaner also provides some functions of its own, which are never
 126     exported.
 127
 128   "tap_stream [ $fh ]"
 129     Read/write accessor for the filehandle to which the tests are outputted.
 130     On write, it also turns autoflush on onto $fh.
 131
 132     Note that it can only be used as a write accessor before you start any
 133     thread, as threads::shared cannot reliably share filehandles.
 134
 135     Defaults to "STDOUT".
 136
 137   "diag_stream [ $fh ]"
 138     Read/write accessor for the filehandle to which the diagnostics are
 139     printed. On write, it also turns autoflush on onto $fh.
 140
 141     Just like "tap_stream", it can only be used as a write accessor before
 142     you start any thread, as threads::shared cannot reliably share
 143     filehandles.
 144
 145     Defaults to "STDERR".
 146
 147   "THREADSAFE"
 148     This constant evaluates to true if and only if Test::Leaner is
 149     thread-safe, i.e. when this version of "perl" is at least 5.8, has been
 150     compiled with "useithreads" defined, and threads has been loaded before
 151     Test::Leaner. In that case, it also needs a working threads::shared.
 152
 153 DEPENDENCIES
 154     perl 5.6.
 155
 156     Exporter, Test::More.
 157
 158 AUTHOR
 159     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 160
 161     You can contact me by mail or on "irc.perl.org" (vincent).
 162
 163 BUGS
 164     Please report any bugs or feature requests to "bug-test-leaner at
 165     rt.cpan.org", or through the web interface at
 166     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Leaner>. I will be
 167     notified, and then you'll automatically be notified of progress on your
 168     bug as I make changes.
 169
 170 SUPPORT
 171     You can find documentation for this module with the perldoc command.
 172
 173         perldoc Test::Leaner
 174
 175 COPYRIGHT & LICENSE
 176     Copyright 2010,2011 Vincent Pit, all rights reserved.
 177
 178     This program is free software; you can redistribute it and/or modify it
 179     under the same terms as Perl itself.
 180
 181     Except for the fallback implementation of the internal "_reftype"
 182     function, which has been taken from Scalar::Util and is
 183
 184     Copyright 1997-2007 Graham Barr, all rights reserved.
 185
 186     This program is free software; you can redistribute it and/or modify it
 187     under the same terms as Perl itself.
 188