Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Test::Modern(3)	      User Contributed Perl Documentation      Test::Modern(3)

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.

perl v5.24.1			  2014-10-05		       Test::Modern(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORT | ENVIRONMENT | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENCE | DISCLAIMER OF WARRANTIES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Test::Modern&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help