NAME

WRAPPERS

  use Test::Group;

  sub maybe_test ($&) {
      my ($name, $code) = @_;

      my $only = $ENV{ONLY_TEST};
      if ($only and $only !~ /(^|,)\Q$name\E(,|$)/) {
          skip_next_test("$name not enabled");
      }
      goto &test;
  }

In a test script, you can now use maybe_test() anywhere you would use test():

  maybe_test foo => sub {
      ok ...
  };

Note the use of "goto &test" to pass control to Test::Group::test(), see "goto" in perlfunc. This is good practice when wrapping Test::Group::test(), because it avoids creating a new subroutine call frame and messing up the line numbers in failed test diagnostics.

Sometimes you can't use "goto &test", because you want to add some code after the test() call. In this situation you can adjust the line numbers in failed test diagnostics by incrementing $Test::Builder::Level, see Test::Builder.

The following example outputs a timestamp diagnostic before and after running the test group:

  use Test::Builder;
  use Test::Group;
  use Test::More;
  use Time::HiRes;

  sub timed_test ($&) {
      my ($name, $code) = @_;

      diag("$name start: ".Time::HiRes::time());

      local $Test::Builder::Level = $Test::Builder::Level + 1;
      &test($name, $code);

      diag("$name done:  ".Time::HiRes::time());
  };

Note the use of the ampersand in the call to Test::Group::test(). This bypasses Test::Group::test()'s function prototype, which would otherwise reject $code as the second parameter because it is not a literal code block.

PLUGINS

The next_test_plugin() function takes a single parameter, which must be a subroutine reference. That subroutine will be called with a single parameter: another subroutine reference which will run the test group.

For example, a plugin to check that a test group does not modify the PATH environment variable could be implemented like this:

  use Test::Group qw(:DEFAULT next_test_plugin);
  use Test::More;

  sub next_test_nopathchange {
      next_test_plugin {
          my $next = shift;

          my $old = $ENV{PATH};
          $next->();
          is $ENV{PATH}, $old, "path not modified";
      };
  }

To use this plugin from a test script:

  next_test_nopathchange();

  test foo => sub {
      do_my_tests('foo');
  };

Another example - the following plugin runs the test group twice, with and without a DEBUG environment variable set:

  use Test::Group qw(:DEFAULT next_test_plugin);

  sub next_test_with_and_without_debug {
      next_test_plugin {
          my $next = shift;

          $next->();
          local $ENV{DEBUG} = 1;
          $next->();
      };
  }

In a test script, you might apply both plugins to the same test group:

  next_test_with_and_without_debug();
  next_test_nopathchange();

  test foo => sub {
      do_my_tests('foo');
  };

When multiple plugins have been set, the one that was set first gets control first. In the example above, the DEBUG plugin will be called first, and each time it calls "$next->()" control passes to the PATH plugin. When the PATH plugin calls "$next->()", control gets down to do_my_tests().

If you want to apply the same set of plugins to several groups in your test script, then you can write a Test::Group::test() wrapper to set them up:

  sub mytest ($&) {
      next_test_with_and_without_debug();
      next_test_nopathchange();

      goto &test;
  }

  mytest foo => sub {
      do_my_tests('foo');
  };

  mytest bar => sub {
      do_my_tests('bar');
  };

SEE ALSO

Test::Group::Tester helps you to write tests for Test::Group extensions.