NAME

       Test::TableDriven - write tests, not scripts that run them

SYNOPSIS

          use A::Module qw/or two!/;
          use Test::TableDriven (
            foo => { input   => 'expected output',
                     another => 'test',
                   },

            bar => [[some => 'more tests'],
                    [that => 'run in order'],
                    [refs => [qw/also work/]],
                    [[qw/this is also possible/] => { and => 'it works' }],
                   ],
          );

          runtests;

          sub foo {
             my $in  = shift;
             my $out = ...;
             return $out;
          }

          sub bar { same as foo }

DESCRIPTION

       Writing table-driven tests is usually a good idea.  Adding a test case doesn't require
       adding code, so it's easy to avoid fucking up the other tests.  However, actually going
       from a table of tests to a test that runs is non-trivial.

       "Test::TableDriven" makes writing the test drivers trivial.  You simply define your test
       cases and write a function that turns the input data into output data to compare against.
       "Test::TableDriven" will compute how many tests need to be run, and then run the tests.

       Concentrate on your data and what you're testing, not "plan tests =" scalar keys
       %test_cases> and a big foreach loop.

WHAT DO I DO

       Start by using the modules that you need for your tests:

          use strict;
          use warnings;
          use String::Length; # the module you're testing

       Then write some code to test the module:

          sub strlen {
              my $in  = shift;
              my $out = String::Length->strlen($in);
              return $out;
          }

       This "strlen" function will accept a test case (as $in) and turns it into something to
       compare against your test cases:

       Oh yeah, you need some test cases:

          use Test::TableDriven (
              strlen => { foo => 3,
                          bar => 3,
                          ...,
                        },
          );

       And you'll want those test to run somehow:

          runtests;

       Now execute the test file.  The output will look like:

          1..2
          ok 1 - strlen: bar => 3
          ok 2 - strlen: foo => 3

       Add another test case:

              strlen => { foo  => 3,
                          bar  => 3,
                          quux => 4,
                          ...,
                        },

       And your test still works:

          1..3
          ok 1 - strlen: bar => 3
          ok 2 - strlen: quux => 4
          ok 3 - strlen: foo => 3

       Yay.

DETAILS

       I'm not in a prose-generation mood right now, so here's a list of things to keep in mind:

       •   Don't forget to "runtests".  Just loading the module doesn't do a whole lot.

       •   If a subtest is not a subroutine name in the current package, runtests will die.

       •   If a subtest definition is a hashref, the tests won't be run in order.  If it's an
           arrayref of arrayrefs, then the tests are run in order.

       •   If a test case "expects" a reference, "is_deeply" is used to compare the expected
           result and what your test returned.  If it's just a string, "is" is used.

       •   Feel free to use "Test::More::diag" and friends, if you like.

       •   Don't print to STDOUT.

       •   Especially don't print TAP to STDOUT :)

EXPORT

   runtests
       Run the tests.  Only call this once.

BUGS

       Report them to RT, or patch them against the git repository at:

          git clone git://git.jrock.us/Test-TableDriven

       (or <http://git.jrock.us/>).

AUTHOR

       Jonathan Rockway "<jrockway AT cpan.org>".

COPYRIGHT

       This module is copyright (c) 2007 Jonathan Rockway.  You may use, modify, and redistribute
       it under the same terms as Perl itself.