/ 
Assert-Refute-0.17
River stage one • 5 direct dependents • 5 total dependents
/ Assert::Refute::Report

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.

set_title

Set the a contract title that briefly explains what we are trying to prove, and why.

See also "get_title".

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

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:

  • code reference - will be executed in eval block, with a new Assert::Refute::Report passed as argument.

    Exceptions are rethrown, leaving a failed contract behind.

    $report->subcontract( "My code" => sub {
    my $new_report = shift;
    # run some checks here
} );

  • Assert::Refute::Contract instance - apply() will be called;

    As of v.0.15, contract swallows exceptions, leaving behind a failed contract report only. This MAY change in the future.

  • Assert::Refute::Report instance from a previously executed test.

[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_failed_ids

List the numbers of tests that failed.

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.

get_title

Returns the contract title that briefly explains what we are trying to prove, and why.

See also "set_title".

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

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.

Exceptions are rethrown. As of current, an exception in CODEREF leaves report in an unfinished state. This may or may not change in the future.

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.

set_parent

$report->set_parent($bigger_report);
$report->set_parent(undef);

Indicate that a contract is part of a larger one. The parent object should be an Assert::Refute::Report instance. The parent object reference will be weakened to avoid memory leak.

Provide undef as argument to erase parent information.

Returns self, so that calls to set_parent can be chained.

This is used internally by "subcontract".

NOTE As of 0.16, no isa/DOES check on the argument is enforced. It must be blessed, however. This MAY change in the future.

get_parent

Return parent contract, i.e. the contract we are subcontract of, if any.

Always check get_parent to be defined as it will vanish if parent object goes out of scope. This is done so to avoid memory leak in subcontract call.

get_depth

Returns 0 is there is no parent, or parent's depth + 1. This of this as "this contract's indentation level".

EXPERIMENTAL. Name and meaning MAY change in the future.

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