NAME

Test::Effects - Test all effects at once (return value, I/O, warnings, exceptions, etc.)

VERSION

This document describes Test::Effects version 0.002000

SYNOPSIS

use Test::Effects;

# Test all possible detectable side-effects of some code...
effects_ok { your_code_here() }
       {
           return => $expected_scalar_context_return_value,
           warn   => qr/match expected warning text/,
           stdout => '',  # i.e. Doesn't print anything.
       }
       => 'Description of test';


# Test only specifically requested side-effects of some code...
effects_ok { your_code_here() }
       ONLY {
           return => \@expected_list_context_return_values,
           stderr => 'Expected output to STDERR',
           die    => undef,  # i.e. Doesn't die.
           exit   => undef,  # i.e. Doesn't exit either.
       }
       => 'Description of test';


# Test that some code has no detectable side-effects...
effects_ok { your_code_here() };

DESCRIPTION

Test::Effects provides a single exported subroutine: effects_ok

This sub expects a block of code (or sub ref) as its first argument, followed by an optional hash ref as its second, and an optional string as its third.

The first argument specifies some code to be tested. This code is run in void context by default, but may instead be called in either list or scalar context, depending on the test specification provided by the second argument. The block is run within a call to Test::Trap::trap(), so all warnings, exceptions, output, and exit attempts are trapped. The block may contain calls to other Test::Builder-based testing modules; these are handled correctly within the overall test.

The second argument is a hash reference, whose entries specify the expected side-effects of executing the block. You specify the name of the side-effect you're interested in as the key, and the "effect" you expected as the value. Side-effects that are not explicitly specified are automatically tested for default behaviour (e.g. no warnings, no exceptions, no output, not call to exit(), etc. If the entire hash is omitted, all possible side-effects are tested for default behaviour (in other words, did the block of code have no side-effects whatsoever?)

The third argument is the overall description of the test (i.e. the usual final argument for Perl tests). If omitted, effects_ok() generates a description based on the line number at which it was called.

INTERFACE

`use Test::Effects;`

Loads the module, and exports the effects_ok(), VERBOSE(), ONLY(), and TIME() subroutines (see below). Also exports the standard interface from the Test::More module.

`use Test::Effects tests => $N;`

Exactly the same as:

use Test::More tests => $N;

In fact, use Test::Effects can take all the same arguments as use Test::More.

`use Test::Effects import => [':minimal'];`

Only export the effects_ok() subroutine.

Do not export VERBOSE(), ONLY(), TIME(), or any of the Test::More interface.

`use Test::Effects import => [':more'];`

Only export the effects_ok() subroutine and the Test::More interface

Do not export VERBOSE(), ONLY(), or TIME().

`effects_ok {BLOCK} {EFFECTS_HASH} => 'TEST_DESCRIPTION';`

Test the code in the block, ensuring that the side-effects named by the keys of the hash match the corresponding hash values. Both the hash and the description arguments are optional.

The effects that can be specified as key/value pairs in the hash are:

void_return => undef

Call the block in void context.

return => $ARRAY_REFERENCE

list_return => $ANY_SCALAR_VALUE

Call the block in list context. The final value evaluated in the block should (deeply) match the specified array ref or scalar value of the option.

return => $NON_ARRAYREF

scalar_return => $ANY_SCALAR_VALUE

Call the block in scalar context. The final value evaluated in block should match the specified scalar value of the option.

stdout => $STRING

What the block wrote to STDOUT should be eq to $STRING.

stdout => $REGEX

What the block wrote to STDOUT should be match $REGEX.

stdout => $CODE_REF

The subroutine specified by the code ref should return true when passed what the block wrote to STDOUT.

The subroutine can call nested tests (such as Test::More's is) or Test::Tolerant's is_tol) and these will be correctly handled.

stderr => $STRING

stderr => $REGEX

stderr => $CODE_REF

What the block writes to STDERR should "match" the specified value (either eq, or =~, or return true when passed as an argument).

Note that, if this option is not specified, but the 'warn' option (see below) is specified, then this option defaults to the value of the 'warn' option.

warn => $STRING

warn => $REGEX

warn => $CODE_REF

warn => [ $STRING1, $REGEX2, $CODE_REF3, $ETC ]

The block should issue the specified number of warnings, and each of these warnings should match the corresponding value specified, in the order specified.

die => $STRING

