NAME

Test::Tester - Ease testing test modules built with Test::Builder

SYNOPSIS

use Test::Tester tests => 5;

use Test::MyStyle;

check_test(
  sub {
    is_mystyle_eq("this", "that", "not eq");
  },
  {
    ok => 0, # expect this to fail
    name => "not eq",
    diag => "Expected: 'this'\nGot: 'that'",
  }
);

or

use Test::Tester;

use Test::More tests => 2;
use Test::MyStyle;

my @results = run_tests(
  sub {
    is_database_alive("dbname");
  },
  {
    ok => 1, # expect the test to pass
  }
);

# now use Test::More::like to check the diagnostic output

like($result[1]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");

DESCRIPTION

If you have written a test module based on Test::Builder then Test::Tester allows you to test it with the minimum of effort.

HOW TO USE (THE EASY WAY)

From version 0.08 Test::Tester no longer requires you to included anything special in your test modules. All you need to do is

use Test::Tester;

in your test script before any other Test::Builder based modules and away you go.

Other modules based on Test::Builder can be used to help with the testing. In fact you can even use functions from your test module to test other functions from the same module - although that may not be a very wise thing to do!

The easiest way to test is to do something like

check_test(
  sub { is_mystyle_eq("this", "that", "not eq") },
  {
    ok => 0, # we expect the test to fail
    name => "not eq",
    diag => "Expected: 'this'\nGot: 'that'",
  }
);

this will execute the is_mystyle_eq test, capturing it's results and checking that they are what was expected.

You may need to examine the test results in a more flexible way, for example, if the diagnostic output may be quite complex or it may involve something that you cannot predict in advance like a timestamp. In this case you can get direct access to the test results:

my @results = run_tests(
  sub {
    is_database_alive("dbname");
  },
  {
    ok => 1, # expect the test to pass
  }
);

like($result[1]->{diag}, "/^Database ping took \\d+ seconds$"/, "diag");

We cannot predict how long the database ping will take so we use Test::More's like() test to check that the diagnostic string is of the right form.

HOW TO USE (THE HARD WAY)

This is here for backwards compatibility only

Make your module use the Test::Tester::Capture object instead of the Test::Builder one. How to do this depends on your module but assuming that your module holds the Test::Builder object in $Test and that all your test routines access it through $Test then providing a function something like this

sub set_builder
{
  $Test = shift;
}

should allow your test scripts to do

Test::YourModule::set_builder(Test::Tester->capture);

and after that any tests inside your module will captured.