NAME

Test::Group::Foreach - repeat tests for several values

SYNOPSIS

  use Test::More;
  use Test::Group;
  use Test::Group::Foreach;

  next_test_foreach my $foo, 'f', 1, 2, 3;
  next_test_foreach my $bar, 'b', 1, 2, 3;

  test mytest => sub {
      # These tests will be repeated for each of the 9 possible
      # combinations of $foo in (1,2,3) and $bar in (1,2,3). 
      ok "$foo$bar" =~ /^\d+$/, "numeric";
      ok $foo+$bar < 6, "sum less than 6";
  };

  # This will result in a failure message like:
  #   Failed test 'sum less than 6 (f=3,b=3)'
  #   ...


  # Values can be given labels to be used in the test name in
  # place of the value, useful if you're working with values
  # that are not short printable strings...

  next_test_foreach my $foo, 'foo', [
      null  => "\0",
      empty => '',
      hash  => {foo => 1},
      array => ['bar'],
      long  => 'foo' x 1000,
  ];
  test mytest => sub {
      ok ref($foo) || length($foo) < 1000, "ref or short";
  };

  # This will result in a failure message like:
  #   Failed test 'ref or short (foo=long)'
  #   ...

FUNCTIONS

The following function is exported by default.

next_test_foreach ( VARIABLE, NAME, VALUE [,VALUE...] )

Arranges for the next test group to be repeated for one or more values of a variable. A note will be appended to the name of each test run within the group, specifying the value used.

The VARIABLE parameter must be a scalar, it will be set to each of the specified values in turn.

The NAME parameter should be a short name that identifies this variable. It will be used in the note added to the test name. If NAME is undef then no note will be added to the test name for this variable. If NAME is the empty string then the note will consist of just the value rather than a name=value pair.

The remaining parameters are treated as values to assign to the variable. There must be at least one. It's possible to specify labels to use in the test name for some or all of the values, by passing array references containing label/value pairs. The following examples are all equivalent:

  next_test_foreach( my $p, 'p', [
      foo  => 'foo',
      bar  => 'bar',
      null => "\0",
      long => 'foo' x 1000,
  ]);

  next_test_foreach( my $p, 'p',
      [ foo  => 'foo' ],
      [ bar  => 'bar' ],
      [ null => "\0" ],
      [ long => 'foo' x 1000 ],
  );

  next_test_foreach( my $p, 'p',
      'foo',
      'bar',
      [ null => "\0" ],
      [ long => 'foo' x 1000 ],
  );

  next_test_foreach( my $p, 'p',
      'foo',
      'bar',
      [ null => "\0", long => 'foo' x 1000 ],
  );

The following function is not exported by default.

tgf_label ( VARIABLE )

Returns the label associated with the current value of VARIABLE. Can only be called from within a test group, and VARIABLE must be a scalar that is being varied by next_test_foreach().

This is useful if you want your test to do something slightly differently for some values, for example:

  use Test::Group::Foreach qw(next_test_foreach tgf_label);

  next_test_foreach my $x, 'x', [
    foo => [{asd => 0, r => 19}, 'foo'],
    bar => [{a => b}, ['bar'], [], {}],
    baz => [{x => y}, {p => q}],
  ];

  test mytest => sub {
      if (tgf_label $x eq 'bar') {
          # special handling for the 'bar' case ...
          ...
      }
      ...
  };

AUTHOR

Nick Cleaton, <nick at cleaton dot net>

COPYRIGHT & LICENSE

Copyright 2009 Nick Cleaton, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.