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.

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:

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:

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.

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.

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.

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.

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

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.