Update VPIT::TestHelpers to 0bb3aa5
[perl/modules/Test-Leaner.git] / 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