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-module
    s.html>, Precision Testing for Modern Perl
    <http://blogs.perl.org/users/toby_inkster/2014/03/precision-testing-for-mo
    dern-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.

