—

              
package Test::Stream::Manual::Components;
use strict;
use warnings;
1;
__END__
HideShow 425 lines of Pod
=pod
=encoding UTF-8
=head1 NAME
Test::Stream::Manual::Components - Categorization and overview of Test::Stream
components and modules.
=head1 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.
=head1 ESSENTIAL INFRASTRUCTURE
The modules in this section are the most critical. These modules are the heart
of Test::Stream.
=over 4
=item Test::Stream::Capabilities
The L<Test::Stream::Capabilities> module detects various capabilities of the
current system, this includes the ability to fork or use threads.
=item Test::Stream::Context
The L<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.
=item Test::Stream::DebugInfo
The L<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.
=item Test::Stream::Event
The L<Test::Stream::Event> module is the base class for all events, such as
C<Ok>, C<Diag>, etc.
=item Test::Stream::Exporter
The L<Test::Stream::Exporter> module is used by Test::Stream to accomplish
export behavior well beyond what L<Exporter> is capable of.
The L<Test::Stream::Exporter::Meta> module is a key component of
L<Test::Stream::Exporter>.
=item Test::Stream::Formatter::TAP
L<Test::Stream::Formatter::TAP> is the TAP output formatter. This module is
used whenever Test::Stream outputs TAP.
=item Test::Stream::HashBase
L<Test::Stream::HashBase> is the object builder used in most L<Test::Stream>
modules. It provides constructors and accessor generators.
=item Test::Stream::Hub
L<Test::Stream::Hub> is responsible for routing events to output handlers. This
module also provides several hooks for testing tools.
=item Test::Stream::IPC
L<Test::Stream::IPC> is responsible for sending events between processes and
threads. L<Test::Stream::IPC::Files> is the default IPC driver.
=item Test::Stream::Stack
The L<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.
=item Test::Stream::State
L<Test::Stream::State> tracks a tests state, this includes the number of tests,
the number of passes, and the number of failures.
=item Test::Stream::Sync
The L<Test::Stream::Sync> module is where global shared state is managed.
=item Test::Stream::Table
L<Test::Stream::Table> is used to generate nicely formatted tables.
L<Test::Stream::Table::LineBreak> breaks lines of text so that they fit in a
table.
=item Test::Stream::Util
L<Test::Stream::Util> is a collection of general purpose functions used in
almost every component of Test::Stream.
=back
=head2 ESSENTIAL EVENT TYPES
=over 4
=item Test::Stream::Event::Bail
L<Test::Stream::Event::Bail> is an event that is issued when there is a
catastrophic failure and all testing should end.
=item Test::Stream::Event::Diag
L<Test::Stream::Event::Diag> is used to output a message that should always be
displayed.
=item Test::Stream::Event::Exception
L<Test::Stream::Event::Exception> is used when an exception is cought and needs
to be reported.
=item Test::Stream::Event::Note
L<Test::Stream::Event::Note> is used to output an informational message that
does not always need to be seen.
=item Test::Stream::Event::Ok
L<Test::Stream::Event::Ok> is used to represent a single pass or failure.
=item Test::Stream::Event::Plan
L<Test::Stream::Event::Plan> is used when a plan is set.
=item Test::Stream::Event::Subtest
L<Test::Stream::Event::Subtest> is used to run an isolated sub-group of tests.
=item Test::Stream::Event::Waiting
L<Test::Stream::Event::Waiting> is used by the IPC system to pass along a note
that the primary process/thread is finished.
=back
=head1 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.
=over 4
=item Test::Stream
L<Test::Stream> is a loader that bootstraps the infrastructure, then loads the
requested bundles and plugins.
=item Test::Stream::Bundle
L<Test::Stream::Bundle> is the base class for Test::Stream bundles.
=item Test::Stream::Plugin
L<Test::Stream::Plugin> is the base class for Test::Stream plugins.
=back
=head1 BUNDLES
These are collections of plugins and options.
=over 4
=item Test::Stream::Bundle::Classic
L<Test::Stream::Bundle::Classic> is a bundle that closely resembles
L<Test::More>.
=item Test::Stream::Bundle::V1
L<Test::Stream::Bundle::V1> is the bundle used by the Test::Stream author in
Test::Stream's test suite..
=item Test::Stream::Bundle::SpecTester
L<Test::Stream::Bundle::SpecTester> is used a lot on internal self-testing.
=item Test::Stream::Bundle::Tester
L<Test::Stream::Bundle::Tester> is useful when writing tests for testing tools.
=back
=head1 PLUGINS
=over 4
=item Test::Stream::Plugin::AuthorTest
L<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.
=item Test::Stream::Plugin::BailOnFail
L<Test::Stream::Plugin::BailOnFail> will cause the test suite to bail out on
the first failure.
=item Test::Stream::Plugin::CanFork
L<Test::Stream::Plugin::CanFork> is used to write tests that require fork, the
tests are skipped if forking is not available.
=item Test::Stream::Plugin::CanThread
L<Test::Stream::Plugin::CanThread> is used to write tests that requre ithreads,
the tests are skipped if threads are not available.
=item Test::Stream::Plugin::Capabilities
L<Test::Stream::Plugin::Capabilities> is an interface into
L<Test::Stream::Capabilities>.
=item Test::Stream::Plugin::Capture
L<Test::Stream::Plugin::Capture> can be used to intercept STDERR and STDOUT.
=item Test::Stream::Plugin::Class
L<Test::Stream::Plugin::Class> is used to specify what class is being tested.
=item Test::Stream::Plugin::Compare
L<Test::Stream::Plugin::Compare> is used for deep comparison. This is the code
responsible for C<is()> and C<like()>.
This plugin also has the following infrastructure modules:
=over 4
=item L<Test::Stream::Compare::Array>
=item L<Test::Stream::Compare::Custom>
=item L<Test::Stream::Compare::Event>
=item L<Test::Stream::Compare::EventMeta>
=item L<Test::Stream::Compare::Hash>
=item L<Test::Stream::Compare::Meta>
=item L<Test::Stream::Compare::Object>
=item L<Test::Stream::Compare::Pattern>
=item L<Test::Stream::Compare::Ref>
=item L<Test::Stream::Compare::Regex>
=item L<Test::Stream::Compare::Scalar>
=item L<Test::Stream::Compare::Set>
=item L<Test::Stream::Compare::Value>
=item L<Test::Stream::Compare::Wildcard>
=item L<Test::Stream::Compare>
=item L<Test::Stream::Delta>
=back
=item Test::Stream::Plugin::Context
L<Test::Stream::Plugin::Context> is a plugin interface into the
L<Test::Stream::Context> module.
=item Test::Stream::Plugin::Core
L<Test::Stream::Plugin::Core> provides the most common and simple testing
tools. This module is resposnible for functions like C<ok()>.
=item Test::Stream::Plugin::Defer
L<Test::Stream::Plugin::Defer> can be used to make assertions that are stored
and run at a later time. L<Test::Stream::DeferredTests> is used under the hood.
=item Test::Stream::Plugin::DieOnFail
L<Test::Stream::Plugin::DieOnFail> throw an exception on the first test
failure.
=item Test::Stream::Plugin::Exception
L<Test::Stream::Plugin::Exception> has tools for intercepting and verifying
exceptions.
=item Test::Stream::Plugin::ExitSummary
L<Test::Stream::Plugin::ExitSummary> provides useful deubgging information at
the end of a test run.
=item Test::Stream::Plugin::Grab
L<Test::Stream::Plugin::Grab> can be used to intercept Test::Stream events
without adding any scope.
=item Test::Stream::Plugin::IPC
L<Test::Stream::Plugin::IPC> is the interface into Test::Stream's IPC system.
=item Test::Stream::Plugin::Intercept
L<Test::Stream::Plugin::Intercept> is used to intercept Test::Stream events for
testing purposes.
The L<Test::Stream::Hub::Interceptor> and
L<Test::Stream::Hub::Interceptor::Terminator> modules are used under the hood
to achieve this functionality.
=item Test::Stream::Plugin::LoadPlugin
L<Test::Stream::Plugin::LoadPlugin> can be used to load plugins at run-time,
primarily useful when testing plugins.
=item Test::Stream::Plugin::Mock
L<Test::Stream::Plugin::Mock> is the mocking library included with
L<Test::Stream>. It is based off of L<Mock::Quick>.
L<Test::Stream::Mock> is used under the hood.
=item Test::Stream::Plugin::SRand
L<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.
=item Test::Stream::Plugin::SkipWithout
L<Test::Stream::Plugin::SkipWithout> can be used to skip test files that
require modules that may not be installed.
=item Test::Stream::Plugin::Spec
B<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.
L<Test::Stream::Plugin::Spec> provides RSPEC like functionality. This is
essentially a much more advanced form of subtests.
See also:
=over 4
=item L<Test::Stream::Workflow>
=item L<Test::Stream::Workflow::Unit>
=item L<Test::Stream::Workflow::Meta>
=item L<Test::Stream::Workflow::Runner>
=item L<Test::Stream::Workflow::Task>
=back
=item Test::Stream::Plugin::Subtest
L<Test::Stream::Plugin::Subtest> is used for L<Test::More> style subtests.
L<Test::Stream::Hub::Subtest> is used under the hood.
=item Test::Stream::Plugin::TAP
L<Test::Stream::Plugin::TAP> is used to turn on TAP output.
=item Test::Stream::Plugin::UTF8
L<Test::Stream::Plugin::UTF8> is used to turn on UTF8 globaly.
=item Test::Stream::Plugin::Warnings
L<Test::Stream::Plugin::Warnings> provides tools for intercepting and
validating warnings.
=back
=head1 SOURCE
The source code repository for Test::Stream can be found at
F<http://github.com/Test-More/Test-Stream/>.
=head1 MAINTAINERS
=over 4
=item Chad Granum E<lt>exodist@cpan.orgE<gt>
=back
=head1 AUTHORS
=over 4
=item Chad Granum E<lt>exodist@cpan.orgE<gt>
=back
=head1 COPYRIGHT
Copyright 2015 Chad Granum E<lt>exodist7@gmail.comE<gt>.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
See F<http://dev.perl.org/licenses/>
=cut