view release on metacpan or  search on metacpan

lib/Test/Most.pm  view on Meta::CPAN

=head2 C<explain>

Similar to C<note()>, the output will only be seen by the user by
using the C<-v> switch with C<prove> or reading the raw TAP.

Unlike C<note()>, any reference in the argument list is automatically expanded
using C<Data::Dumper>.  Thus, instead of this:

 my $self = Some::Object->new($id);
 use Data::Dumper;
 explain 'I was just created', Dumper($self);

You can now just do this:

 my $self = Some::Object->new($id);
 explain 'I was just created:  ', $self;

That output will look similar to:

 I was just created: bless( {
   'id' => 2,
   'stack' => []
 }, 'Some::Object' )

Note that the "dumpered" output has the C<Data::Dumper> variables
C<$Indent>, C<Sortkeys> and C<Terse> all set to the value of C<1> (one).  This
allows for a much cleaner diagnostic output and at the present time cannot be
overridden.

Note that Test::More's C<explain> acts differently.  This C<explain>
is equivalent to C<note explain> in Test::More.

=head2 C<show>

Experimental.  Just like C<explain>, but also tries to show you the lexical
variable names:

 my $var   = 3;
 my @array = qw/ foo bar /;
 show $var, \@array;
 __END__
 $var = 3;
 @array = [
     'foo',
     'bar'
 ];

It will show C<$VAR1>, C<$VAR2> ... C<$VAR_N> for every variable it cannot
figure out the variable name to:

 my @array = qw/ foo bar /;
 show @array;
 __END__
 $VAR1 = 'foo';
 $VAR2 = 'bar';

Note that this relies on L<Data::Dumper::Names> version 0.03 or greater.  If
this is not present, it will warn and call L<explain> instead.  Also, it can
only show the names for lexical variables.  Globals such as C<%ENV> or C<%@>
are not accessed via PadWalker and thus cannot be shown.  It would be nice to
find a workaround for this.

=head2 C<always_explain> and C<always_show>

These are identical to C<explain> and C<show>, but like L<Test::More>'s
C<diag> function, these will always emit output, regardless of whether or not
you're in verbose mode.

=head2 C<all_done>

B<DEPRECATED>.  Use the new C<done_testing()> (added in
L<Test::More|Test::More> since 0.87_01).  Instead. We're leaving this in here
for a long deprecation cycle.  After a while, we might even start warning.

If the plan is specified as C<defer_plan>, you may call C<&all_done> at the
end of the test with an optional test number.  This lets you set the plan
without knowing the plan before you run the tests.

If you call it without a test number, the tests will still fail if you don't
get to the end of the test.  This is useful if you don't want to specify a
plan but the tests exit unexpectedly.  For example, the following would
I<pass> with C<no_plan> but fails with C<all_done>.

 use Test::More 'defer_plan';
 ok 1;
 exit;
 ok 2;
 all_done;

See L<Deferred plans> for more information.

=head1 EXPORT ON DEMAND

The following will be exported only if requested:

=head2 C<timeit>

Prototype: C<timeit(&;$)>

This function will warn if C<Time::HiRes> is not installed. The test will
still be run, but no timing information will be displayed.

 use Test::Most 'timeit';
 timeit { is expensive_function(), $some_value, $message }
    "expensive_function()";
 timeit { is expensive_function(), $some_value, $message };

C<timeit> accepts a code reference and an optional message. After the test is
run, will C<explain> the time of the function using C<Time::HiRes>. If a
message is supplied, it will be formatted as:

  sprintf "$message: took %s seconds" => $time;

Otherwise, it will be formatted as:

  sprintf "$filename line $line: took %s seconds" => $time;

=head1 DIE OR BAIL ON FAIL

Sometimes you want your test suite to throw an exception or BAIL_OUT() if a