Provided by: libtest-modern-perl_0.013-3_all bug

NAME

       Test::Modern - precision testing for modern perl

SYNOPSIS

          use Test::Modern;

          # Your tests here

          done_testing;

DESCRIPTION

       Test::Modern provides the best features of Test::More, Test::Fatal, Test::Warnings,
       Test::API, Test::LongString, and Test::Deep, as well as ideas from Test::Requires,
       Test::DescribeMe, Test::Moose, and Test::CleanNamespaces.

       Test::Modern also automatically imposes strict and warnings on your script, and loads
       IO::File. (Much of the same stuff Modern::Perl does.)

       Although Test::Modern is a modern testing framework, it should run fine on pre-modern
       versions of Perl. It should be easy to install on Perl 5.8.9 and above; and if you can
       persuade its dependencies to install (not necessarily easy!), should be OK on anything
       back to Perl 5.6.1.

   Features from Test::More
       Test::Modern exports the following subs from Test::More:

       "ok($truth, $description)"
       "is($got, $expected, $description)"
       "isnt($got, $unexpected, $description)"
       "like($got, $regexp, $description)"
       "unlike($got, $regexp, $description)"
       "is_deeply($got, $expected, $description)"
       "cmp_ok($got, $operator, $expected, $description)"
       "new_ok($class, \@args, $name)"
       "isa_ok($object|$subclass, $class, $name)"
       "can_ok($object|$class, @methods)"
       "pass($description)"
       "fail($description)"
       "subtest($description, sub { ... })"
       "diag(@messages)"
       "note(@messages)"
       "explain(@messages)"
       "skip($why, $count) if $reason"
       "todo_skip($why, $count) if $reason"
       $TODO
       "plan(%plan)"
       "done_testing"
       "BAIL_OUT($reason)"

       The "use_ok", "require_ok", "eq_array", "eq_hash", and "eq_set" functions are also
       available, but not exported by default. For "use_ok" and "require_ok" it's normally better
       to use the Perl built-ins "use" and "require" which will die (failing your test) if things
       are not OK. For the "eq_*" functions, they can usually be replaced by "is_deeply".

   Features from Test::Fatal
       Test::Modern exports the following subs from Test::Fatal:

       "exception { BLOCK }"

   Features from Test::Warnings
       Test::Modern exports the following subs from Test::Warnings:

       "warning { BLOCK }"
       "warnings { BLOCK }"

       In addition, Test::Modern always enables the "had_no_warnings" test at the end of the
       file, ensuring that your test script generated no warnings other than the expected ones
       which were caught by "warnings" blocks.  (See also "PERL_TEST_MODERN_ALLOW_WARNINGS" in
       "ENVIRONMENT".)

       Test::Modern can also export an additional function for testing warnings, but does not
       export it by default:

       "shouldnt_warn { BLOCK }"
           Runs a block of code that will hopefully not warn, but might. Tests that it doesn't
           warn, but performs that test as a "todo" test, so if it fails, your test suite can
           still pass.

   Features from Test::API
       Test::Modern exports the following subs from Test::API:

       "public_ok($package, @functions)"
       "import_ok($package, export => \@functions, export_ok => \@functions)"
       "class_api_ok($class, @methods)"

   Features from Test::LongString
       Test::Modern exports the following subs from Test::LongString:

       "is_string($got, $expected, $description)"
       "is_string_nows($got, $expected, $description)"
       "like_string($got, $regexp, $description)"
       "unlike_string($got, $regexp, $description)"
       "contains_string($haystack, $needle, $description)"
       "lacks_string($haystack, $needle, $description)"

       Actually Test::Modern provides these via a wrapper. If Test::LongString is not installed
       then Test::Modern will provide a fallback implementation using Test::More's "is", "isnt",
       "like", and "unlike" functions. (The diagnostics won't be as good in the case of
       failures.)

   Features from Test::Deep
       Test::Modern exports the following subs from Test::Deep:

       "cmp_deeply($got, $expected, $description)"

       The following are not exported by default, but can be exported upon request:

       "ignore()"
       "methods(%hash)"
       "listmethods(%hash)"
       "shallow($thing)"
       "noclass($thing)"
       "useclass($thing)"
       "re($regexp, $capture_data, $flags)"
       "superhashof(\%hash)"
       "subhashof(\%hash)"
       "bag(@elements)"
       "set(@elements)"
       "superbagof(@elements)"
       "subbagof(@elements)"
       "supersetof(@elements)"
       "subsetof(@elements)"
       "all(@expecteds)"
       "any(@expecteds)"
       "obj_isa($class)"
       "array_each($thing)"
       "str($string)"
       "num($number, $tolerance)"
       "bool($value)"
       "code(\&subref)"

       As an alternative to using those functions, Test::Modern exports a constant "TD" upon
       which you can call them as methods:

          # like Test::Deep::bag(@elements)
          TD->bag(@elements)

   Features from Test::Pod and Test::Pod::Coverage
       These features are currently considered experimental. They may be removed from a future
       version of Test::Modern.

       Test::Modern can export the following subs from Test::Pod and Test::Pod::Coverage, though
       they are not exported by default:

       "pod_file_ok($file, $description)"
       "all_pod_files_ok(@dirs)"
       "pod_coverage_ok($module, $params, $description)"
       "all_pod_coverage_ok($params, $description)"

       In fact, Test::Modern wraps these tests in checks to see whether Test::Pod(::Coverage) is
       installed, and the state of the "RELEASE_TESTING", "AUTHOR_TESTING", and
       "EXTENDED_TESTING" environment variables. If none of those environment variables is set to
       true, then the test is skipped altogether. If Test::Pod(::Coverage) is not installed, then
       the test is skipped, unless "RELEASE_TESTING" is true, in which case Test::Pod(::Coverage)
       must be installed.

       This is usually a pretty sensible behaviour. You want authors to be made aware of pod
       errors if possible. You want to make sure they are tested before doing a release. End
       users probably don't want a pod formatting error to prevent them from installing the
       software, unless they opt into it using "EXTENDED_TESTING".

       Also, Test::Modern wraps the "all_*" functions to run them in a subtest (because otherwise
       they can interfere with your test plans).

   Features from Test::Version
       These features are currently considered experimental. They may be removed from a future
       version of Test::Modern.

       Test::Modern can export the following subs from Test::Version, though they are not
       exported by default:

       "version_ok($file, $description)"
       "version_all_ok(@dirs)"

       These are wrapped similarly to those described in the "Features from Test::Pod and
       Test::Coverage".

       Test::Modern can also export another sub based on "version_all_ok":

       "version_all_same(@dirs)"
           Acts like "version_all_ok" but also checks that all modules have the same version
           number.

   Features inspired by Test::Moose
       Test::Modern does not use Test::Moose, but does provide the following function inspired by
       it:

       "does_ok($object|$subclass, $class, $name)"
           Like "isa_ok", but calls "$obj->DOES" instead of "$obj->isa".

   Features inspired by Test::CleanNamespaces
       Test::Modern does not use Test::CleanNamespaces, but does provide the following function
       inspired by it:

       "namespaces_clean(@namespaces)"
           Tests that namespaces don't contain any imported functions. (i.e. you haven't
           forgotten to use namespace::autoclean or namespace::sweep in a class).

           Unlike the version of this function supplied with Test::CleanNamespaces, if
           @namespaces contains more than one namespace, these will be run in a subtest, so the
           whole thing will only count as one test.

   Features inspired by Test::Benchmark
       Test::Modern does not use Test::Benchmark, but does provide the following feature inspired
       by it:

       "is_fastest($implementation, $times, \%implementations, $desc)"
              use Test::Modern qw( is_fastest );

              is_fastest("speedy", -1, {
                 "speedy"     => sub { ... },
                 "slowcoach"  => sub { ... },
              });

           This ensures that the named coderef runs the fastest out of a hashref of alternatives.
           The "-1" parameter in the example is the number of times to run the coderefs (see
           Benchmark for more details, including how numbers less than zero are interpreted).

       Caveat: on fast computers, a set of coderefs that you might expect to differ in speed
       might all run in a negligible period of time, and thus be rounded to zero, in which case
       your test case could randomly fail. Use this test with caution!

       Caveat the second: these tests tend to be slow. Use sparingly.

       Because of the aforementioned caveats, it is a good idea to move your benchmarking tests
       into separate test scripts, keeping an imaginary wall between them and the bulk of your
       test suite (which tests correctness rather than speed).

       Test::Modern provides an import hint suitable for including at the top of these
       benchmarking tests to mark them as being primarily concerned with speed:

          use Test::Modern -benchmark;

       This will not only import the "is_fastest" function, but will also skip the entire script
       unless one of the "EXTENDED_TESTING" or "RELEASE_TESTING" environment variables is set.

   Features inspired by Test::Requires
       Test::Modern does not use Test::Requires, but does provide the following feature inspired
       by it:

       "use Test::Modern -requires => \%requirements"
           This will skip the entire test script if the requirements are not met.  For example:

              use Test::Modern -requires => {
                 'perl'                 => '5.010',
                 'Moose'                => '2.11',
                 'namespace::autoclean' => undef,
              };

   Features inspired by Test::RequiresInternet
       Similarly you can skip the test script if an Internet connection is not available:

          use Test::Modern -internet;

       You can check for the ability to connect to particular hosts and ports:

          use Test::Modern -internet => [
             'www.example.com'  => 'http',
             '8.8.8.8'          => 53,
          ];

       Test::Modern does not use Test::RequiresInternet but I've stolen much of the latter's
       implementation.

   Features inspired by Test::Without::Module
       Test::Modern does not use Test::Without::Module, but does provide the following feature
       inspired by it:

       "use Test::Modern -without => \@modules"
           This will run the tests as if the module was not installed. Useful for testing things
           in the absence of optional dependencies. For example:

              use Test::Modern -without => [ "Class::XSAccessor" ];

           It cannot suppress modules from being loaded if they are required by Test::Modern
           itself. To get a list of what modules Test::Modern requires, run the following
           command:

              perl -MTest::Modern -le'print for sort keys %INC'

           (Note that the actual implementation is mostly stolen from Devel::Hide which seems to
           behave better than Test::Without::Module.)

   Features inspired by Test::DescribeMe
       These export tags allow you to classify tests as "author tests", "release tests",
       "extended tests", or "interactive tests".

       They will cause your test script to be skipped depending on various environment variables.

       "use Test::Modern -author"
       "use Test::Modern -release"
       "use Test::Modern -extended"
       "use Test::Modern -interactive"

   Features inspired by Test::Lib
       These features are currently considered experimental. They may be removed from a future
       version of Test::Modern.

       Test::Modern tries to find a directory called "t/lib" by traversing up the directory tree
       from the caller file. If found, this directory will be added to @INC.

       Test::Lib would croak if such a directory cannot be found.  Test::Modern carries on if it
       can't find it. If you want something more like the Test::Lib behaviour, use the "-lib"
       import tag:

          use Test::Modern -lib;

   Brand Spanking New Features
       Test::Modern provides a shortcut which combines several features it has pilfered from
       other testing modules:

       "object_ok($object, $name, %tests)"
           Runs a gamut of subtests on an object:

              object_ok(
                 $object,
                 $name,
                 isa   => \@classes,
                 does  => \@roles,
                 can   => \@methods,
                 api   => \@methods,
                 clean => $boolean,
                 more  => sub {
                    my $object = shift;
                    ...;
                 }
              );

           $object may be a blessed object, or an unblessed coderef which returns a blessed
           object. The "isa" test runs "isa_ok"; the "does" test runs "does_ok", the "can" test
           runs "can_ok", and the "api" test runs "class_api_ok".  "clean" allows you to run
           "namespaces_clean" on the object's class.

           "more" introduces a coderef for running more tests. Within this sub you can use any of
           the standard Test::More, Test::LongString, etc tests. It is automatically run in a
           "try" block (see Try::Tiny); throwing an exception will cause the test to fail, but
           not cause the script to end.

           Any of the test hash keys may be omitted, in which case that test will not be run.
           $name may be omitted.

           If the test succeeds, it returns the object (which may be useful for further tests).
           Otherwise, returns "undef".

           Practical example:

              my $bob = object_ok(
                 sub { Employee->new(name => 'Robert Jones') },
                 '$bob',
                 isa   => [qw( Employee Person Moo::Object )],
                 does  => [qw( Employable )],
                 can   => [qw( name employee_number tax_code )],
                 clean => 1,
                 more  => sub {
                    my $object = shift;
                    is($object->name, "Robert Jones");
                    like($object->employee_number, qr/^[0-9]+$/);
                 },
              );

              # make further use of $bob
              object_ok(
                 sub { $bob->line_manager },
                 isa   => [qw( Person )],
              );

