The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Test::Stream::Manual::Components - Categorization and overview of Test::Stream components and modules.

DESCRIPTION

This document categorizes the modues included in the Test-Stream distribution. This document also gives basic information about each component, and what modules they connect with. This document is primarily useful for maintainers and test tool authors.

ESSENTIAL INFRASTRUCTURE

The modules in this section are the most critical. These modules are the heart of Test::Stream.

Test::Stream::Capabilities

The Test::Stream::Capabilities module detects various capabilities of the current system, this includes the ability to fork or use threads.

Test::Stream::Context

The Test::Stream::Context module is easily the most important module in Test::Stream. The context object is the primary interface for tool authors. The context object ties everything together and ensures events get to the correct hub. The context object also makes it possible to report the filename and line numbers of errors.

Test::Stream::DebugInfo

The Test::Stream::DebugInfo is used by the context object to track filename, line numbers, todo status, and other information that is important when reporting a test failure.

Test::Stream::Event

The Test::Stream::Event module is the base class for all events, such as Ok, Diag, etc.

Test::Stream::Exporter

The Test::Stream::Exporter module is used by Test::Stream to accomplish export behavior well beyond what Exporter is capable of.

The Test::Stream::Exporter::Meta module is a key component of Test::Stream::Exporter.

Test::Stream::Formatter::TAP

Test::Stream::Formatter::TAP is the TAP output formatter. This module is used whenever Test::Stream outputs TAP.

Test::Stream::HashBase

Test::Stream::HashBase is the object builder used in most Test::Stream modules. It provides constructors and accessor generators.

Test::Stream::Hub

Test::Stream::Hub is responsible for routing events to output handlers. This module also provides several hooks for testing tools.

Test::Stream::IPC

Test::Stream::IPC is responsible for sending events between processes and threads. Test::Stream::IPC::Files is the default IPC driver.

Test::Stream::Stack

The Test::Stream::Stack module manages a stack of hubs. In Test::Stream there can be several hubs and they all live on a stack like this. Events typically go to whichever hub is on top.

Test::Stream::State

Test::Stream::State tracks a tests state, this includes the number of tests, the number of passes, and the number of failures.

Test::Stream::Sync

The Test::Stream::Sync module is where global shared state is managed.

Test::Stream::Table

Test::Stream::Table is used to generate nicely formatted tables. Test::Stream::Table::LineBreak breaks lines of text so that they fit in a table.

Test::Stream::Util

Test::Stream::Util is a collection of general purpose functions used in almost every component of Test::Stream.

ESSENTIAL EVENT TYPES

Test::Stream::Event::Bail

Test::Stream::Event::Bail is an event that is issued when there is a catastrophic failure and all testing should end.

Test::Stream::Event::Diag

Test::Stream::Event::Diag is used to output a message that should always be displayed.

Test::Stream::Event::Exception

Test::Stream::Event::Exception is used when an exception is cought and needs to be reported.

Test::Stream::Event::Note

Test::Stream::Event::Note is used to output an informational message that does not always need to be seen.

Test::Stream::Event::Ok

Test::Stream::Event::Ok is used to represent a single pass or failure.

Test::Stream::Event::Plan

Test::Stream::Event::Plan is used when a plan is set.

Test::Stream::Event::Subtest

Test::Stream::Event::Subtest is used to run an isolated sub-group of tests.

Test::Stream::Event::Waiting

Test::Stream::Event::Waiting is used by the IPC system to pass along a note that the primary process/thread is finished.

PRIMARY INTERFACE

These are the modules people workng with Test::Stream are most likely to interact with. This includes test authors, as well as tool authors.

Test::Stream

Test::Stream is a loader that bootstraps the infrastructure, then loads the requested bundles and plugins.

Test::Stream::Bundle

Test::Stream::Bundle is the base class for Test::Stream bundles.

Test::Stream::Plugin

Test::Stream::Plugin is the base class for Test::Stream plugins.

BUNDLES

These are collections of plugins and options.

Test::Stream::Bundle::Classic

Test::Stream::Bundle::Classic is a bundle that closely resembles Test::More.

Test::Stream::Bundle::V1

Test::Stream::Bundle::V1 is the bundle used by the Test::Stream author in Test::Stream's test suite..

Test::Stream::Bundle::SpecTester

Test::Stream::Bundle::SpecTester is used a lot on internal self-testing.

Test::Stream::Bundle::Tester

Test::Stream::Bundle::Tester is useful when writing tests for testing tools.

PLUGINS

Test::Stream::Plugin::AuthorTest

Test::Stream::Plugin::AuthorTest is used to write tests that should be run by a modules author, but are not required to run when installing the module from cpan.

