Sync

Test::Stream::Sync

The sync package is where global state is tracked.
One of the goals of Test::Stream was to isolate and limit global state.
Test::Builder used a singleton to solve the same problem.

What it tracks:

Root PID and thread ID
Post-test hooks
Post-load hooks
Default formatter
Hub stack
IPC object

Hub Stack

Test::Stream::Stack (Hub Stack)

The hub stack is where a test tool finds the current hub.
The stack can contain any number of hubs.
The top hub is always current.
The stack has methods to help push, pop, and properly initialize hubs.
The stack is what makes subtests and self-testing easy.

Hub

Test::Stream::Hub

The hub object handles 4 things in this order:

Event modification hooks.
Track event driven state changes.
Route events to the formatter.
Event listener hooks.

Things the hub has to consider:

IPC, do events go to another thread/process?
Has the PID or thread ID changed?
Performance, most tools generate at least 1 event object.
Are tests currently failing?
Does the event change the state to failing?

State

Test::Stream::State

The test state has the following attributes:

Current test count.
Current failure count.
The test plan.
Have we bailed out?
Has the test ended?
Is the test currently passing?
Skip reason (if applicable)

Formatter

Test::Stream::Formatter::*

Currently there is only one formatter, the TAP formatter.

Formatters are easy to create:

Any module can implement a 'write' method.
Formatter gets all events.
The test number is bumped on 'Ok' events.
A single test number can have multiple events.

IPC

Test::Stream::IPC

The IPC system is responsible for sending events to the correct process or thread in tests that fork or spawn threads.

IPC system makes use of a driver.
The default driver uses a temp dir and writes events to files.
Anyone can write a driver.
Works for ithreads, forking, or both at once.
You can have more than one.
Typically there is a global instance in the Sync package.

Context

Test::Stream::Context

The context object is the Test::Stream linchpin.

The context object ties everything together:

Finds the current hub for you.
Tracks the file+line number for error reporting.
Makes it possible to nest tools sanely (replaces $Level).
Primary interface to generating event objects.
Has several hooks tools can use.

Conception of the context object happened fairly early in development. The idea started as a way to address the shortcommings of $Level. Schwern and I had conversed about how awful $Level was several times with no resolution. One day the concept came to me, much of the Test::Stream architecture is a result of the context object concept.

Event

Test::Stream::Event

Events should be used for any of the following:

Change state (fail/pass/plan)
Produce output
Communicate between processes or threads

The core event types are:

Ok: Represents a pass or fail result.
Plan: Represents the expectations of a test file.
Diag: Critical Diagnostics intended for humans.
Note: Informational Diagnostics intended for humans.
Exception: If a tool trapped an exception it can use this to cause a test failure, even across processes and threads.
Bail: Used to abort all testing.
Subtest: This is a subclass of Ok, used for subtests to track sub-events.
Waiting: Used internally by the IPC system to note that the main process/thread is waiting.