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 quotes 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

cpanm Assert::Refute

perl -MCPAN -e shell
install Assert::Refute