Test::Builder2 - 2nd Generation test library builder
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.
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.
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.
my $event_coordinator = $builder->event_coordinator; $builder->event_coordinator($event_coordinator);
Get/set the Test::Builder2::EventCoordinator associated with this $builder.
$builder
By default it creates a new EventCoordinator detached from other builders.
The singleton contains the EventCoordinator singleton.
my $history = $builder->history;
A convenience method to access the first History object associated with the event_coordinator.
event_coordinator
Note that there can be more than one.
my $formatter = $builder->formatter;
A convenience method to access the first Formatter associated with the event_coordinator.
my $top_stack = $tb->top_stack;
Stores the current stack of asserts being run as a Test::Builder2::AssertStack.
$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_start
stream_end
$tb->stream_end;
Inform the Builder that a set of asserts is complete.
$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 );
$tb->assert_start;
Called just before a user written test function begins, an assertion.
Most users should call ok instead.
ok
By default it records the caller at this point in $self->top_stack for the purposes of reporting test file and line numbers properly.
$self->top_stack
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.
$tb->assert_end($result);
Like assert_start but for just after a user written assert function finishes.
assert_start
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.
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.
assert_end
$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.
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.
Test::Builder2 was written with a generous grant from The Perl Foundation using donations by viewers like you.
Michael G Schwern <schwern@pobox.com>.
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
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.
To install Test::Simple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Simple
CPAN shell
perl -MCPAN -e shell install Test::Simple
For more information on module installation, please visit the detailed CPAN module installation guide.