NAME

Test::Tester2 - Tools for validating the events produced by your testing tools.

DESCRIPTION

Unit tests are tools to validate your code. This library provides tools to validate your tools!

TEST COMPONENT MAP

[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.

SYNOPSIS

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");
};

# By Hand
is($events->[0]->{bool}, 1, "First event passed");

# With help
events_are(
    $events,
    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:
events_are(
    intercept { ... },
    ok => { bool => 1 },
    ...
);

done_testing;

EXPORTS

$events = intercept { ... }: Capture the Test::Builder::Event objects generated by tests inside the block.
events_are($events, ...): Validate the given events.
$dump = render_event($event): 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.
display_event($event)
display_events($events): These will print the render_event string to STDERR.

INTERCEPTING EVENTS

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.

EVENT TYPES

All events will be subclasses of Test::Builder::Event

Test::Builder::Event::Ok
Test::Builder::Event::Note
Test::Builder::Event::Diag
Test::Builder::Event::Plan
Test::Builder::Event::Finish
Test::Builder::Event::Bail
Test::Builder::Event::Child

VALIDATING EVENTS

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   => { 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 events_are() must be an arrayref containing Test::Builder::Event objects. Such an arrayref can be produced by 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.

TYPES AND IDS

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.

VALIDATING FIELDS

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.

field => 'exact_value',: The specified field must exactly match the given value, be it number or string.
field => qr/.../,: The specified field must match the regular expression.
field => sub { my $val = shift; return $val ? 1 : 0 },: 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.

FIELDS PRESENT FOR ALL EVENT TYPES

pid

The process ID the event came from.

depth

Usually 0, but will be 1 for subtests, 2 for nested subtests, etc.

source

Usually $0, but in a subtest it will be the name of the subtest that generated the event.

in_todo

True if the event was generated inside a todo.

line

Line number to which failures will be reported.

(This is actually usually undefined for plan and finish)

file

File to which failures will be reported

(This is actually usually undefined for plan and finish)

package

package to which errors will be reported

(This is actually usually undefined for plan and finish)

tool_package

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'.

tool_name

Note: Only present if applicable.

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'.

tap

Note: Only present if applicable.

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.

EVENT SPECIFIC FIELDS

ok

bool: True if the test passed (or failed but is in todo).
real_bool: The actual event of the test, not mangled by todo.
name: The name of the test.
todo: The todo reason.
skip: The reason the test was skipped.

diag and note

message: Message for the diag/note.

plan

max: Will be a number if a numeric plan was issued.
directive: Usually empty, but may be 'skip_all' or 'no_plan'
reason: Reason for the directive.

finish

tests_run: Number of tests that ran.
tests_failed: Number of tests that failed.

bail

reason: Reason the test bailed.

child

name: Name of the child
is_subtest: True if the child was created to start subtests
action: Always either 'push' or 'pop'. 'push' when a child is created, 'pop' when a child is destroyed.

VALIDATION DIRECTIVES

These provide ways to filter or skip events. They apply as seen, and do not effect checks before they are seen.

filter_provider

filter_provider => ...

filter_providers => [...]

'!filter_provider' => ...

'!filter_providers' => [...]

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_type

filter_type => ...

filter_types => [...]

'!filter_type' => ...

'!filter_types' => [...]

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.

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 {
    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' },
);

skip

skip => #

skip => '*'

The numeric form will skip the next # events.

example:

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.

example:

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" },
);

seek

seek => $BOOL

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" },
);

name

name => "Name of test": Used to name the test when not using 'end'.

end

'end'

end => 'Test Name'

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'.

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

TEST COMPONENT MAP

SYNOPSIS

EXPORTS

INTERCEPTING EVENTS

EVENT TYPES

VALIDATING EVENTS

TYPES AND IDS

VALIDATING FIELDS

FIELDS PRESENT FOR ALL EVENT TYPES

EVENT SPECIFIC FIELDS

ok

diag and note

plan

finish

bail

child

VALIDATION DIRECTIVES

filter_provider

filter_type

skip

seek

name

end

SEE ALSO

AUTHORS

COPYRIGHT

Module Install Instructions