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!

SYNOPSIS

use Test::More;
use Test::Tester2;

eventa_are(
    # Capture all the events within the block
    intercept {
        ok(1, "pass");
        ok(0, "fail");
        diag("xxx");
    },

    # Describe what we expect to see
    check {
        event ok => {bool => 1, name => 'pass'};
        event ok => {
            bool => 0,
            name => 'fail',
            diag => check {
                event diag => {message => qr/^Failed test /};
            },
        };
        event diag => {message => 'xxx'};
        event bail => {reason  => 'oops'};
        directive end => 'Validate our Grab results';
    }
);

done_testing;

GRAB WITH NO ADDED STACK

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.
ok(1, "pass");
ok(0, "fail");
diag("xxx");

my $success = eval { # Wrap in an eval since we also test BAIL_OUT
    # 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;
};
my $error = $@; # Save the error for later

# Stop capturing events, and validate the ones recieved.
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

TIMTOWTDI

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;

EXPORTS

$events = intercept { ... }

Capture the Test::Builder::Event objects generated by tests inside the block.

events_are($events, ...)

Validate the given events.

events_are(
    $events, # From intercept { ... }
    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',
);

$checks = check { ... };

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

event TYPE => { ... };

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.

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.

dir 'DIRECTIVE';

directive 'DIRECTIVE';

dir DIRECTIVE => 'ARG';

directive DIRECTIVE => 'ARG';

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.

$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::Subtest

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   => {                                          # 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 { ... }.

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.

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: An arrayref of Test::Stream::Event::Diag objects generated specifically for the ok event.

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.

Subtest

A subtest isa Test::Stream::Ok, so it inherits any/all fields from an ok object.

events: An arrayref of all events generated within the subtest.

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

SOURCE

The source code repository for Test::More can be found at http://github.com/Test-More/test-more/.

MAINTAINER

Chad Granum <exodist@cpan.org>

AUTHORS

The following people have all contributed to the Test-More dist (sorted using VIM's sort function).

Chad Granum <exodist@cpan.org>
Fergal Daly <fergal@esatclear.ie>>
Mark Fowler <mark@twoshortplanks.com>
Michael G Schwern <schwern@pobox.com>
唐鳳

COPYRIGHT

Test::Stream

Test::Tester2

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

Test::Simple

Test::More

Test::Builder

Originally authored by Michael G Schwern <schwern@pobox.com> with much inspiration from Joshua Pritikin's Test module and lots of help from Barrie Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and the perl-qa gang.

Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern <schwern@pobox.com>, wardrobe by Calvin Klein.

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

Test::use::ok

To the extent possible under law, 唐鳳 has waived all copyright and related or neighboring rights to Test-use-ok.

This work is published from Taiwan.

http://creativecommons.org/publicdomain/zero/1.0

Test::Tester

Under the same license as Perl itself

See http://www.perl.com/perl/misc/Artistic.html

Test::Builder::Tester

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

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

SYNOPSIS

GRAB WITH NO ADDED STACK

TIMTOWTDI

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

Subtest

VALIDATION DIRECTIVES

filter_provider

filter_type

skip

seek

name

end

SEE ALSO

SOURCE

MAINTAINER

AUTHORS

COPYRIGHT

Module Install Instructions