Test::YAFT - Yet another testing framework
use Test::YAFT; it "should pass this test" => got => scalar do { ... } => expect => $expected_value ;
Please accept the fact that I'm not English native speaker so this documentation may contain improper grammar or wording making it harder to understand.
If you encounter such place, please visit project's issue tracking.
This module combines features of multiple test libraries providing its own, BDD inspired, Context oriented, testing approach.
Assert function performs actual value comparison.
Expectation function provides object (Test::Deep::Cmp) describing expected value.
Similar concept to git, plumbing functions are used to build higher level asserts, expectations, and/or tools.
Please read following documentation how are other test libraries mapped into Test::YAFT workflow.
This document contains reference manual. If you want some kind of tutorial, please visit Test::YAFT::Introduction as well.
This module exports symbols using Exporter::Tiny.
use Test::YAFT qw[ :asserts ];
Assert functions are exported by default.
Every assert accepts (if any) test message as a first (positional) parameter, with restof parameters using named approach.
When assert performs multiple expectations internally, it always reports as one, using provided test message, failing early.
Named parameters are provided either via key/value pairs
ok "test title" => got => $value ;
or via builder functions
ok "test title" => got { build got } ;
Coding style note: I suggest to use coding style as presented in all examples, with one parameter per line, leading with fat comma.
return fail 'what failed'; return fail 'what failed' => diag => "diagnostic message" ; return fail 'what failed' => diag => sub { "diagnostic message" } ;
Likewise "fail" in Test::More it also always fails, but it also accepts additional parameter - diagnostic message to show.
When diagnostic message is a CODEREF, it is executed and its result is treated as list of diagnostic messages (passed to diag)
diag
had_no_warnings; had_no_warnings 'title';
Reexported from Test::Warnings
it "should be ..." => got => ... => expect => ... ;
Basic test primitive, used by all other test functions. It uses Test::Deep's cmp_deeply to compare values.
cmp_deeply
In addition to Test::Deep's stack also uses Test::Difference to report differences when failed.
Test::Deep
When expected value is Test::Deep::Bool then it uses Test::More's ok.
ok
Accepted named(-like) parameters:
it "should ..." => arrange { foo => "bar" } => arrange { bar => "baz" } ;
arrange { } blocks are evaluated in context of it-local frame before resolving value under test (got { }).
arrange { }
it
got { }
arrange { } blocks are always evaluated, even when value under test is provided as an exact value.
Custom diagnostic message, printed out in case of failure.
When specified no other diagnostic message is printed.
Can be string, arrayref of strings, or coderef returning strings.
Coderef gets two parameters - Test::Deep stack and value under test.
Expected value.
When specified and got { } block is used, additional expectation that it didn't die is executed before any other comparison.
Value under test.
When got { } block is used, it is evaluated and its error status is checked before actual comparison.
Expected error.
When specified and got { } block is used, additional expectation that it did die is executed before any other comparison.
When both expect and throws parameters are specified, throws takes precedence.
expect
throws
See also Test::YAFT::Test::Exception.
nok "shouldn't be ..." => got => ... ;
Simple shortcut to expect value behaving like boolean false.
ok "should be ..." => got => ... ;
Simple shortcut to expect value behaving like boolean true.
pass 'what passed';
Reexported from Test::More
there "should be ..." => got => ... => expect => ... ;
Alias for it, providing convenient word to form meaningful English sentence
Every expectation returns Test::Deep::Cmp object.
Reexported "all" in Test::Deep.
Reexported "any" in Test::Deep.
Reexported "array" in Test::Deep.
Reexported "array_each" in Test::Deep.
Reexported "arrayelementsonly" in Test::Deep.
Reexported "arraylength" in Test::Deep.
Reexported "arraylengthonly" in Test::Deep.
Reexported "bag" in Test::Deep.
Reexported "blessed" in Test::Deep.
Reexported "bool" in Test::Deep.
Reexported "code" in Test::Deep.
it "should not exceed maximum value" => got => $got => expect => expect_compare ('<=', $max) ;
Similar to "cmp_ok" in Test::More but provided as an expectation instead so it can be combined with other Test::Deep-based expectations.
it "should be a boring number" => got => $got => expect => expect_complement_to (42) ;
Negative expectation.
Usually it's easier to use overloaded complement operators ! or ~.
!
~
Boolean expectation.
Reexported "hash" in Test::Deep.
Reexported "hash_each" in Test::Deep.
Reexported "hashkeys" in Test::Deep.
Reexported "hashkeysonly" in Test::Deep.
Reexported "Isa" in Test::Deep. Instance or inheritance expectation.
Reexported "listmethods" in Test::Deep.
Reexported "methods" in Test::Deep.
Reexported "noclass" in Test::Deep.
Reexported "none" in Test::Deep.
Reexported "noneof" in Test::Deep.
Reexported "num" in Test::Deep.
Reexported "obj_isa" in Test::Deep.
Reexported "re" in Test::Deep.
Reexported "reftype" in Test::Deep.
Reexported "regexpmatches" in Test::Deep.
Reexported "regexponly" in Test::Deep.
Reexported "regexpref" in Test::Deep.
Reexported "regexprefonly" in Test::Deep.
Reexported "scalarref" in Test::Deep.
Reexported "scalarrefonly" in Test::Deep.
Reexported "set" in Test::Deep.
Reexported "shallow" in Test::Deep.
Reexported "str" in Test::Deep.
Reexported "subbagof" in Test::Deep.
Reexported "subhashof" in Test::Deep.
Reexported "subsetof" in Test::Deep.
Reexported "superbagof" in Test::Deep.
Reexported "superhashof" in Test::Deep.
Reexported "supersetof" in Test::Deep.
Reexported "useclass" in Test::Deep.
=> expect => expect_value (42)
Wraps any value as an expectation.
Reexported "ignore" in Test::Deep.
use Test::YAFT qw[ :helpers ];
Helper functions are exported by default.
Functions helping to organize your tests.
Reexported "BAIL_OUT" in Test::More
arrange { foo => "bar" }; it "should ..." => arrange { foo => "bar2" } => got { $foo->method (deduce 'foo') } => expect => ... ;
Arrange block is treated as a function providing arguments for Context::Singleton's proclaim.
proclaim
Arrange block returns a guard object, which is evaluated in frame valid at the time of evaluation (timely evaluation is responsibility of it).
When arrange { } is called in void context, it is evaluated immediately.
Validity of values follows Context::Singleton rules, so for example
# This is available globally arrange { foo => "global value" }; subtest "subtest" => sub { # This is available in scope of subtest (it creates its own frame) arrange { foo => "subtest local" }; # This is available only in scope of 'it' (ie, insite got { }) it "should ..." => got { ... } => arrange { foo => "assert local" } ; };
Reexported "diag" in Test::More
Reexported "done_testing" in Test::More
Reexported "explain" in Test::More
Can be used to specify code to build test value or to test that given code should / shouldn't throw an exception.
it "should die" => got { $foo->do_something } => throws => expect_obj_isa (...) ;
When used, it always checks error status first before checking provided expectations.
Reexported "note" in Test::More
Reexported "plan" in Test::More
Reexported "skip" in Test::More
subtest "title" => sub { ...; }
Similar to "subtest" in Test::More but also creates new Context::Singleton frame for each subtest.
Reexported "todo" in Test::More
Reexported "todo_skip" in Test::More
use Test::YAFT qw[ :plumbings ];
Functions helping writing your custom asserts, expectations, and/or tools. Plumbing functions are not exported by default.
use Test::YAFT qw[ cmp_details ]; my ($ok, $stack) = cmp_details ($a, $b);
Reexported "cmp_details" in Test::Deep.
use Test::YAFT qw[ deep_diag ]; deep_diag ($stack);
Reexported "deep_diag" in Test::Deep.
use Test::YAFT qw[ eq_deeply ]; if (eq_deeply ($a, $b)) { }
Reexported "eq_deeply" in Test::Deep.
Creates "anonymous" (as far as Perl supports) Test::Deep comparator class. Returns created class name.
Typical usage
sub expect_foo { state $class = test_deep_cmp ( isa => ..., descend => ..., renderGot => ..., ); $class->new (@_); }
Accepts named arguments
Parent class, default: Test::YAFT::Cmp.
Every other named parameter is treated as a method name to install into created namespace.
use Test::YAFT qw[ test_frame ]; sub my_assert { test_frame { ... }; }
Utility function to populate required boring details like
Branislav Zahradník <barney@cpan.org>
Test::YAFT distribution is distributed under Artistic Licence 2.0.
To install Test::YAFT, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::YAFT
CPAN shell
perl -MCPAN -e shell install Test::YAFT
For more information on module installation, please visit the detailed CPAN module installation guide.