NAME

build_test - build/verify the test data for GraphViz::Data::Structure

SYNOPSIS

Run dotty and verify that the test is visually correct:

build_test testname

Build the tests without running dotty:

build_test --no-dotty testname

DESCRIPTION

GraphViz::Data::Structure is a bit more difficult to test than some Perl modules. Since "bad" (i.e., visually-unappealing or incorrect) output can only be checked visually, we have a bit of a problem turning this into text-based tests.

build_tests gets around this problem by creating a "pre-test" suite for GraphViz::Data::Structure. Each pre-test runs a set of data structures through GraphViz::Data::Structure; the output is run through dotty to allow the developer to do the visual check. At the same time, a .t file is created in the module's /t directory; this .t file can check the output of GraphViz::Data::Structure to make sure that the output is consistent.

DEVELOPMENT USAGE

It is recommended that anyone developing, modifying, or maintaining GraphViz::Data::Structure run build_test as needed after each change to verify that the modifications that were made do indeed draw the correct picture. Often it will be found that running just a single test build will be sufficient to check the enw code, but you should always run all of them before signing off on a change.

If new functionality is added to GraphViz::Data::Structure, new tests should be added to the data.in files in this directory to ensure that the new features get both a visual check and a test in the test suite.

WARNINGS

Running all the tests together from one driver program can lead to problems with cross-contamination of the old with the new; this is paticularly a problem with globs. This is why the tests are run one by one.

data.in FILES

The data.in files have the following format:

(name => 'undef',
 code => 'GraphViz::Data::Structure->new(undef)->graph->as_canon',
)
%%
(name => 'atom',
 code => 'GraphViz::Data::Structure->new(1)->graph->as_canon',
)
%%
...

Each one is a valid hash initializer, with the name and code keys required. The name is the name to be associated with the test, and code is the actual code to be executed to create and visualize the data structure.

You should name your data.in files in a manner consistent with the other tests: ddname.data.in, where "dd" is a two-digit number, and "name" is an arbitrary name to be associated with the test(s) in this file.

USE

When you add or change function in GraphViz::Data::Structure, do the following:

1. Create a new data.in file containing the tests you want to run.

2. In this directory, run perl build_test testname.

3. Verify that the output of the test is visually pleasing and accurate.

4. cd .. and run make test to verify that the new test is OK and passes.

NOTES

Obviously, it would be nice if there was an easy way to get the Makefile.PL to handle the running of build_tests appropriately, but there doesn't seem to be an easy way to do that.

Always remember: you have to do a make before re-running build_tests when you've changed the module! Otherwise you build tests based on the old code instead of the new changes.