---
name: "Test::TableDriven"
section: "3pm"
platform: "linux"
package: "libtest-tabledriven-perl"
version: "0.02-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test::TableDriven"
---

# Test::TableDriven(3pm)

write tests, not scripts that run them

## 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.