1Test::Modern(3) User Contributed Perl Documentation Test::Modern(3)
2
6 Test::Modern - precision testing for modern perl
7
9 use Test::Modern;
10 # Your tests here
12 done_testing;
14
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 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 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 Features from Test::More
30 Test::Modern exports the following subs from Test::More:
31 "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 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 Features from Test::Fatal
62 Test::Modern exports the following subs from Test::Fatal:
63 "exception { BLOCK }"
65 Features from Test::Warnings
67 Test::Modern exports the following subs from Test::Warnings:
68 "warning { BLOCK }"
70 "warnings { BLOCK }"
71 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 Test::Modern can also export an additional function for testing
78 warnings, but does not export it by default:
79 "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 Features from Test::API
86 Test::Modern exports the following subs from Test::API:
87 "public_ok($package, @functions)"
89 "import_ok($package, export => \@functions, export_ok => \@functions)"
90 "class_api_ok($class, @methods)"
91 Features from Test::LongString
93 Test::Modern exports the following subs from Test::LongString:
94 "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 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 Features from Test::Deep
108 Test::Modern exports the following subs from Test::Deep:
109 "cmp_deeply($got, $expected, $description)"
111 The following are not exported by default, but can be exported upon
113 request:
114 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 As an alternative to using those functions, Test::Modern exports a
140 constant "TD" upon which you can call them as methods:
141 # like Test::Deep::bag(@elements)
143 TD->bag(@elements)
144 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 Test::Modern can export the following subs from Test::Pod and
150 Test::Pod::Coverage, though they are not exported by default:
151 "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 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 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 Also, Test::Modern wraps the "all_*" functions to run them in a subtest
172 (because otherwise they can interfere with your test plans).
173 Features from Test::Version
175 These features are currently considered experimental. They may be
176 removed from a future version of Test::Modern.
177 Test::Modern can export the following subs from Test::Version, though
179 they are not exported by default:
180 "version_ok($file, $description)"
182 version_all_ok(@dirs)
183 These are wrapped similarly to those described in the "Features from
185 Test::Pod and Test::Coverage".
186 Test::Modern can also export another sub based on "version_all_ok":
188 version_all_same(@dirs)
190 Acts like "version_all_ok" but also checks that all modules have
191 the same version number.
192 Features inspired by Test::Moose
194 Test::Modern does not use Test::Moose, but does provide the following
195 function inspired by it:
196 "does_ok($object|$subclass, $class, $name)"
198 Like "isa_ok", but calls "$obj->DOES" instead of "$obj->isa".
199 Features inspired by Test::CleanNamespaces
201 Test::Modern does not use Test::CleanNamespaces, but does provide the
202 following function inspired by it:
203 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 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 Features inspired by Test::Benchmark
215 Test::Modern does not use Test::Benchmark, but does provide the
216 following feature inspired by it:
217 "is_fastest($implementation, $times, \%implementations, $desc)"
219 use Test::Modern qw( is_fastest );
220 is_fastest("speedy", -1, {
222 "speedy" => sub { ... },
223 "slowcoach" => sub { ... },
224 });
225 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 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 Caveat the second: these tests tend to be slow. Use sparingly.
237 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 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 use Test::Modern -benchmark;
248 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 Features inspired by Test::Requires
254 Test::Modern does not use Test::Requires, but does provide the
255 following feature inspired by it:
256 "use Test::Modern -requires => \%requirements"
258 This will skip the entire test script if the requirements are not
259 met. For example:
260 use Test::Modern -requires => {
262 'perl' => '5.010',
263 'Moose' => '2.11',
264 'namespace::autoclean' => undef,
265 };
266 Features inspired by Test::RequiresInternet
268 Similarly you can skip the test script if an Internet connection is not
269 available:
270 use Test::Modern -internet;
272 You can check for the ability to connect to particular hosts and ports:
274 use Test::Modern -internet => [
276 'www.example.com' => 'http',
277 '8.8.8.8' => 53,
278 ];
279 Test::Modern does not use Test::RequiresInternet but I've stolen much
281 of the latter's implementation.
282 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 "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 use Test::Modern -without => [ "Class::XSAccessor" ];
293 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 perl -MTest::Modern -le'print for sort keys %INC'
299 (Note that the actual implementation is mostly stolen from
301 Devel::Hide which seems to behave better than
302 Test::Without::Module.)
303 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 They will cause your test script to be skipped depending on various
309 environment variables.
310 "use Test::Modern -author"
312 "use Test::Modern -release"
313 "use Test::Modern -extended"
314 "use Test::Modern -interactive"
315 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 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 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 use Test::Modern -lib;
329 Brand Spanking New Features
331 Test::Modern provides a shortcut which combines several features it has
332 pilfered from other testing modules:
333 "object_ok($object, $name, %tests)"
335 Runs a gamut of subtests on an object:
336 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 $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 "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 Any of the test hash keys may be omitted, in which case that test
364 will not be run. $name may be omitted.
365 If the test succeeds, it returns the object (which may be useful
367 for further tests). Otherwise, returns "undef".
368 Practical example:
370 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 # make further use of $bob
386 object_ok(
387 sub { $bob->line_manager },
388 isa => [qw( Person )],
389 );
390
392 This module uses Exporter::Tiny to perform its exports. This allows
393 exported subs to be renamed, etc.
394 The following export tags are supported:
396 "-more"
398 Exports the "Features from Test::More", except deprecated ones.
399 "-deprecated"
401 Exports the deprecated Test::More features.
402 "-fatal"
404 Exports the "Features from Test::Fatal".
405 "-warnings"
407 Exports the "Features from Test::Warnings".
408 "-api"
410 Exports the "Features from Test::API", including "class_api_ok".
411 "-strings"
413 Exports the "Features from Test::LongString".
414 "-deep"
416 Exports cmp_deeply and TD.
417 "-deeper"
419 Exports all the "Features from Test::Deep".
420 "-moose"
422 Exports the "Features inspired by Test::Moose".
423 "-clean"
425 Exports the "Features inspired by Test::CleanNamespaces".
426 "-pod"
428 Exports the "Features from Test::Pod and Test::Pod::Coverage".
429 "-versions"
431 Exports the "Features from Test::Version".
432 "-default"
434 Exports the default features -- all of the above except
435 "-deprecated", "-pod", "-versions", and "-deeper". Also exports
436 "object_ok".
437 "-all"
439 Exports all of the above features including "-deprecated", "-pod",
440 "-versions", "-deeper", "object_ok", and "shouldnt_warn".
441 "-author", "-extended", "-interactive", and "-release"
443 Classify the test script.
444 "-benchmark"
446 The test script consists mostly of benchmarking.
447 "-internet"
449 The test script requires Internet access.
450 "-requires", "-without"
452 Specify modules required or hidden for these test cases.
453 "-lib"
455 Makes the absence of a "t/lib" directory fatal.
456 See "Features inspired by Test::Lib".
458 "-verbose"
460 Makes test output more verbose. (Currently only "is_faster" takes
461 notice of this.)
462 $TODO is currently always exported.
464
466 Test::Modern is affected by the following environment variables:
467 "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 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 "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 "PERL_TEST_MODERN_ALLOW_WARNINGS"
484 Setting this to true allows you to disable Test::Warnings' end
485 test.
486 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
495 Please report any bugs to
496 <http://rt.cpan.org/Dist/Display.html?Queue=Test-Modern>.
497
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 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 Test::Most is a similar idea, but provides a slightly different
511 combination of features.
512
514 Toby Inkster <tobyink@cpan.org>.
515
517 This software is copyright (c) 2014 by Toby Inkster.
518 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
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.
526perl v5.36.0 2023-01-20 Test::Modern(3)