NAME
Test::Builder2 - 2nd Generation test library builder
SYNOPSIS
If you're writing a test library, you should start with Test::Builder2::Module.
If you're writing a test, you should start with Test::Simple.
DESCRIPTION
Test::Builder2 is an object for writing testing libraries. It records assert results and formats them for output. It also provides a central location for test libraries to place behaviors when certain test events happen, like an assert failing or a new test starting. Finally, it records the point where the user called an assert allowing test libraries to freely call asserts inside asserts but still report failure at a file and line number useful to the user.
The end goal of all this is to allow test authors to write their own asserts without having to worry about coordination with other test libraries or formatting.
There is usually a single Test::Builder2 object per test process coordinating everything. Results are stored in a single Test::Builder2::History object and formatting the results with a single Test::Builder2::Formatter.
Test::Builder2 is very generic and doesn't do a lot of the work you've probably come to expect a test framework to do. This reduction of assumptions increases flexibility and ensures that TB2 can remain the core of Perl testing for another decade to come. Extra beahviors are either farmed out to other objects which can be swapped out for others with more behavior or placed into roles that can be applied to the TB2 object as desired.
Mouse
Test::Builder2 is a Mouse object (like Moose, but smaller) to take advantage of the advances in OO over the last 10 years. To avoid dependencies and bugs caused by changes in Mouse, Test::Builder2 ships and uses its own copy of Mouse called Test::Builder2::Mouse. All Mouse classes have Test::Builder2:: prepended.
You can take advantage of all the features Mouse has to offer, including roles and meta stuff. You are free to use Test::Builder2::Mouse in your TB2 derived classes or use Mouse directly.
METHODS
event_coordinator
my $event_coordinator = $builder->event_coordinator;
$builder->event_coordinator($event_coordinator);Get/set the Test::Builder2::EventCoordinator associated with this $builder.
By default it creates a new EventCoordinator detached from other builders.
The singleton contains the EventCoordinator singleton.
history
my $history = $builder->history;A convenience method to access the first History object associated with the event_coordinator.
Note that there can be more than one.
formatter
my $formatter = $builder->formatter;A convenience method to access the first Formatter associated with the event_coordinator.
Note that there can be more than one.
top_stack
my $top_stack = $tb->top_stack;Stores the current stack of asserts being run as a Test::Builder2::AssertStack.
stream_start
$tb->stream_start;Inform the builder that testing is about to begin.
This should be called before any set of asserts is run.
It should eventually be followed by a call to stream_end.
You can indicate nested sets of asserts by calling stream_start before stream_end.
stream_end
$tb->stream_end;Inform the Builder that a set of asserts is complete.
set_plan
$tb->set_plan(%plan);Inform the builder what your test plan is, if any.
For example, Perl tests would say:
$tb->set_plan( tests => $number_of_tests );assert_start
$tb->assert_start;Called just before a user written test function begins, an assertion.
Most users should call ok instead.
By default it records the caller at this point in $self->top_stack for the purposes of reporting test file and line numbers properly.
This will be called when *any* assertion begins. If you want to know when the assertion is called from the user's point of view, check $self->top_stack. It will be empty before and have a single assert after.
assert_end
$tb->assert_end($result);Like assert_start but for just after a user written assert function finishes.
Most users should call ok instead.
By default it pops $self->top_stack and if this is the last assert in the stack it formats the result.
This will be called when *any* assertion ends. If you want to know when the assertion is complete from the user's point of view, check $self->top_stack. It will have a single element before and be empty after.
ok
my $result = $tb->ok( $test );
my $result = $tb->ok( $test, $name );The most basic assertion that all other assertions should use.
This handles things like calling assert_start, assert_end, creating a test result and recording the result. It will start a stream if one is not already started. Everything you want an assert to do and nothing else.
$test is simple true for success, false for failure.
$name is a description of the test.
Returns a Test::Builder2::Result object representing the test.
CONTRIBUTE
The repository for Test::Builder2 can be found at http://github.com/schwern/test-more/tree/Test-Builder2.
Issues can be discussed at http://github.com/schwern/test-more/issues or <bugs-Test-Simple@rt.cpan.org>. We are always open to discussion, critiques and feedback. Doesn't matter if you're not sure if its a "bug". If it bugs you, let us know.
THANKS
Test::Builder2 was written with a generous grant from The Perl Foundation using donations by viewers like you.
AUTHOR
Michael G Schwern <schwern@pobox.com>.
COPYRIGHT
Copyright 2008-2010 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://dev.perl.org/licenses/artistic.html
SEE ALSO
Test::Builder2::Design for a high level overview of how Test::Builder2 is put together.
Test::Builder2::Result for the object representing the result of an assert.
Test::Builder2::History for the object storing result history.
Test::Builder2::Formatter for the object handling printing results.
Test::Builder2::EventCoordinator for the object coordinating between builders.
Test::Builder2::Module for writing your own test libraries.