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.

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)

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::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::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

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, and object_ok.
-author, -extended, -interactive, and -release: Classify the test script.
-requires, -without: Specify modules required or hidden for these test cases.

$TODO is currently always exported.

BUGS

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

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

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.

To install Test::Modern, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Test::Modern

CPAN shell

perl -MCPAN -e shell
install Test::Modern

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)