NAME

Test::Stream::Context - Object to represent a testing context.

DESCRIPTION

In testing it is important to have context. It is not helpful to simply say a test failed, you want to know where it failed. This object is responsible for tracking the context of each test that is run. It makes it possible to get the file and line number where the failure occured .This object is also responsible for generating almost all the events you will encounter.

SYNOPSIS

    use Test::Stream::Context qw/context/;

    sub my_tool {
        my $ctx = context();

        # Generate an 'Ok' event.
        $ctx->ok(1, "Pass!");

        # Generate any type of event
        $ctx->send_event('Type', ...);
    }

    1;

EXPORTS

$ctx = context()

This function is used to obtain a context. If there is already a context object in scope this will return it, otherwise it will return a new one.

It is important that you never store a context object in a variable from a higher scope, a package variable, or an object attribute. The scope of a context matters a lot.

If you want to store a context for later reference use the snapshot() method to get a clone of it that is safe to store anywhere.

Note, context() assumes you are at the lowest level of your tool, and looks at the current caller. If you need it to look further you can call it with a numeric argument which is added to the level. To clarify, calling context() is the same as calling context(0).

METHODS

$ctx->alert($MESSAGE)

This issues a warning at the calling context (filename and line number where errors should be reported).

$ctx->throw($MESSAGE)

This throws an exception at the calling context (filename and line number where errors should be reported).

($package, $file, $line, $subname) = $ctx->call()

Get the caller details for the context. This is where errors should be reported.

$pkg = $ctx->package

Get the context package.

$file = $ctx->file

Get the context filename.

$line = $ctx->line

Get the context line number.

$subname = $ctx->subname

Get the context subroutine name.

$ctx_copy = $ctx->snapshot

Get a copy of the context object that is safe to store for later reference.

$ctx->send($event)

Send an event to the correct Test::Stream::Hub object.

$ctx = $class->peek

Get the current context object, if there is one.

$ctx->done_testing(...)

See the done_testing() method on Test::Stream::Hub for arguments, this is just a shortcut to call done_testing on the correct hub.

$ctx->send_event($Type, %params)

Construct and send an event of type c<$Type>. $Type may be the last segment of the Test::Stream::Event::* events, or a fully qualified namespace for an event. $Type is case sensitive, so to build a Test::Stream::Event::Ok event use the string 'Ok'.

Note: If legacy code has monkeypatched Test::Builder, this method will filter the event through the monkeypatch for compatability reasons.

$e = $ctx->build_Event($Type, %params)

This is the same as send_event except that it does not send the event to the hub, it returns it instead.

Note: Unlike send_event() this method will NOT filter the event through Test::Builder monkeypatching.

EVENT SHORTCUTS

ok($pass, $name, $diag)

Generate an Test::Stream::Event::Ok event.

diag($message)

Generate an Test::Stream::Event::Diag event.

note($message)

Generate an Test::Stream::Event::Note event.

plan($max, $directive, $reason)

Generate an Test::Stream::Event::Plan event.

bail($reason, $quiet)

Generate an Test::Stream::Event::Bail event.

finish($tests_run, $tests_failed)

Generate an Test::Stream::Event::Finish event.

subtest($pass, $name)

Generate an Test::Stream::Event::Subtest event.

DANGEROUS METHODS

$ctx->set

$class->set($ctx)

Set the context object as the current one, replacing any that might already be current.

$class->clear

Unset the current context.

$stash = $ctx->hide_todo

$ctx->restore_todo($stash)

These are used to temporarily hide the TODO value in ALL places where it might be found. The returned $stash must be used to restore it later.

$stash = $ctx->subtest_start($name, %params)

$stash = $ctx->subtest_stop($name)

Used to start and stop subtests in the test hub. The stash can be used to configure and manipulate the subtest information. subtest_start will hide the current TODO settings, and unset the current context. subtest_stop will restore the TODO and reset the context back to what it was.

It is your job to take the results in the stash and produce a Test::Stream::Event::Subtest event from them.

Using this directly is not recommended.

CLASS METHODS

Note: These can effect all test packages, if that is not what you want do not use them!.

$msg = Test::Stream::Context->push_todo($msg)

$msg = Test::Stream::Context->pop_todo()

$msg = Test::Stream::Context->peek_todo()

These manage a global todo stack. Any new context created will check here first for a TODO. Changing this will not effect any existing context instances. This is a reliable way to set a global todo that effects any/all packages.

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

There has been a lot of code migration between modules, here are all the original copyrights together:

Test::Stream

Test::Stream::Tester

Copyright 2015 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

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.

Copyright 2001-2008 by Michael G Schwern <schwern@pobox.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

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

This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some parts are based on other people's work.

Under the same license as Perl itself

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

Test::Builder::Tester

Copyright Mark Fowler <mark@twoshortplanks.com> 2002, 2004.

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