GENERAL PRINCIPLES

Especially it avoids writing ugly, boring code like:

  my $ok = 1;
  foreach my $x ($arg1a, $arg2a) {
      foreach my $y ($arg2a, $arg2b, $arg3b, $arg4b) {
          $ok &&= foo($x,$y);
      }
  }
  ok $ok, $testname;

Instead you simpler write

  all_ok {foo(@_)}  
         [ [$arg1a, $arg2a], [$arg2b, $arg2b, $arg3b, $arg4b] ]
         $testname;

Additionally the output contains also some useful information about the parameters that should be tested and the first parameters the test failed. E.g.

  all_ok {$_[0] != 13 and $_[1] != 13} 
         [ [1 .. 100], [1 .. 100] ], 
         "No double bad luck";

would print:

  not ok 1 - No double bad luck
  #     Failed test (x.pl at line 5)
  # Tests with the parameters: $VAR1=[[10,11,12,13,14,15],[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15]];
  # Failed first using these parameters: $VAR1=[10,13];

The parameters passed to "all_ok" can be passed in two ways. If you need to test a crossproduct of more than one parameterlist, you have to write it as

  all_ok CODE [ \@arglist1, \@arglist2, ..., \@arglistn ], TEST_NAME;

The CODE-routine will be called with every combination of the arglists, passed as simple arguments. E.g.

  all_ok {foo(@_)} [ ["red", "green", "blue"], ["big", "medium", "little"] ];

would call

  foo("red","big");
  foo("red","medium");
  foo("red","little");
  foo("green","big");
  foo("green","medium");
  foo("green","little");
  foo("blue","big");
  foo("blue","medium");
  foo("blue","little");

Note, that the order of calling shouldn't play any role, as it could be changed in future versions without any notice about.

Please always remember, that a crossproduct of the lists can be very, very big. So don't write something like "all_ok {&foo} [ [1 .. 32000], [1 .. 32000], [1 .. 32000] ]", as it would test 32_768_000_000_000 parameter combinations.

If you only want to test one parameter with different values, you can write in general

  all_ok CODE \@values, TEST_NAME

So "all_ok {&foo} [1,2,3]" would call "foo(1); foo(2); foo(3)". (In this way and only in this, $_ will be set to the passed argument. Thus it is "$_ = $_[0]" in this special case. Reason for this behaviour is just convenience.)

Please take care, that the first element of the values list isn't an array ref, as Test::ManyParams would assume that you want to test combinations of the above. If it is important to pass values that are array refs, you have to write it this way:

  my @values = ( [1 .. 10],
                 [100 .. 110],
                 [990 .. 1000] );
  all_ok {&foo} [ [@values] ];
  
  # calls foo(1), ... foo(10), foo(100), ..., foo(110), foo(990), ..., foo(1000)

what is very different to

  all_ok {&foo} [ @values ];
  
  # what would call foo(1,100,900), foo(1,100,901), ...

Of course, the test name is always optional, but recommended.

FUNCTIONS

all_ok CODE PARAMETERS, [ TEST_NAME ]

See the general comments.

all_are CODE VALUE, PARAMETERS, [ TEST_NAME ]

The equivalent to "Test::More"'s "is" method. The given subroutine has to return always the given value. They are compared with 'eq'.

all_arent CODE VALUE, PARAMETERS, [ TEST_NAME ]

The equivalent to "Test::More"'s "isnt" method. The given subroutine has to return always values different from the given one. They are compared with 'eq'.

any_ok CODE PARAMETERS, [ TEST_NAME ]

Returns whether the subroutine returns true for one of the given parameters.

any_is CODE VALUE, PARAMETERS, [ TEST_NAME ]

Returns whether there is at least one parameter (combination) for that the given subroutine results the specified value.

any_isnt CODE VALUE, PARAMETERS, [ TEST_NAME ]

Returns whether there is at least one parameter (combination) for that the given subroutine results to a value different to the specified one.

most_ok CODE PARAMETERS => NR_OF_TESTS [, TEST_NAME]

Tests NR_OF_TESTS (randomly choosen) parameter (combinations) of the given parameters. All the (randomly choosen) parameters have to let the subroutine results to true.

This method is intended to used, when a full test would need to long and you want to avoid systematic mistakes.

There could be some parameter (combinations), that are tested twice or more often.

IMPORTING

But when you want to set the seed for the randomization of the "most_ok" method, the way for importing looks like "use Test::ManyParams seed =" 42>.

At the time, it only will call "srand(42)", but later on, it will hold foreach test script and file it's own random numbers, so that several modules all using this Test::ManyParams module won't collide.

If you don't seet a seed value, at default the "time ^ $$" value will be taken as seed (the default value could be changed in future versions without any notice). That's not a very good seed, but I hope it will be good and quick enough for the most cases.

You can access the setted seed with the variable $Test::ManyParams::seed. That's a non-exported, readonly variable.

Please take care only to import Test::ManyParams one times in one package, as the use command is executed while compile time and so different seedings will be confusing.

EXPORT