Test::Stream::Plugin::BailOnFail

Test::Stream::Plugin::BailOnFail will cause the test suite to bail out on the first failure.

Test::Stream::Plugin::CanFork

Test::Stream::Plugin::CanFork is used to write tests that require fork, the tests are skipped if forking is not available.

Test::Stream::Plugin::CanThread

Test::Stream::Plugin::CanThread is used to write tests that requre ithreads, the tests are skipped if threads are not available.

Test::Stream::Plugin::Capabilities

Test::Stream::Plugin::Capabilities is an interface into Test::Stream::Capabilities.

Test::Stream::Plugin::Capture

Test::Stream::Plugin::Capture can be used to intercept STDERR and STDOUT.

Test::Stream::Plugin::Class

Test::Stream::Plugin::Class is used to specify what class is being tested.

Test::Stream::Plugin::Compare

Test::Stream::Plugin::Compare is used for deep comparison. This is the code responsible for is() and like().

This plugin also has the following infrastructure modules:

Test::Stream::Compare::Array
Test::Stream::Compare::Custom
Test::Stream::Compare::Event
Test::Stream::Compare::EventMeta
Test::Stream::Compare::Hash
Test::Stream::Compare::Meta
Test::Stream::Compare::Object
Test::Stream::Compare::Pattern
Test::Stream::Compare::Ref
Test::Stream::Compare::Regex
Test::Stream::Compare::Scalar
Test::Stream::Compare::Set
Test::Stream::Compare::Value
Test::Stream::Compare::Wildcard
Test::Stream::Compare
Test::Stream::Delta
Test::Stream::Plugin::Context

Test::Stream::Plugin::Context is a plugin interface into the Test::Stream::Context module.

Test::Stream::Plugin::Core

Test::Stream::Plugin::Core provides the most common and simple testing tools. This module is resposnible for functions like ok().

Test::Stream::Plugin::Defer

Test::Stream::Plugin::Defer can be used to make assertions that are stored and run at a later time. Test::Stream::DeferredTests is used under the hood.

Test::Stream::Plugin::DieOnFail

Test::Stream::Plugin::DieOnFail throw an exception on the first test failure.

Test::Stream::Plugin::Exception

Test::Stream::Plugin::Exception has tools for intercepting and verifying exceptions.

Test::Stream::Plugin::ExitSummary

Test::Stream::Plugin::ExitSummary provides useful deubgging information at the end of a test run.

Test::Stream::Plugin::Grab

Test::Stream::Plugin::Grab can be used to intercept Test::Stream events without adding any scope.

Test::Stream::Plugin::IPC

Test::Stream::Plugin::IPC is the interface into Test::Stream's IPC system.

Test::Stream::Plugin::Intercept

Test::Stream::Plugin::Intercept is used to intercept Test::Stream events for testing purposes.

The Test::Stream::Hub::Interceptor and Test::Stream::Hub::Interceptor::Terminator modules are used under the hood to achieve this functionality.

Test::Stream::Plugin::LoadPlugin

Test::Stream::Plugin::LoadPlugin can be used to load plugins at run-time, primarily useful when testing plugins.

Test::Stream::Plugin::Mock

Test::Stream::Plugin::Mock is the mocking library included with Test::Stream. It is based off of Mock::Quick.

Test::Stream::Mock is used under the hood.

Test::Stream::Plugin::SRand

Test::Stream::Plugin::SRand can be used to set the random seed to the current date. This is useful for making a test run consistent over any given day.

Test::Stream::Plugin::SkipWithout

Test::Stream::Plugin::SkipWithout can be used to skip test files that require modules that may not be installed.

Test::Stream::Plugin::Spec

Experimental: This plugin is still considered experimental. It is included in the dist because it is used heavily in the tests for Test::Stream. This is still considered experimental because the API is not completely finalized, but it does work well, is fully tested, and will not be removed.

Test::Stream::Plugin::Spec provides RSPEC like functionality. This is essentially a much more advanced form of subtests.

See also:

Test::Stream::Workflow
Test::Stream::Workflow::Unit
Test::Stream::Workflow::Meta
Test::Stream::Workflow::Runner
Test::Stream::Workflow::Task
Test::Stream::Plugin::Subtest

Test::Stream::Plugin::Subtest is used for Test::More style subtests.

Test::Stream::Hub::Subtest is used under the hood.

Test::Stream::Plugin::TAP

Test::Stream::Plugin::TAP is used to turn on TAP output.

Test::Stream::Plugin::UTF8

Test::Stream::Plugin::UTF8 is used to turn on UTF8 globaly.

Test::Stream::Plugin::Warnings

Test::Stream::Plugin::Warnings provides tools for intercepting and validating warnings.

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/