| Test::Builder makes writing custom testing libraries easy (see the previous lab, "Writing a Testing Library") by handling all of the distracting test bookkeeping and management. They're just code. Good libraries need good tests, though. Fortunately, using Test::Builder makes writing tests for these custom libraries easier too, with a little help from Test::Builder::Tester . How do I do that? Consider a test suite for Test::Between (from "Writing a Testing Library"). Save the following test file as between.t : #!perl use strict; use warnings; use Test::Between; use Test::Builder::Tester tests => 3; my $desc; $desc = 'simple alphabetical comparison'; test_pass( $desc ); is_between( 'b', 'a', 'c', $desc ); test_test( $desc ); $desc = 'simple numeric comparison'; test_pass( $desc ); is_between( 2, 1, 3, $desc ); test_test( $desc ); $desc = 'mixed comparison'; test_out( "not ok 1 - $desc" ); test_fail( +2 ); test_diag( ' two is not between 1 and 3' ); is_between( "two", 1, 3, $desc ); test_test( 'failed comparison with diagnostics' );
Note: The $desc variable appears multiple times so as to avoid copying and pasting the test description multiple times. Avoid repetition in tests as you would in any other code .
Run it with perl : $ perl between.t 1..3 ok 1 - simple alphabetical comparison ok 2 - simple numeric comparison ok 3 - failed comparison with diagnostics
What just happened ? between.t looks almost like any other test that uses Test::Between except for one twist: instead of using Test::More to declare a test plan, it uses Test::Builder::Tester , which provides its own test plan. From there, it has three blocks of tests that correspond to the tests shown in "Writing a Testing Library"--an alphabetical comparison that should pass, a numeric comparison that should also pass, and a mixed comparison that should fail. Test::Builder::Tester works by collecting information about what a test should do, running the test, and comparing its actual output to the expected output. Then it reports the results. This requires you to know if the test should pass or fail and what kind of output it will produce. The first test should pass, so the test file calls test_pass( ) to tell Test::Builder::Tester to expect a success message with the test description. Next, it calls the simple alphabetic comparison from the previous lab. Finally, it calls test_test( ) to compare the actual result to the expected result; this line produces the test output for Test::Harness to interpret. Passing the description here produces nicer output for humans . Testing the numeric comparison test works the same way. The mixed comparison test should fail, so the test file uses test_fail( ) to tell Test::Builder::Tester to expect a failure message. Because failure messages include the line number of the failing test, the sole argument to this function refers to the line number of the test call to test. That call occurs in the second line following in the test file, just after the call to test_diag( ) , so the argument is +2 . Because Test::Between produces diagnostics for failed tests, the code uses test_diag( ) to test that diagnostic output. Next comes the mixed comparison test that test_fail( ) expected, and then a test_test( ) call to compare all of the expected output ”both the failure message and the diagnostics ”to the received output. Test::Builder::Tester expects the is_between( ) test to fail. If it does, the test ”whether Test::Between reports failures correctly ” passes . What about... | Q: | How do you distribute tests for test modules? | | A: | Either set a dependency on Test::Builder::Tester in your Makefile.PL or Build.PL file or bundle it with your code. Place it under your t/ directory (in t/lib/Test/Builder/Tester.pm ) and add the following lines to your test files to set its path appropriately when they run. It requires no modules outside of the standard library. BEGIN { chdir 't' if -d 't'; use lib 'lib'; }
| | Q: | Debugging failed test library output is difficult. Can this be easier? | | A: | Test::Builder::Tester:: Color , which ships with Test::Builder::Tester , colorizes diagnostic output to make differences easier to see. It requires the Term::ANSIColor module, so install that too. To enable color debugging, either add the line: use Test::Builder::Tester::Color;
directly to your test files or load it from the command line when you run your tests: $ perl -MTest::Builder::Tester::Color between.t
By default, matches between the received and expected output appear in green reverse type and differences appear highlighted in red reverse type. | | 