1Test::Modern(3)       User Contributed Perl Documentation      Test::Modern(3)
2
3
4

NAME

6       Test::Modern - precision testing for modern perl
7

SYNOPSIS

9          use Test::Modern;
10
11          # Your tests here
12
13          done_testing;
14

DESCRIPTION

16       Test::Modern provides the best features of Test::More, Test::Fatal,
17       Test::Warnings, Test::API, Test::LongString, and Test::Deep, as well as
18       ideas from Test::Requires, Test::DescribeMe, Test::Moose, and
19       Test::CleanNamespaces.
20
21       Test::Modern also automatically imposes strict and warnings on your
22       script, and loads IO::File. (Much of the same stuff Modern::Perl does.)
23
24       Although Test::Modern is a modern testing framework, it should run fine
25       on pre-modern versions of Perl. It should be easy to install on Perl
26       5.8.9 and above; and if you can persuade its dependencies to install
27       (not necessarily easy!), should be OK on anything back to Perl 5.6.1.
28
29   Features from Test::More
30       Test::Modern exports the following subs from Test::More:
31
32       "ok($truth, $description)"
33       "is($got, $expected, $description)"
34       "isnt($got, $unexpected, $description)"
35       "like($got, $regexp, $description)"
36       "unlike($got, $regexp, $description)"
37       "is_deeply($got, $expected, $description)"
38       "cmp_ok($got, $operator, $expected, $description)"
39       "new_ok($class, \@args, $name)"
40       "isa_ok($object|$subclass, $class, $name)"
41       "can_ok($object|$class, @methods)"
42       "pass($description)"
43       "fail($description)"
44       "subtest($description, sub { ... })"
45       "diag(@messages)"
46       "note(@messages)"
47       "explain(@messages)"
48       "skip($why, $count) if $reason"
49       "todo_skip($why, $count) if $reason"
50       $TODO
51       "plan(%plan)"
52       "done_testing"
53       "BAIL_OUT($reason)"
54
55       The "use_ok", "require_ok", "eq_array", "eq_hash", and "eq_set"
56       functions are also available, but not exported by default. For "use_ok"
57       and "require_ok" it's normally better to use the Perl built-ins "use"
58       and "require" which will die (failing your test) if things are not OK.
59       For the "eq_*" functions, they can usually be replaced by "is_deeply".
60
61   Features from Test::Fatal
62       Test::Modern exports the following subs from Test::Fatal:
63
64       "exception { BLOCK }"
65
66   Features from Test::Warnings
67       Test::Modern exports the following subs from Test::Warnings:
68
69       "warning { BLOCK }"
70       "warnings { BLOCK }"
71
72       In addition, Test::Modern always enables the "had_no_warnings" test at
73       the end of the file, ensuring that your test script generated no
74       warnings other than the expected ones which were caught by "warnings"
75       blocks.  (See also "PERL_TEST_MODERN_ALLOW_WARNINGS" in "ENVIRONMENT".)
76
77       Test::Modern can also export an additional function for testing
78       warnings, but does not export it by default:
79
80       "shouldnt_warn { BLOCK }"
81           Runs a block of code that will hopefully not warn, but might. Tests
82           that it doesn't warn, but performs that test as a "todo" test, so
83           if it fails, your test suite can still pass.
84
85   Features from Test::API
86       Test::Modern exports the following subs from Test::API:
87
88       "public_ok($package, @functions)"
89       "import_ok($package, export => \@functions, export_ok => \@functions)"
90       "class_api_ok($class, @methods)"
91
92   Features from Test::LongString
93       Test::Modern exports the following subs from Test::LongString:
94
95       "is_string($got, $expected, $description)"
96       "is_string_nows($got, $expected, $description)"
97       "like_string($got, $regexp, $description)"
98       "unlike_string($got, $regexp, $description)"
99       "contains_string($haystack, $needle, $description)"
100       "lacks_string($haystack, $needle, $description)"
101
102       Actually Test::Modern provides these via a wrapper. If Test::LongString
103       is not installed then Test::Modern will provide a fallback
104       implementation using Test::More's "is", "isnt", "like", and "unlike"
105       functions. (The diagnostics won't be as good in the case of failures.)
106
107   Features from Test::Deep
108       Test::Modern exports the following subs from Test::Deep:
109
110       "cmp_deeply($got, $expected, $description)"
111
112       The following are not exported by default, but can be exported upon
113       request:
114
115       "ignore()"
116       "methods(%hash)"
117       "listmethods(%hash)"
118       "shallow($thing)"
119       "noclass($thing)"
120       "useclass($thing)"
121       "re($regexp, $capture_data, $flags)"
122       "superhashof(\%hash)"
123       "subhashof(\%hash)"
124       "bag(@elements)"
125       "set(@elements)"
126       "superbagof(@elements)"
127       "subbagof(@elements)"
128       "supersetof(@elements)"
129       "subsetof(@elements)"
130       "all(@expecteds)"
131       "any(@expecteds)"
132       "obj_isa($class)"
133       "array_each($thing)"
134       "str($string)"
135       "num($number, $tolerance)"
136       "bool($value)"
137       "code(\&subref)"
138
139       As an alternative to using those functions, Test::Modern exports a
140       constant "TD" upon which you can call them as methods:
141
142          # like Test::Deep::bag(@elements)
143          TD->bag(@elements)
144
145   Features from Test::Pod and Test::Pod::Coverage
146       These features are currently considered experimental. They may be
147       removed from a future version of Test::Modern.
148
149       Test::Modern can export the following subs from Test::Pod and
150       Test::Pod::Coverage, though they are not exported by default:
151
152       "pod_file_ok($file, $description)"
153       "all_pod_files_ok(@dirs)"
154       "pod_coverage_ok($module, $params, $description)"
155       "all_pod_coverage_ok($params, $description)"
156
157       In fact, Test::Modern wraps these tests in checks to see whether
158       Test::Pod(::Coverage) is installed, and the state of the
159       "RELEASE_TESTING", "AUTHOR_TESTING", and "EXTENDED_TESTING" environment
160       variables. If none of those environment variables is set to true, then
161       the test is skipped altogether. If Test::Pod(::Coverage) is not
162       installed, then the test is skipped, unless "RELEASE_TESTING" is true,
163       in which case Test::Pod(::Coverage) must be installed.
164
165       This is usually a pretty sensible behaviour. You want authors to be
166       made aware of pod errors if possible. You want to make sure they are
167       tested before doing a release. End users probably don't want a pod
168       formatting error to prevent them from installing the software, unless
169       they opt into it using "EXTENDED_TESTING".
170
171       Also, Test::Modern wraps the "all_*" functions to run them in a subtest
172       (because otherwise they can interfere with your test plans).
173
174   Features from Test::Version
175       These features are currently considered experimental. They may be
176       removed from a future version of Test::Modern.
177
178       Test::Modern can export the following subs from Test::Version, though
179       they are not exported by default:
180
181       "version_ok($file, $description)"
182       "version_all_ok(@dirs)"
183
184       These are wrapped similarly to those described in the "Features from
185       Test::Pod and Test::Coverage".
186
187       Test::Modern can also export another sub based on "version_all_ok":
188
189       "version_all_same(@dirs)"
190           Acts like "version_all_ok" but also checks that all modules have
191           the same version number.
192
193   Features inspired by Test::Moose
194       Test::Modern does not use Test::Moose, but does provide the following
195       function inspired by it:
196
197       "does_ok($object|$subclass, $class, $name)"
198           Like "isa_ok", but calls "$obj->DOES" instead of "$obj->isa".
199
200   Features inspired by Test::CleanNamespaces
201       Test::Modern does not use Test::CleanNamespaces, but does provide the
202       following function inspired by it:
203
204       "namespaces_clean(@namespaces)"
205           Tests that namespaces don't contain any imported functions. (i.e.
206           you haven't forgotten to use namespace::autoclean or
207           namespace::sweep in a class).
208
209           Unlike the version of this function supplied with
210           Test::CleanNamespaces, if @namespaces contains more than one
211           namespace, these will be run in a subtest, so the whole thing will
212           only count as one test.
213
214   Features inspired by Test::Benchmark
215       Test::Modern does not use Test::Benchmark, but does provide the
216       following feature inspired by it:
217
218       "is_fastest($implementation, $times, \%implementations, $desc)"
219              use Test::Modern qw( is_fastest );
220
221              is_fastest("speedy", -1, {
222                 "speedy"     => sub { ... },
223                 "slowcoach"  => sub { ... },
224              });
225
226           This ensures that the named coderef runs the fastest out of a
227           hashref of alternatives. The "-1" parameter in the example is the
228           number of times to run the coderefs (see Benchmark for more
229           details, including how numbers less than zero are interpreted).
230
231       Caveat: on fast computers, a set of coderefs that you might expect to
232       differ in speed might all run in a negligible period of time, and thus
233       be rounded to zero, in which case your test case could randomly fail.
234       Use this test with caution!
235
236       Caveat the second: these tests tend to be slow. Use sparingly.
237
238       Because of the aforementioned caveats, it is a good idea to move your
239       benchmarking tests into separate test scripts, keeping an imaginary
240       wall between them and the bulk of your test suite (which tests
241       correctness rather than speed).
242
243       Test::Modern provides an import hint suitable for including at the top
244       of these benchmarking tests to mark them as being primarily concerned
245       with speed:
246
247          use Test::Modern -benchmark;
248
249       This will not only import the "is_fastest" function, but will also skip
250       the entire script unless one of the "EXTENDED_TESTING" or
251       "RELEASE_TESTING" environment variables is set.
252
253   Features inspired by Test::Requires
254       Test::Modern does not use Test::Requires, but does provide the
255       following feature inspired by it:
256
257       "use Test::Modern -requires => \%requirements"
258           This will skip the entire test script if the requirements are not
259           met.  For example:
260
261              use Test::Modern -requires => {
262                 'perl'                 => '5.010',
263                 'Moose'                => '2.11',
264                 'namespace::autoclean' => undef,
265              };
266
267   Features inspired by Test::RequiresInternet
268       Similarly you can skip the test script if an Internet connection is not
269       available:
270
271          use Test::Modern -internet;
272
273       You can check for the ability to connect to particular hosts and ports:
274
275          use Test::Modern -internet => [
276             'www.example.com'  => 'http',
277             '8.8.8.8'          => 53,
278          ];
279
280       Test::Modern does not use Test::RequiresInternet but I've stolen much
281       of the latter's implementation.
282
283   Features inspired by Test::Without::Module
284       Test::Modern does not use Test::Without::Module, but does provide the
285       following feature inspired by it:
286
287       "use Test::Modern -without => \@modules"
288           This will run the tests as if the module was not installed. Useful
289           for testing things in the absence of optional dependencies. For
290           example:
291
292              use Test::Modern -without => [ "Class::XSAccessor" ];
293
294           It cannot suppress modules from being loaded if they are required
295           by Test::Modern itself. To get a list of what modules Test::Modern
296           requires, run the following command:
297
298              perl -MTest::Modern -le'print for sort keys %INC'
299
300           (Note that the actual implementation is mostly stolen from
301           Devel::Hide which seems to behave better than
302           Test::Without::Module.)
303
304   Features inspired by Test::DescribeMe
305       These export tags allow you to classify tests as "author tests",
306       "release tests", "extended tests", or "interactive tests".
307
308       They will cause your test script to be skipped depending on various
309       environment variables.
310
311       "use Test::Modern -author"
312       "use Test::Modern -release"
313       "use Test::Modern -extended"
314       "use Test::Modern -interactive"
315
316   Features inspired by Test::Lib
317       These features are currently considered experimental. They may be
318       removed from a future version of Test::Modern.
319
320       Test::Modern tries to find a directory called "t/lib" by traversing up
321       the directory tree from the caller file. If found, this directory will
322       be added to @INC.
323
324       Test::Lib would croak if such a directory cannot be found.
325       Test::Modern carries on if it can't find it. If you want something more
326       like the Test::Lib behaviour, use the "-lib" import tag:
327
328          use Test::Modern -lib;
329
330   Brand Spanking New Features
331       Test::Modern provides a shortcut which combines several features it has
332       pilfered from other testing modules:
333
334       "object_ok($object, $name, %tests)"
335           Runs a gamut of subtests on an object:
336
337              object_ok(
338                 $object,
339                 $name,
340                 isa   => \@classes,
341                 does  => \@roles,
342                 can   => \@methods,
343                 api   => \@methods,
344                 clean => $boolean,
345                 more  => sub {
346                    my $object = shift;
347                    ...;
348                 }
349              );
350
351           $object may be a blessed object, or an unblessed coderef which
352           returns a blessed object. The "isa" test runs "isa_ok"; the "does"
353           test runs "does_ok", the "can" test runs "can_ok", and the "api"
354           test runs "class_api_ok".  "clean" allows you to run
355           "namespaces_clean" on the object's class.
356
357           "more" introduces a coderef for running more tests. Within this sub
358           you can use any of the standard Test::More, Test::LongString, etc
359           tests. It is automatically run in a "try" block (see Try::Tiny);
360           throwing an exception will cause the test to fail, but not cause
361           the script to end.
362
363           Any of the test hash keys may be omitted, in which case that test
364           will not be run. $name may be omitted.
365
366           If the test succeeds, it returns the object (which may be useful
367           for further tests). Otherwise, returns "undef".
368
369           Practical example:
370
371              my $bob = object_ok(
372                 sub { Employee->new(name => 'Robert Jones') },
373                 '$bob',
374                 isa   => [qw( Employee Person Moo::Object )],
375                 does  => [qw( Employable )],
376                 can   => [qw( name employee_number tax_code )],
377                 clean => 1,
378                 more  => sub {
379                    my $object = shift;
380                    is($object->name, "Robert Jones");
381                    like($object->employee_number, qr/^[0-9]+$/);
382                 },
383              );
384
385              # make further use of $bob
386              object_ok(
387                 sub { $bob->line_manager },
388                 isa   => [qw( Person )],
389              );
390