die => $REGEX

die => $CODE_REF

The block should raise an exception, which should match the value specified.

Note: when using OO exceptions, use a code ref to test them:

die => sub { shift->isa('X::BadData') }

You can also use Test::More-ish tests, if you prefer:

die => sub { isa_ok(shift, 'X::BadData') }

exit => $NUMBER

exit => $REGEX

exit => $CODE_REF

The block should call exit() and the exit code should match the value specified.

timing => { min => $MIN_SEC, max => $MAX_SEC }

timing => [$MIN_SEC, $MAX_SEC]

timing => $MAX_SEC

This option performs a separate timing measurment for the block, by running it multiple times over at least 1 cpu-second and averaging the times required for each run (i.e. like the Benchmark module does).

When passed a hash reference, the 'min' and 'max' entries specify the range of allowable timings (in seconds) for the block. For example:

# Test our new snooze() function...
effects_ok { snooze(1.5, plus_or_minus=>0.2); }
           {
                timing => { min => 1.3, max => 1.7 },
           }
           => 'snooze() slept about the right amount of time';

The default for 'min' is zero seconds; the default for 'max' is eternity.

If you use an array reference instead of a hash reference, the first value in the array is taken as the minimum time, and the final value is taken as the maximum allowed time. Hence the above time specification could also be written:

timing => [ 1.3, 1.7 ],

But don't write:

timing => [ 1.3 .. 1.7 ],

(unless your limits are integers), because Perl truncates the bounds of a range, so it treats [1.3 .. 1.7] as [1 .. 1].

If you use a number instead of a reference, then number is taken as the maximum time allowed:

timing => 3.2,    # Same as: timing => { min => 0, max => 3.2 }

If you do not specify either time limit:

timing => {},

or:

timing => [],

then the "zero-to-eternity" defaults are used and effects_ok() simply times the block and reports the timing (as a success).

Note that the timings measured using this option are considerably more accurate than those produced by the TIME => 1 option (see below), but also take significantly longer to measure.

Other configuration options that can be specified as key/value pairs in the hash are:

VERBOSE => $BOOLEAN

If the value is true, all side-effect tests are reported individually (running them in a subtest).

When this option is false (or omitted) only the overall result, plus any individual failures, are reported.

ONLY => $BOOLEAN

If the value is true, only the effects explicitly requested by the other keys of this hash are tested for. In other words, this option causes effects_ok() to omit the "default" tests for unnamed side-effects.

When this option is false (or omitted) unspecified options are tested for their expected default behaviour.

TIME => $BOOLEAN

If the value is true, the block is timed as it is executed. The timing is reported in the final TAP line.

Note that this option is entirely independent of the 'timing' option (which times the block repeatedly and then tests it against specified limits).

In contrast, the 'TIME' option merely times the block once, while it is being evaluated for the other tests. This is much less accurate, but also much faster and much less intrusive, when you merely want an rough indication of performance.

WITHOUT => 'Module::Name'

WITHOUT => qr/Module::.*/

Execute the block as if the specified module (or all modules matching the specified pattern) were not installed.

WITHOUT => 'lib/path/'

