"useTest::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.
"useTest::Effectstests=>$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".
"useTest::Effectsimport=>[':minimal'];"
Only export the "effects_ok()" subroutine.
Do not export "VERBOSE()", "ONLY()", "TIME()", or any of the Test::More interface.
"useTest::Effectsimport=>[':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' }
"useTest::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.
"noTest::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.
"useTest::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.
"noTest::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.
"useTest::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.
"noTest::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.
Install Now
PNG Icons
SVG Icons