NAME
Test::Builder2 - 2nd Generation test library builder
SYNOPSIS
If you're writing a test library, you should start with TB2::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 TB2::History object and formatting the results with a single TB2::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 TB2::Mouse. All Mouse classes have TB2:: prepended.
You can take advantage of all the features Mouse has to offer, including roles and meta stuff. You are free to use TB2::Mouse in your TB2 derived classes or use Mouse directly.
METHODS
test_state
my $test_state = $builder->test_state;
$builder->test_state($test_state);Get/set the TB2::TestState associated with this $builder.
By default it creates a new TestState detached from other builders.
The default contains the TestState default.
history
my $history = $builder->history;A convenience method to access the TB2::History object associated with the test_state.
formatter
my $formatter = $builder->formatter;A convenience method to access the first Formatter associated with the test_state.
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 TB2::AssertStack.
test_start
$tb->test_start;Inform the builder that testing is about to begin.
This should be called before any set of asserts is run, but ok will do it for you if you haven't.
It should eventually be followed by a call to test_end.
test_end
$tb->test_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 TB2::Result object representing the test.
done_testing
$tb->done_testing;
$tb->done_testing($num_tests);Declares that testing is done, issuing a set_plan and test_end event.
If $num_tests is given, that is the number of asserts_expected in the plan. Otherwise a no_plan plan is used.
subtest
$tb->subtest($name => \&code);Declares that &code should run as a subtest. Subtest events run in isolation from regular tests.
See TB2::TestState for more details about subtests.
$name is the name given to this subtest.
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
TB2::Design for a high level overview of how Test::Builder2 is put together.
TB2::Result for the object representing the result of an assert.
TB2::History for the object storing result history.
TB2::Formatter for the object handling printing results.
TB2::TestState for the object holding the state of the test.
TB2::Module for writing your own test libraries.