Assert::Refute::Build - tool for extending Assert::Refute suite
Although arbitrary checks may be created using just the refute function, they may be cumbersome to use and especially share.
refute
This module takes care of some boilerplate as well as maintains parity between functional and object-oriented interfaces of Assert::Refute.
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').
args
ok 1
ok 1 'test passed'
All functions are exportable.
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");
"$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.
@CARP_NOT
NOTE One needs to use Exporter explicitly if either export or export_ok option is in use. This MAY change in the future.
export
export_ok
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.
no_create
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.
manual
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.
nnn
list => 1 - create a list prototype instead. Mutually exclusive with args.
list
block => 1 - create a block function.
block
no_proto => 1 - skip prototype, function will have to be called with parentheses.
no_proto
The name must not start with set_, get_, or do_. Also colliding with a previously defined name would case an exception.
set_
get_
do_
Returns a Assert::Refute::Report object. Dies if no contract is being executed at the time.
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').
'(undef)'
'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.
This module is part of Assert::Refute suite.
Copyright 2017-2018 Konstantin S. Uvarin. <khedin at cpan.org>
<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
To install Assert::Refute, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Assert::Refute
CPAN shell
perl -MCPAN -e shell install Assert::Refute
For more information on module installation, please visit the detailed CPAN module installation guide.