EXPORT

       This module uses Exporter::Tiny to perform its exports. This allows exported subs to be
       renamed, etc.

       The following export tags are supported:

       "-more"
           Exports the "Features from Test::More", except deprecated ones.

       "-deprecated"
           Exports the deprecated Test::More features.

       "-fatal"
           Exports the "Features from Test::Fatal".

       "-warnings"
           Exports the "Features from Test::Warnings".

       "-api"
           Exports the "Features from Test::API", including "class_api_ok".

       "-strings"
           Exports the "Features from Test::LongString".

       "-deep"
           Exports cmp_deeply and TD.

       "-deeper"
           Exports all the "Features from Test::Deep".

       "-moose"
           Exports the "Features inspired by Test::Moose".

       "-clean"
           Exports the "Features inspired by Test::CleanNamespaces".

       "-pod"
           Exports the "Features from Test::Pod and Test::Pod::Coverage".

       "-versions"
           Exports the "Features from Test::Version".

       "-default"
           Exports the default features -- all of the above except "-deprecated", "-pod",
           "-versions", and "-deeper". Also exports "object_ok".

       "-all"
           Exports all of the above features including "-deprecated", "-pod", "-versions",
           "-deeper", "object_ok", and "shouldnt_warn".

       "-author", "-extended", "-interactive", and "-release"
           Classify the test script.

       "-benchmark"
           The test script consists mostly of benchmarking.

       "-internet"
           The test script requires Internet access.

       "-requires", "-without"
           Specify modules required or hidden for these test cases.

       "-lib"
           Makes the absence of a "t/lib" directory fatal.

           See "Features inspired by Test::Lib".

       "-verbose"
           Makes test output more verbose. (Currently only "is_faster" takes notice of this.)

       $TODO is currently always exported.

