++ed by:

1 non-PAUSE user.

Konstantin S. Uvarin
and 2 contributors

NAME

Assert::Refute::Report - Contract execution class for Assert::Refute suite

DESCRIPTION

This class represents one specific application of contract. It is mutable, but can only changed in one way (there is no undo of tests and diagnostic messages). Eventually a done_testing locks it completely, leaving only "QUERYING PRIMITIVES" for inspection.

See Assert::Refute::Contract for contract definition.

SYNOPSIS

    my $c = Assert::Refute::Report->new;
    $c->refute ( $cond, $message );
    $c->refute ( $cond2, $message2 );
    # .......
    $c->done_testing; # no more refute after this

    $c->get_count;    # how many tests were run
    $c->is_passing;   # did any of them fail?
    $c->get_tap;      # return printable summary in familiar format

METHODS

new

    Assert::Refute::Report->new();

No arguments are currently supported.

RUNNING PRIMITIVES

plan( tests => $n )

Plan to run exactly n tests. This is not required, and "done_testing" (see below) is needed at the end anyway.

plan( skip_all => $reason )

Plan to run no tests at all. As of current, this does not prevent any future checks from being run.

In both cases, dies if there's already a plan, or tests are being run, or done_testing was seen.

If plan is not fullfilled by the time of done_testing call, a message indicating plan violation will be added, and the report will become unconditionally failing.

refute( $condition, $message )

An inverted assertion. That is, it passes if $condition is false.

Returns inverse of first argument. Dies if "done_testing" was called.

See "refute" in Assert::Refute for more detailed discussion.

diag

    diag "Message", \%reference, ...;

Add human-readable diagnostic message to report. References are auto-explained via Data::Dumper.

note

    diag "Message", \%reference, ...;

Add human-readable notice message to report. References are auto-explained via Data::Dumper.

done_testing

Stop testing. After this call, no more writes (including done_testing) can be performed on this contract. This happens by default at the end of contract{ ... } block.

Dies if called for a second time, unless an argument is given.

A true argument is considered to be the exception that interrupted the contract execution, resulting in an unconditionally failed contract.

A false argument just avoids dying and is equivalent to

    $report->done_testing
        unless $report->is_done;

Returns self.

context()

Get execution context hash with arbitrary user data.

Upon failure, the hash content is going to be appended to the log at diag level.

set_context( \%hash )

Set the context hash.

Only plain (not blessed) hash is allowed as argument.

TESTING PRIMITIVES

Assert::Refute comes with a set of basic checks similar to that of Test::More, all being wrappers around "refute" discussed above. They are available as both prototyped functions (if requested) and methods in contract execution object and its descendants.

The list is as follows:

is, isnt, ok, use_ok, require_ok, cmp_ok, like, unlike, can_ok, isa_ok, new_ok, contract_is, is_deeply, fail, pass, note, diag.

See Assert::Refute::T::Basic for more details.

Additionally, any checks defined using Assert::Refute::Build will be added to Assert::Refute::Report as methods unless explicitly told otherwise.

subcontract( "Message" => $specification, @arguments ... )

Execute a previously defined group of tests and fail loudly if it fails.

$specification may be one of:

[NOTE] that the message comes first, unlike in refute or other test conditions, and is required.

QUERYING PRIMITIVES

is_done

Tells whether done_testing was seen.

is_passing

Tell whether the contract is passing or not.

get_count

How many tests have been executed.

get_fail_count

How many tests failed

get_tests

Returns a list of test ids, preserving order.

get_result( $id )

Returns result of test denoted by $id, dies if such test was never performed. The result is false for passing tests and whatever the reason for failure was for failing ones.

get_result_details ($id)

Returns a hash containing information about a test:

  • number - the number of test (this is equal to argument);

  • name - name of the test (if any);

  • ok - whether the test was successful;

  • reason - the reason for test failing, if it failed; Undefined for "ok" tests.

  • diag - diagnostic messages as one array, without leading #;

  • log - any log messages that followed the test (see get_log for format)

  • subcontract - if test was a subcontract, contains the report.

Returns empty hash for nonexistent tests, and dies if test number is not integer.

As a special case, tests number 0 and -1 represent the output before any tests and postmortem output, respectively. These only contains the log and diag fields.

See also Assert::Refute::T::Tester.

[EXPERIMENTAL]. Name and meaning may change in the future.

get_error

Return last error that was recorded during contract execution, or false if there was none.

get_tap( $level )

Return a would-be Test::More script output for current contract.

The level parameter allows to adjust verbosity level. The default is 0 which includes passing tests, but not notes and/or debugging messages.

[NOTE] that diag is higher than ok.

  • -3 - something totally horrible, like Bail out!

  • -2 - a failing test

  • -1 - a diagnostic message, think Test::More/diag

  • 0 - a passing test

  • 1+ - a normally ignored verbose message, think "note" in Test::More

get_sign

Produce a terse pass/fail summary (signature) as a string of numbers and letters.

The format is "t(\d+|N)*[rdE]".

  • t is always present at the start;

  • a number stands for a series of passing tests;

  • N stands for a single failing test;

  • r stands for a contract that is still running;

  • E stands for a an exception during execution;

  • d stands for a contract that is done.

The format is still evolving. Capital letters are used to represent failure, and it is likely to stay like that.

The numeric notation was inspired by Forsyth-Edwards notation (FEN) in chess.

DEVELOPMENT PRIMITIVES

Generally one should not touch these methods unless when subclassing to build a new test backend.

When extending this module, please try to stick to do_*, get_*, and set_* to avoid clash with test names.

This is weird and probably has to be fixed at some point.

do_run( $code, @list )

Run given CODEREF, passing self as both first argument and current_contract(). Report object is locked afterwards via "done_testing" call.

Returns self.

Example usage is

    Assert::Refute::Report->new->run( sub {
        like $this, qr/.../;
        can_ok $that, qw(foo bar frobnicate);
    } );

do_log( $indent, $level, $message )

Append a message to execution log.

See "get_tap($level)" for level descriptions.

get_log

Return log messages "as is" as array reference containing triads of (indent, level, message).

[CAUTION] This currently returns reference to internal structure, so be careful not to spoil it. This MAY change in the future.

DEPRECATED METHODS

set_result

Was used inside refute() prior to 0.10. This is no more the case. This function just dies and will be removed completely in 0.15.

LICENSE AND COPYRIGHT

This module is part of Assert::Refute suite.

Copyright 2017-2018 Konstantin S. Uvarin. <khedin at cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0