NAME

Assert::Refute::Contract - Contract definition class for Assert::Refute suite

DESCRIPTION

This class represents a contract and is thus immutable.

See Assert::Refute::Report for its application to a specific case.

SYNOPSIS

    use Assert::Refute::Contract;

    my $contract = Assert::Refute::Contract->new(
        code => sub {
            my ($c, $life) = @_;
            $c->is( $life, 42 );
        },
        need_object => 1,
    );

    # much later
    my $result = $contract->apply( 137 );
    $result->get_count;  # 1
    $result->is_passing; # 0
    $result->get_tap;    # Test::More-like summary

DESCRIPTION

This is a contract specification class. See Assert::Refute::Report for execution log. See "contract" in Assert::Refute for convenient interface.

EXPORT

contract prototyped function is optionally exported.

contract { ... }

Save a contract BLOCK for future use:

    use Assert::Refute qw(:all);

    my $spec = contract {
        my ($foo, $bar) = @_;
        is $foo, 42, "Life";
        like $bar, qr/b.*a.*r/, "Regex";
    };

    # later
    my $report = $spec->apply( 42, "bard" );
    $report->get_count;  # 2
    $report->is_passing; # true
    $report->get_tap;    # printable summary *as if* it was Test::More

The same may be written as

    my $spec = contract {
        my ($report, @args) = @_;
        $report->is( ... );
        $report->like( ... );
    } need_object => 1;

The need_object form may be preferable if one doesn't want to pollute the main namespace with test functions (is, ok, like etc) and instead intends to use object-oriented interface.

Note that contract does not validate anything by itself, it just creates a read-only Assert::Refute::Contract object sitting there and waiting for an apply call.

The apply call returns a Assert::Refute::Report object containing results of specific execution.

This is similar to how prepare / execute works in DBI.

This function is equivalent to new (see below) but may be more convenient in some cases.

OBJECT-ORIENTED INTERFACE

new

    Assert::Refute::Contract->new( %options );

%options may include:

• code (required) - contract to be executed

• need_object - if given, a contract execution object will be prepended to code's argument list, as if it was a method.

  This allows to run a contract without exporting anything to the calling package.

  The name is not final, better suggestions wanted.

• args = n or args = [min, max] - set limitation on the number of accepted parameters. Negative maximum value means unlimited.

adjust( %overrides )

Return a copy of this object with some overridden fields.

The name is not perfect, better ideas wanted.

%overrides may include:

• driver - the class to perform tests.

apply( @parameters )

Spawn a new execution log object and run contract against it.

Returns a locked Assert::Refute::Report instance.

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

cpanm Assert::Refute

perl -MCPAN -e shell
install Assert::Refute