NAME
Test2::Tools::ComboObject - Combine checks and diagnostics into a single test as an object
VERSION
version 0.01
SYNOPSIS
use Test2::V0;
use Test2::Tools::ComboObject;
use feature qw( signatures );
sub my_test_tool ($test_name //='my test tool', @numbers) {
my $combo = combo $test_name;
foreach my $number (@numbers) {
if($number % 2) {
$combo->fail("$number is not even");
} else {
$combo->pass;
}
}
return $combo->finish;
}
my_test_tool undef, 4, 6, 8, 9, 100, 200, 300, 9999, 2859452842;
my_test_tool 'try again', 2, 4, 6, 8;
done_testing;output:
prove -lvm examples/synopsis.t
examples/synopsis.t ..
# Seeded srand with seed '20241121' from local date.
not ok 1 - my test tool
# Failed test 'my test tool'
# at examples/synopsis.t line 17.
# 9 is not even
# 9999 is not even
ok 2 - try again
1..2
Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/2 subtests
Test Summary Report
-------------------
examples/synopsis.t (Wstat: 256 (exited 1) Tests: 2 Failed: 1)
Failed test: 1
Non-zero exit status: 1
Files=1, Tests=2, 0 wallclock secs ( 0.00 usr 0.00 sys + 0.03 cusr 0.00 csys = 0.03 CPU)
Result: FAILDESCRIPTION
Combine multiple checks into a single test. Sometimes you want a test tool that has multiple possible failure points, but you want to hide that complexity from the user of your test tool. This class helps provide a OO interface to make this easy without having to track status and diagnostics in separate variables.
If any one check fails the test will fail. If all checks pass then the test will pass. You can log diagnostics which will be directed to either diag or note depending on if the test fails or passes (respectively) overall.
ATTRIBUTES
context
my $ctx = $combo->context;The Test2::API::Context context. When created, this context takes into account the extra stack frames so that any failure diagnostics will point back to the call point of your tool.
name
my $name = $combo->name;The string name of the test. The default combo object test will be used if not provided.
status
The boolean status of the test. Zero 0 for failure and One 1 for pass. You should generally not set this yourself directly, and instead use "pass", "fail" or "ok" below.
FUNCTIONS
combo
my $combo = combo $test_name;
my $combo = combo;Exported by default. Takes an optional test name. Will use combo object test if not provided.
METHODS
Note that methods that do not specify a return type will return the combo object, so such methods may be chained.
finish
my $status = $combo->finish;Complete the combo test by generating the appropriate Test2 events and release its context. It also returns the pass/fail status, to make it a good choice to return from your tool, since it is a common practice for tools to return true/false when the pass/fail (respectively).
sub test_tool {
my $combo = combo;
...
return $combo->finish;
}If the the combo object is not explicitly finished when the object is destroyed then it will be finished for you in its destructor.
log
$combo->log(@messages);Include the given @messages as either a diag or note if the test overall fails or passes (respectively).
pass
$self->pass;
$self->pass(@messages);Marks a passing check. @messages if provided will be added to the log.
fail
$self->fail;
$self->fail(@messages);Marks a failing check. @messages if provided will be added to the log.
ok
$self->ok($status);
$self->ok($status, @messages);Marks a passing or failing check depending on if the $status is true or false (respectively). @messages if provided will be added to the log.
CAVEATS
This class creates a Test2::API::Context, and does release it when the object is either finished (via "finish") or when it falls out of scope. Because of this any caveats about storing and releasing contexts also applies to objects of this class.
AUTHOR
Graham Ollis <plicease@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2024 by Graham Ollis.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.