NAME

Test::Stream::Manual::Tooling - How to write test tools using the Test::Stream infrastructure.

DESCRIPTION

This manual page explains the process of building a test tool using Test::Stream.

QUICK START

If you wantd to write a module that implemented the ok() function, this is all you need to write:

    package Test::Stream::Plugin::MyOk;
    use strict;
    use warnings;

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

    use Test::Stream::Exporter;
    default_exports qw/ok/;
    no Test::Stream::Exporter;

    sub ok($;$) {
        my ($bool, $name) = @_;    # Get args

        my $ctx = context();       # Obtain a context

        $ctx->ok($bool, $name);    # Issue an OK event

        $ctx->release;             # Release the context

        return $bool;              # Return the true/false
    }

    1;

EXPLANATION

Obtaining a context

This is the MOST critical thing you need to do in any testing tool. You should do this as soon as possible. The Test::Stream::Context object ties everything together. Obtaining a context object locks in the file and line number to which errors should be reported. It also finds the current hub to which all events should be sent. Finally the context object is the primary interface used to generate events. In short the context object is the tool builders 1-stop shop.

Issue an Ok event

The core event types, ok, note, diag, bail, and plan have shortcut functions on the context object. These shortcut functions construct the event, and send it to the hub for processing. Other event types can be generated as well using the $ctx->build_event(...) or $ctx->send_event(...) methods. See the Test::Stream::Context object documentation for additional details.

Release the context

When your tool is finished it is very important that you release the context. Failing to release the context would result in a leak condition. In most cases the context will detect this condition and take measures to correct it, along with issuing a very verbose warning.

Return the true/false

Typically testing tools will return a true or false indicating if the test has passed or failed.

ADVANCED

This covers more advanced topics for tool builders.

EVENTS

Most testing tools generate events. The most common event generated is the Test::Stream::Event::Ok event. In addition it is possible for tools to create their own event types.

CONTEXT

The Test::Stream::Context object ties everything together. Obtaining a context object locks in the file and line number to which errors should be reported. It also finds the current hub to which all events should be sent. Finally the context object is the primary interface used to generate events. In short the context object is the tool builders 1-stop shop.

There is only ever one canonical context instance per active hub. If two tools try to obtain a context in the same stack they will both get the same one, the first one to request it generates it, the second gets the existing instance. In both cases the tool MUST release it when done. Tools should never send contexts to other tools, and they should never accept them as arguments. Tools that get broken up into multiple functions may pass the context to their component subs.

DEBUGINFO

Test::Stream::DebugInfo objects are stored inside the context object, its job is to store filename and line number for errors. It can also be used to issue warnings and throw exceptions. Every event generated needs to have a DebugInfo object, typically cloned from the one in the context object.

HUBS

Test::Stream::Hub objects are responsible for 2 things, the first is tracking state. Hubs have an instance of an Test::Stream::State object. When an event is processed by a hub the state will be updated accordingly.

The second job of a hub is to make sure events get to the right place. Typically this means processing the event through any 'filters', then handing them off to the formatter, then finally running them through 'listeners'.

When IPC is active the hub will use the IPC driver (See Test::Stream::IPC) to send events to the correct process or thread.

HUB STACK

There is a single canonical Test::Stream::Stack instance tracked by the Test::Stream::Sync package. When a context is obtained it will reference whatever hub is on the top of the stack at the time it is created. Typically all events will be sent to the topmost hub.

SYNC

The Test::Stream::Sync package is the place where all shared state is tracked. Part of Test::Streams design is reducing shared state to the bare minimum. This class is kept as small as possible while still achieving the necessary functionality. The sync package tracks IPC drivers, formatter, the hub stack, and some global hooks.

EXPORTER

Test::Stream::Exporter is an export tool built-in to Test::Stream. Test::Stream requires export functionality well beyond what Exporter.pm is able to provide. In addition a plugin that does not need special import functionality can simply use Test::Stream::Exporter to work as a plugin.

CAPABILITIES

Test::Stream::Capabilities can be used to guage the active systems fork and/or thread support levels.

UTILITIES

The Test::Stream::Util package exports many useful functions for test authors.

PLUGINS

Plugins can either use Test::Stream::Export or they can use Test::Stream::Plugin and implement the load_ts_plugin() method.

BUNDLES

Bundles are used to combine several plugins into a single module that can be used to load them all at once. This is the better alternative to the Test::Builder practice of having tools load eachother.

SOURCE

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

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

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://dev.perl.org/licenses/