EXPORT

392       This module uses Exporter::Tiny to perform its exports. This allows
393       exported subs to be renamed, etc.
394
395       The following export tags are supported:
396
397       "-more"
398           Exports the "Features from Test::More", except deprecated ones.
399
400       "-deprecated"
401           Exports the deprecated Test::More features.
402
403       "-fatal"
404           Exports the "Features from Test::Fatal".
405
406       "-warnings"
407           Exports the "Features from Test::Warnings".
408
409       "-api"
410           Exports the "Features from Test::API", including "class_api_ok".
411
412       "-strings"
413           Exports the "Features from Test::LongString".
414
415       "-deep"
416           Exports cmp_deeply and TD.
417
418       "-deeper"
419           Exports all the "Features from Test::Deep".
420
421       "-moose"
422           Exports the "Features inspired by Test::Moose".
423
424       "-clean"
425           Exports the "Features inspired by Test::CleanNamespaces".
426
427       "-pod"
428           Exports the "Features from Test::Pod and Test::Pod::Coverage".
429
430       "-versions"
431           Exports the "Features from Test::Version".
432
433       "-default"
434           Exports the default features -- all of the above except
435           "-deprecated", "-pod", "-versions", and "-deeper". Also exports
436           "object_ok".
437
438       "-all"
439           Exports all of the above features including "-deprecated", "-pod",
440           "-versions", "-deeper", "object_ok", and "shouldnt_warn".
441
442       "-author", "-extended", "-interactive", and "-release"
443           Classify the test script.
444
445       "-benchmark"
446           The test script consists mostly of benchmarking.
447
448       "-internet"
449           The test script requires Internet access.
450
451       "-requires", "-without"
452           Specify modules required or hidden for these test cases.
453
454       "-lib"
455           Makes the absence of a "t/lib" directory fatal.
456
457           See "Features inspired by Test::Lib".
458
459       "-verbose"
460           Makes test output more verbose. (Currently only "is_faster" takes
461           notice of this.)
462
463       $TODO is currently always exported.
464