WITHOUT => qr{lib/*}

Execute the block as if the specified library directory (or all directories matching the specified pattern) were not accessible.

The specified patch must include at least one slash (/), otherwise it will be interpreted as a module name (see above). You can always add a redundant slash at the end of the path, if necessary:

WITHOUT => 'lib',     # Test without the C<lib.pm> module

WITHOUT => 'lib/',    # Test without the C<lib> directory

`VERBOSE $HASH_REF`

A call to:

effects_ok { BLOCK }
           VERBOSE { return => 0, stdout => 'ok' }

is just a shorthand for:

effects_ok { BLOCK }
           { return => 0, stdout => 'ok', VERBOSE => 1 }

`ONLY $HASH_REF`

A call such as:

effects_ok { BLOCK }
           ONLY { return => 0, stdout => 'ok' }

is just a shorthand for:

effects_ok { BLOCK }
           { return => 0, stdout => 'ok', ONLY => 1 }

`TIME $HASH_REF`

A call such as:

effects_ok { BLOCK }
           TIME { return => 0, stdout => 'ok' }

is just a shorthand for:

effects_ok { BLOCK }
           { return => 0, stdout => 'ok', TIME => 1 }

Note that the VERBOSE, ONLY, and TIME subs can be "stacked" (in any combination and order):

effects_ok { BLOCK }
           TIME ONLY VERBOSE { return => 0, stdout => 'ok' }

effects_ok { BLOCK }
           VERBOSE ONLY { return => 0, stdout => 'ok' }

`use Test::Effects::VERBOSE;`

This causes every subsequent call to effects_ok() in the current lexical scope to act as if it had a VERBOSE => 1 option set.

Note, however, that an explicit VERBOSE => 0 in any call in the scope overrides this default.

`no Test::Effects::VERBOSE;`

This causes every subsequent call to effects_ok() in the current lexical scope to act as if it had a VERBOSE => 0 option set. Again, however, an explicit VERBOSE => 1 in any call in the scope overrides this default.

`use Test::Effects::ONLY;`

This causes every subsequent call to effects_ok() in the current lexical scope to act as if it had a ONLY => 1 option set.

Note, however, that an explicit ONLY => 0 in any call in the scope overrides this default.

`no Test::Effects::ONLY;`

This causes every subsequent call to effects_ok() in the current lexical scope to act as if it had a ONLY => 0 option set. Again, however, an explicit ONLY => 1 in any call in the scope overrides this default.

`use Test::Effects::TIME;`

This causes every subsequent call to effects_ok() in the current lexical scope to act as if it had a TIME => 1 option set.

Note, however, that an explicit TIME => 0 in any call in the scope overrides this default.

`no Test::Effects::TIME;`

This causes every subsequent call to effects_ok() in the current lexical scope to act as if it had no TIME => 0 option set. Again, however, an explicit TIME => 1 in any call in the scope overrides this default.

DIAGNOSTICS

Second argument to effects_ok() must be hash or hash reference, not %s

effects_ok() expects a hash as its second argument, but you passed something else. This can happen if you forget to put braces around a single option, such as:

effects_ok { test_code() }
           warn => qr/Missing arg/;

That needs to be:

effects_ok { test_code() }
           { warn => qr/Missing arg };

Or you may have accidentally used an array instead of a hash:

effects_ok { test_code() }
           [ warn => qr/Missing arg ];

That is not supported, as it is being reserved for a future feature.

"Invalid timing specification: timing => %s"

The 'timing' option expects a hash reference, array reference, or a single number as its value. You specified some value that was something else (and which effects_ok() therefore didn't understand).

CONFIGURATION AND ENVIRONMENT

Test::Effects requires no configuration files or environment variables.

DEPENDENCIES

Requires Perl 5.14 (or better).

Requires the Test::Trap module, v0.2.1 (or better).

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

Ironically, the test suite for this module is as yet unsatisfactory. (T.D.D. Barbie says: "Testing test modules is HARD!")

No other bugs have been reported.

Please report any bugs or feature requests to bug-test-effects@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Damian Conway <DCONWAY@CPAN.org>

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

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

cpanm

cpanm Test::Effects

CPAN shell

perl -MCPAN -e shell
install Test::Effects

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)

NAME

VERSION

SYNOPSIS

DESCRIPTION

INTERFACE

use Test::Effects;

use Test::Effects tests => $N;

use Test::Effects import => [':minimal'];

use Test::Effects import => [':more'];

effects_ok {BLOCK} {EFFECTS_HASH} => 'TEST_DESCRIPTION';

VERBOSE $HASH_REF

ONLY $HASH_REF

TIME $HASH_REF

use Test::Effects::VERBOSE;

no Test::Effects::VERBOSE;

use Test::Effects::ONLY;

no Test::Effects::ONLY;

use Test::Effects::TIME;

no Test::Effects::TIME;

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

AUTHOR

LICENCE AND COPYRIGHT

DISCLAIMER OF WARRANTY

Module Install Instructions

`use Test::Effects;`

`use Test::Effects tests => $N;`

`use Test::Effects import => [':minimal'];`

`use Test::Effects import => [':more'];`

`effects_ok {BLOCK} {EFFECTS_HASH} => 'TEST_DESCRIPTION';`

`VERBOSE $HASH_REF`

`ONLY $HASH_REF`

`TIME $HASH_REF`

`use Test::Effects::VERBOSE;`

`no Test::Effects::VERBOSE;`

`use Test::Effects::ONLY;`

`no Test::Effects::ONLY;`

`use Test::Effects::TIME;`

`no Test::Effects::TIME;`