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.

SYNOPSYS

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

    sub my_tool {
        my $ctx = context();

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

    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.

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

$ctx = $class->peek

Get the current context object, if there is one.

DANGEROUS ONES

$ctx->set

$cclass->set($ctx)

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

$class->clear

Unset the current context.

$ctx->register_event($package)

$ctx->register_event($package, $name)

Register a new event type, creating the shortcut method to generate it. If $name is not provided it will be taken from the end of the package name, and will be lowercased.

$hr = $ctx->events

Get the hashref that holds (name => $package) pairs. This is the actual ref used by the package, so please do not alter it.

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

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