NAME

Assert::Refute::Build - tool for extending Assert::Refute suite

DESCRIPTION

Although arbitrary checks may be created using just the refute function, they may be cumbersome to use and especially share.

This module takes care of some boilerplate as well as maintains parity between functional and object-oriented interfaces of Assert::Refute.

SYNOPSIS

Extending the test suite goes as follows:

    package My::Package;
    use Assert::Refute::Build;
    use parent qw(Exporter);

    build_refute is_everything => sub {
        return if $_[0] == 42;
        return "$_[0] is not answer to life, universe, and everything";
    }, export => 1, args => 1;

    1;

This can be later used inside production code to check a condition:

    use Assert::Refute qw(:all);
    use My::Package;
    my $fun_check = contract {
        is_everything( shift );
    };
    my $oo_check = contract {
        $_[0]->is_everything( $_[1] );
    }, need_object => 1;
    # ditto

    # apply $fun_check or $oo_check to a variable, get result

    my $log = $oo_check->apply(137);
    $log->is_passing; # nope
    $log->get_tap;    # get details

This call will create a prototyped function is_everything(...) in the calling package, with args positional parameters and an optional human-readable message. (Think ok 1, ok 1 'test passed').

FUNCTIONS

All functions are exportable.

build_refute name => \&CODE, %options

This function

• accepts a subroutine reference that returns a false value on success and a brief description of the discrepancy on failure (e.g. "$got != $expected");

  Note that this function does not need to know anything about the testing environment it is in, it just cares about its arguments (think pure function).

• builds an exportable wrapper around it that would talk to the most recent Assert::Refute::Report instance;

• adds a method with the same name to Assert::Refute::Report so that object-oriented and functional interfaces are as close to each other as possible.

As a side effect, Assert::Refute's internals are added to the caller's @CARP_NOT array so that carp/croak points to where the built function is actually used.

NOTE One needs to use Exporter explicitly if either export or export_ok option is in use. This MAY change in the future.

Options may include:

• export => 1 - add function to @EXPORT (Exporter still has to be used by target module explicitly).

• export_ok => 1 - add function to @EXPORT_OK (don't export by default).

• no_create => 1 - don't generate a function at all, just add to Assert::Refute's methods.

• manual => 1 - don't generate any code. Instead, assume that user has already done that and just add a method to Assert::Refute::Report and a prototyped exportable wrapper.

  This may be useful to create refutations based on subcontract or such.

  [EXPERIMENTAL].

• args => nnn - number of arguments. This will generate a prototyped function accepting nnn scalars + optional description.

• list => 1 - create a list prototype instead. Mutually exclusive with args.

• block => 1 - create a block function.

• no_proto => 1 - skip prototype, function will have to be called with parentheses.

The name must not start with set_, get_, or do_. Also colliding with a previously defined name would case an exception.

current_contract

Returns a Assert::Refute::Report object. Dies if no contract is being executed at the time.

to_scalar

Convert an arbitrary value into a human-readable string.

    to_scalar( $value )
    to_scalar( $value, $depth )

If $value is undefined and $depth is not given, returns '(undef)' (so that it's harder to confuse with a literal 'undef').

If $value is a scalar and $depth is not given, returns $value as is, without quoted or anything.

Otherwise returns Data::Dumper to depth $depth (or unlimited by default).

One SHOULD NOT rely on exact format of returned data.

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

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cpanm Assert::Refute

perl -MCPAN -e shell
install Assert::Refute