Test::Tester2 - Tools for validating the results produced by your testing tools.
Unit tests are tools to validate your code. This library provides tools to validate your tools!
[Test Script] > [Test Tool] > [Test::Builder] > [Test::Bulder::Stream] > [Result Formatter]
A test script uses a test tool such as Test::More, which uses Test::Builder to produce results. The results are sent to Test::Builder::Stream which then forwards them on to one or more formatters. The default formatter is Test::Builder::Fromatter::TAP which produces TAP output.
use Test::More; use Test::Tester2; # Intercept all the Test::Builder::Result objects produced in the block. my $results = intercept { ok(1, "pass"); ok(0, "fail"); diag("xxx"); }; # By Hand is($results->[0]->{bool}, 1, "First result passed"); # With help results_are( $results, ok => { id => 'a', bool => 1, name => 'pass' }, ok => { id => 'b1', bool => 0, name => 'fail', line => 7, file => 'my_test.t' }, diag => { id => 'b2', message => qr/Failed test 'fail'/, line => 7, file => 'my_test.t' }, diag => { id => 'c', message => qr/xxx/ }, end => 'Name of this test', ); # You can combine the 2: results_are( intercept { ... }, ok => { bool => 1 }, ... ); done_testing;
Capture the Test::Builder::Result objects generated by tests inside the block.
Validate the given results.
This will produce a simplified string of the result data for easy reading. This is useful in debugging, in fact this is the same string that results_are will print when there is a mismatch to show you the result.
These will print the render_result string to STDERR.
my $results = intercept { ok(1, "pass"); ok(0, "fail"); diag("xxx"); };
Any results generated within the block will be intercepted and placed inside the $results array reference.
$results
All results will be subclasses of Test::Builder::Result
my $results = intercept { ok(1, "pass"); ok(0, "fail"); diag("xxx"); }; results_are( $results, name => 'Name of the test', # Name this overall test ok => { id => 'a', bool => 1, name => 'pass' }, # check an 'ok' with ID 'a' ok => { id => 'b', bool => 0, name => 'fail' }, # check an 'ok' with ID 'b' diag => { message => qr/Failed test 'fail'/ }, # check a 'diag' no ID diag => { message => qr/xxx/ }, # check a 'diag' no ID 'end' # directive 'end' );
The first argument to results_are() must be an arrayref containing Test::Builder::Result objects. Such an arrayref can be produced by intercept { ... }.
results_are()
intercept { ... }
All additional arguments to results_are() must be key value pairs (except for 'end'). The key must either be a directive, or a result-type optionally followed by a name. Values for directives are specific to the directives. Values for result types must always be hashrefs with 0 or more fields to check.
Since you can provide many checks, it can be handy to ID them. If you do not provide an ID then they will be assigned a number in sequence starting at 1. You can specify an ID by passing in the 'id' parameter.
ok => { id => 'foo', ... }
This can be very helpful when tracking down the location of a failing check.
The hashref against which results are checked is composed of keys, and values. The values may be regular values, which are checked for equality with the corresponding property of the result object. Alternatively you can provide a regex to match against, or a coderef that validates it for you.
The specified field must exactly match the given value, be it number or string.
The specified field must match the regular expression.
The value from the result will be passed into your coderef as the only argument. The coderef should return true for valid, false for invalid.
The process ID the result came from.
Usually 0, but will be 1 for subtests, 2 for nested subtests, etc.
Usually $0, but in a subtest it will be the name of the subtest that generated the result.
True if the result was generated inside a todo.
Line number to which failures will be reported.
(This is actually usually undefined for plan and finish)
File to which failures will be reported
package to which errors will be reported
Note: Only present if applicable.
If the result was generated by an Test::Builder::Provider, this will tell you what package provided the tool.
For example, if the result was provided by Test::More::ok() this will contain 'Test::More'.
Test::More::ok()
'Test::More'
If the result was generated by an Test::Builder::Provider, this will tell you what the tool was called.
For example, if the result was provided by Test::More::ok() this will contain 'ok'.
'ok'
The TAP string that would be printed by the TAP formatter. This is particularily useful for diags since it translates filenames into the proper encoding, the original message however will be untranslated.
True if the test passed (or failed but is in todo).
The actual result of the test, not mangled by todo.
The name of the test.
The todo reason.
The reason the test was skipped.
Message for the diag/note.
Will be a number if a numeric plan was issued.
Usually empty, but may be 'skip_all' or 'no_plan'
Reason for the directive.
Number of tests that ran.
Number of tests that failed.
Reason the test bailed.
Name of the child
True if the child was created to start subtests
Always either 'push' or 'pop'. 'push' when a child is created, 'pop' when a child is destroyed.
These provide ways to filter or skip results. They apply as seen, and do not effect checks before they are seen.
Filter results so that you only see ones where the tool provider matches one or more of the conditions specified. Conditions may be a value to match, a regex to match, or a codref that takes the provider name and validates it returning either true or false.
Prefixing with '!' will negate the matching, that is only tool providers that do not match will be checked.
The filter will remove any results that do not match for the remainder of the checks. Checks before the directive are used will see unfiltered results.
example:
my $results = intercept { Test::More::ok(1, "foo"); Test::More::ok(1, "bar"); Test::More::ok(1, "baz"); Test::Simple::ok(1, "bat"); }; results_are( $results, ok => { name => "foo" }, ok => { name => "bar" }, # From this point on, only more 'Test::Simple' results will be checked. filter_provider => 'Test::Simple', # So it goes right to the Test::Simple result. ok => { name => "bat" }, );
Filter results so that you only see ones where the type matches one or more of the conditions specified. Conditions may be a value to match, a regex to match, or a codref that takes the provider name and validates it returning either true or false.
Prefixing with '!' will negate the matching, that is only types that do not match will be checked.
my $results = intercept { ok(1, "foo"); diag("XXX"); ok(1, "bar"); diag("YYY"); ok(1, "baz"); diag("ZZZ"); }; results_are( $results, ok => { name => "foo" }, diag => { message => 'XXX' }, ok => { name => "bar" }, diag => { message => 'YYY' }, # From this point on, only 'diag' types will be seen filter_type => 'diag', # So it goes right to the next diag. diag => { message => 'ZZZ' }, );
The numeric form will skip the next # results.
my $results = intercept { ok(1, "foo"); diag("XXX"); ok(1, "bar"); diag("YYY"); ok(1, "baz"); diag("ZZZ"); }; results_are( $results, ok => { name => "foo" }, skip => 1, # Skips the diag ok => { name => "bar" }, skip => 2, # Skips a diag and an ok diag => { message => 'ZZZ' }, );
When '*' is used as an argument, the checker will skip until a result type matching the next type to check is found.
my $results = intercept { ok(1, "foo"); diag("XXX"); diag("YYY"); diag("ZZZ"); ok(1, "bar"); }; results_are( $results, ok => { name => "foo" }, skip => '*', # Skip until the next 'ok' is found since that is our next check. ok => { name => "bar" }, );
When turned on (true), any unexpected results will be skipped. You can turn this on and off any time.
my $results = intercept { ok(1, "foo"); diag("XXX"); diag("YYY"); ok(1, "bar"); diag("ZZZ"); ok(1, "baz"); }; results_are( $results, seek => 1, ok => { name => "foo" }, # The diags are ignored, ok => { name => "bar" }, seek => 0, # This will fail because the diag is not ignored anymore. ok => { name => "baz" }, );
Used to name the test when not using 'end'.
Used to say that there should not be any more results. Without this any results after your last check are simply ignored. This will generate a failure if any unchecked results remain.
This is also how you can name the overall test. The default name is 'Got expected results'.
Deprecated predecessor to this module
The original test tester, checks TAP output
Copyright 2014 by Chad Granum <exodist7@gmail.com>
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://www.perl.com/perl/misc/Artistic.html
2 POD Errors
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install Test::Simple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Simple
CPAN shell
perl -MCPAN -e shell install Test::Simple
For more information on module installation, please visit the detailed CPAN module installation guide.