ENVIRONMENT

       Test::Modern is affected by the following environment variables:

       "AUTHOR_TESTING", "AUTOMATED_TESTING", "EXTENDED_TESTING", "RELEASE_TESTING"
           These variables affect the behaviour of Test::Modern's pod-checking and version-
           checking. See "Features from Test::Pod and Test::Coverage" and "Features from
           Test::Version".

           They also can trigger certain import tags to skip a test script. See "Features
           inspired by Test::DescribeMe", and "Features inspired by Test::Benchmark"

       "NO_NETWORK_TESTS"
           Automatically skips any tests which indicate that they require Internet access,
           without even checking to see if the Internet is accessible.  See "Features inspired by
           Test::RequiresInternet".

       "PERL_TEST_MODERN_ALLOW_WARNINGS"
           Setting this to true allows you to disable Test::Warnings' end test.

           Normally the end test will cause a test script to fail if any unexpected warnings are
           encountered during its execution. New versions of Perl, and upgrades of dependencies
           can cause a previously good test suite to start emitting warnings. This environment
           variable can be used as a "quick fix" to get the test suite passing again.

BUGS

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

SEE ALSO

       My Favourite Test::* Modules <http://blogs.perl.org/users/toby_inkster/2014/02/my-
       favourite-test-modules.html>, Precision Testing for Modern Perl
       <http://blogs.perl.org/users/toby_inkster/2014/03/precision-testing-for-modern-perl.html>.

       Test::More, Test::Fatal, Test::Warnings, Test::API, Test::LongString, Test::Deep,
       Test::Moose, Test::CleanNamespaces, Test::Requires, Test::Without::Module,
       Test::RequiresInternet, Test::DescribeMe, Test::Lib, Test::Pod, Test::Pod::Coverage,
       Test::Version.

       Test::Most is a similar idea, but provides a slightly different combination of features.

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

       This software is copyright (c) 2014 by Toby Inkster.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
       WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
       PURPOSE.