NAME

Test::SerialFork - Run iterations of a test in different processes

SYNOPSIS

  use Test::More plan => 42;
  use Test::SerialFork;

  my $abc=serial_fork('abc','def','ghi');

  ok(do_my_test($abc),'It works');

DESCRIPTION

This module allows you to run multiple copies of the same test, specifying a different label for each copy. The label is made available to the test run, and will generally be used to modify its behaviour in some way. Each copy of the test will also be run in a seperate sub-process, to isolate each test run from system-wide changes made by previous runs.

The module exports a single function, serial_fork(), whose arguments are the labels which will be passed to the subsequent runs of the test. serial_fork() iterates over these labels, forking into two processes each time.

In the child process, serial_fork() essentially just returns the current label, and the remainder of the test program is run as normal. However, the parent process collects all of the child's output, and integrates it into the main status report generated by the test (test names have the current label prepended to make it clear which run produced each message).

serial_fork() generates a few test cases of its own:

serial_fork() parameters good

This test of serial_fork()'s parameters ensures that each one is defined and contains at least one non-whitespace character. This is to make sure that when these labels are useful when prepended to the test. If this test fails, the remainder of the test is aborted.

$label: Create pipe

$label: Fork

These tests are performed at the beginning of each test run, to check that the mechanics of setting up the subprocess are working. If either of them fails, the test run and any subsequent test runs are aborted.

$label: Clean exit

This test is performed after each test run, to check that the subprocess exited with a successful status.

INTEGRATION WITH TEST::*

This module only works properly with other modules derived from Test::Builder. However, the way it currently works loses some of the distinction between the three output channels that Test::Builder provides. If you stick to the ok(), is() and diag() variants, you should be OK.

BUGS AND CAVEATS

Due to their use as test name labels, the values passed to serial_fork() should really only be plain strings (though have a look at Class::Random to see what resulted when Damian Conway said something similar). A future version of this module will probably allow some way of specifying label/data pairs, but in the meantime, you can easily work around it like this:

  my %label_data=(
    abc => { complex data ... },
    def => { more complex data ... },
  );
  my $label=serial_fork(keys %label_data);
  my $data=$label_data{$label};

SEE ALSO

Test::MultiFork forks several copies of a test and runs them all concurrently, through the magic of source filters. It also provides a way for the subprocesses to communicate with each other. In my view, the diagnostics aren't as clear as Test::SerialFork's, but YMMV.

AUTHOR

Copyright 2005 by Peter Haworth <pmh@cpan.org>