Test::Tester2 - Tools for validating the events 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] > [Event Formatter]
A test script uses a test tool such as Test::More, which uses Test::Builder to produce events. The events 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::Event objects produced in the block. my $events = intercept { ok(1, "pass"); ok(0, "fail"); diag("xxx"); }; # Or grab them without adding a scope to your stack: my $grab = grab(); ok(1, "pass"); ok(0, "fail"); diag("xxx"); my $events = $grab->finish; # Note, $grab is undef after this. # By Hand is($events->[0]->{bool}, 1, "First event passed"); # With help events_are( $events, ok => { bool => 1, name => 'pass' }, ok => { bool => 0, name => 'fail', line => 7, file => 'my_test.t', diag => [ diag => { message => qr/Failed test 'fail'/, line => 7, file => 'my_test.t' }, ] }, diag => { message => qr/xxx/, debug_line => __LINE__ }, end => 'Name of this test', ); # You can combine the 2: events_are( intercept { ... }, ok => { bool => 1 }, ... ); # With better debugging, this automatically adds debug_line => __LINE__ for events events_are( $events, check { event ok => { bool => 1 }; ... dir end => 'name of test'; } ); done_testing;
use Test::More; use Test::Tester2; # Start capturing events. We use grab() instead of intercept {} to avoid # adding stack frames. my $grab = grab(); # Generate some events. my $success = eval { # Wrap in an eval since we also test BAIL_OUT ok(1, "pass"); ok(0, "fail"); diag("xxx"); # BAIL_OUT and plan SKIP_ALL must be run in an eval since they throw # their events as exceptions (the events are also added to the grab # object). BAIL_OUT "oops"; ok(0, "Should not see this"); 1; }; # Save the error for later my $error = $@; # Stop capturing events, and validate the ones recieved. # We use check {} with event() for useful debugging. events_are( $grab, check { event ok => { bool => 1, name => 'pass' }; event ok => { bool => 0, name => 'fail' }; event diag => { message => 'xxx' }; event bail => { reason => 'oops' }; directive end => 'Validate our Grab results'; }); # $grab is now undef, it no longer exists. ok(!$success, "Eval did not succeed, BAIL_OUT killed the test"); # Make sure we got the event as an exception isa_ok($error, 'Test::Stream::Event::Bail'); done_testing
Capture the Test::Builder::Event objects generated by tests inside the block.
Validate the given events.
Produce an array of checks for use in events_are.
events_are { $EVENTS, check { # The list that check() returns is passed in as a reference as the # only argument to the block. my ($OUTPUT) = @_; event TYPE => ( ... ); ... } # When the block exits, all events and directives are returned. The # benefit here is that debugging information such as the line number # the event check was defined on is added for you, this makes it easier # to figure out where your expectations and results diverge. }
Define an event and push it onto the list that will be returned by the enclosing check { ... } block. Will fail if run outside a check block. This will fail if you give it an invalid event type.
check { ... }
You may give it a hashref, or an even list as arguments, your choice.
debug_line => __LINE__ is effectively added to each item, this makes tracing a problem easier.
CAVEAT the line given to debug_line is taken from caller(), so it will normally be the line of the final semicolon. This is only noticable on multi-line event checks, but is rarely an issue.
caller()
Define a directive and push it onto the list that will be returned by the enclosing check { ... } block. This will fail if run outside of a check block.
This will produce a simplified string of the event data for easy reading. This is useful in debugging, in fact this is the same string that events_are will print when there is a mismatch to show you the event.
These will print the render_event string to STDERR.
my $events = intercept { ok(1, "pass"); ok(0, "fail"); diag("xxx"); };
Any events generated within the block will be intercepted and placed inside the $events array reference.
$events
All events will be subclasses of Test::Builder::Event
my $events = intercept { ok(1, "pass"); ok(0, "fail"); diag("xxx"); }; events_are( $events, name => 'Name of the test', # Name this overall test ok => {id => 'a', bool => 1, name => 'pass'}, # check an 'ok' with ID 'a' ok => { # check an 'ok' with ID 'b' id => 'b', bool => 0, name => 'fail', diag => [ diag => {message => qr/Failed test 'fail'/}, # Check a diag attached to the Ok. ] }, diag => {message => qr/xxx/}, # check a 'diag' no ID 'end' # directive 'end' );
The first argument to events_are() must be an arrayref containing Test::Builder::Event objects. Such an arrayref can be produced by intercept { ... }.
events_are()
intercept { ... }
All additional arguments to events_are() must be key value pairs (except for 'end'). The key must either be a directive, or a event-type optionally followed by a name. Values for directives are specific to the directives. Values for event 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 events 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 event 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 event will be passed into your coderef as the only argument. The coderef should return true for valid, false for invalid.
The process ID the event came from.
Usually $0, but in a subtest it will be the name of the subtest that generated the event.
True if the event 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 event was generated by an Test::Builder::Provider, this will tell you what package provided the tool.
For example, if the event was provided by Test::More::ok() this will contain 'Test::More'.
Test::More::ok()
'Test::More'
If the event was generated by an Test::Builder::Provider, this will tell you what the tool was called.
For example, if the event 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 event of the test, not mangled by todo.
The name of the test.
The todo reason.
The reason the test was skipped.
An arrayref of Test::Stream::Event::Diag objects generated specifically for the ok event.
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.
A subtest isa Test::Stream::Ok, so it inherits any/all fields from an ok object.
An arrayref of all events generated within the subtest.
These provide ways to filter or skip events. They apply as seen, and do not effect checks before they are seen.
Filter events 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 events that do not match for the remainder of the checks. Checks before the directive are used will see unfiltered events.
example:
my $events = intercept { Test::More::ok(1, "foo"); Test::More::ok(1, "bar"); Test::More::ok(1, "baz"); Test::Simple::ok(1, "bat"); }; events_are( $events, ok => { name => "foo" }, ok => { name => "bar" }, # From this point on, only more 'Test::Simple' events will be checked. filter_provider => 'Test::Simple', # So it goes right to the Test::Simple event. ok => { name => "bat" }, );
Filter events 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 $events = intercept { ok(1, "foo"); diag("XXX"); ok(1, "bar"); diag("YYY"); ok(1, "baz"); diag("ZZZ"); }; events_are( $events, 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 # events.
my $events = intercept { ok(1, "foo"); diag("XXX"); ok(1, "bar"); diag("YYY"); ok(1, "baz"); diag("ZZZ"); }; events_are( $events, 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 event type matching the next type to check is found.
my $events = intercept { ok(1, "foo"); diag("XXX"); diag("YYY"); diag("ZZZ"); ok(1, "bar"); }; events_are( $events, 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 events will be skipped. You can turn this on and off any time.
my $events = intercept { ok(1, "foo"); diag("XXX"); diag("YYY"); ok(1, "bar"); diag("ZZZ"); ok(1, "baz"); }; events_are( $events, 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 events. Without this any events after your last check are simply ignored. This will generate a failure if any unchecked events remain.
This is also how you can name the overall test. The default name is 'Got expected events'.
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
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.