ENVIRONMENT

466       Test::Modern is affected by the following environment variables:
467
468       "AUTHOR_TESTING", "AUTOMATED_TESTING", "EXTENDED_TESTING",
469       "RELEASE_TESTING"
470           These variables affect the behaviour of Test::Modern's pod-checking
471           and version-checking. See "Features from Test::Pod and
472           Test::Coverage" and "Features from Test::Version".
473
474           They also can trigger certain import tags to skip a test script.
475           See "Features inspired by Test::DescribeMe", and "Features inspired
476           by Test::Benchmark"
477
478       "NO_NETWORK_TESTS"
479           Automatically skips any tests which indicate that they require
480           Internet access, without even checking to see if the Internet is
481           accessible.  See "Features inspired by Test::RequiresInternet".
482
483       "PERL_TEST_MODERN_ALLOW_WARNINGS"
484           Setting this to true allows you to disable Test::Warnings' end
485           test.
486
487           Normally the end test will cause a test script to fail if any
488           unexpected warnings are encountered during its execution. New
489           versions of Perl, and upgrades of dependencies can cause a
490           previously good test suite to start emitting warnings. This
491           environment variable can be used as a "quick fix" to get the test
492           suite passing again.
493

BUGS

495       Please report any bugs to
496       <http://rt.cpan.org/Dist/Display.html?Queue=Test-Modern>.
497

SEE ALSO

499       My Favourite Test::* Modules
500       <http://blogs.perl.org/users/toby_inkster/2014/02/my-favourite-test-
501       modules.html>, Precision Testing for Modern Perl
502       <http://blogs.perl.org/users/toby_inkster/2014/03/precision-testing-
503       for-modern-perl.html>.
504
505       Test::More, Test::Fatal, Test::Warnings, Test::API, Test::LongString,
506       Test::Deep, Test::Moose, Test::CleanNamespaces, Test::Requires,
507       Test::Without::Module, Test::RequiresInternet, Test::DescribeMe,
508       Test::Lib, Test::Pod, Test::Pod::Coverage, Test::Version.
509
510       Test::Most is a similar idea, but provides a slightly different
511       combination of features.
512

AUTHOR

514       Toby Inkster <tobyink@cpan.org>.
515
517       This software is copyright (c) 2014 by Toby Inkster.
518
519       This is free software; you can redistribute it and/or modify it under
520       the same terms as the Perl 5 programming language system itself.
521

DISCLAIMER OF WARRANTIES

523       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
524       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
525       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
526
527
528
529perl v5.34.0                      2022-01-21                   Test::Modern(3)
Impressum