Test::Inline - Inlining your tests next to the code being tested

Embedding tests allows tests to be placed near the code it's testing.

This is a nice supplement to the traditional .t files.

It's like XUnit, only better and Perl-style.

CWTest::Inline lets you write small fragments of general or method-specific testing code, and insert it anywhere you want in your modules, inside a specific tagged POD segment, like the following.

  # A fragment of general test code

  =begin testing

  ok( -f /proc/cpuinfo, 'Host has a standard /proc/cpuinfo file' );

  =end testing

  # Completely test a single method

  =begin testing label

  # Test generation of the <label> HTML tag
  is( My::HTML->label('foo'),        '<label>foo</label>',           '->label(simple) works' );
  is( My::HTML->label('bar', 'foo'), '<label for="bar">foo</label>', '->label(for) works'    );

  =end testing

You can add as many, or as few, of these chunks of tests as you wish. The key condition when writing them is that they should be conceptually independant of each other. Each chunk of testing code should not die or crash if it is run before or after another chunk.

Using inline2test or another test compiler, you can then transform these chunks in a test script, or an entire tree of modules into a complete set of standard Test::More-based test scripts.

These test scripts can then be executed as normal.

CWTest::Inline is incredibly useful for doing ad-hoc unit testing.

In any large groups of modules, you can add testing code here, there and everywhere, anywhere you want. The next time the test compiler is run, a new test script will just appear.

It's also extremely for systematically testing self-contained code.

That is, any code which can be independantly tested without the need for external systems such as databases, and that has no side-effects on external systems.

All of this code, written by multiple people, can then have one single set of test files generated. You can check all the bits and pieces of a large API, or anything you like, in fine detail.

CWTest::Inline is not a complete testing solution, and there are several types of testing you probably DON'T want to use it for.

•

Static testing across the entire codebase

•

Functional testing

•

Tests with side-effects such as those that might change a testing database

Because Test::Inline creates test scripts that _don't_ start with a numeric order, is to create your normal tests using file names in the CPAN style of CW01_compile.t, CW02_main.t, CW03_foobar.t.

You can then add your testing fragments wherever you like throughout your code, and then use the CWinline2test script to generate the test scripts for the inline tests. By default the test will be named after the packages that the test fragments are in.

Tests for Class::Name will end up in the file CWclass_name.t.

These test files sit quite happily alongside your number test scripts.

When you run the test suite as you normally would, the inline scripts will be run after the numbered tests.

  my $Tests = Test::Inline->new(
          verbose  => 1,
          output   => 'auto',
          manifest => 'auto.manifest',
          );

The CWnew constructor creates a new test generation framework. Once the constructor has been used to create the generator, the CWadd_class method can be used to specify classes, or class heirachies, to generate tests for.

verbose - The CWverbose option causes the generator to write state and debugging information to STDOUT as it runs.

manifest - The CWmanifest option, if provided, will cause a manifest file to be created and written to disk. The manifest file contains a list of all the test files generated, but listed in the prefered order they should be processed to best satisfy the class-level dependency of the tests.

check_count - The CWcheck_count value controls how strictly the test script will watch the number of tests that have been executed.

When set to false, the script does no count checking other than the standard total count for scripts (where all section counts are known)

When set to CW1 (the default), CWTest::Inline does smart count checking, doing section-by-section checking for known-count sections only when the total for the entire script is not known.

When set to CW2 or higher, CWTest::Inline does full count checking, doing section-by-section checking for every section with a known number of tests.

file_content - The CWfile_content option should be provided as a CODE reference, which will be passed as arguments the CWTest::Inline object, and a single Test::Inline::Script object, and should return a string containing the contents of the resulting test file. This will be written to the CWOutputHandler.

output - The CWoutput option provides the location of the directory where the tests will be written to. It should both already exist, and be writable. If using a custom CWOutputHandler, the value of CWoutput should refer to the location within the OutputHandler the files will be written to.

InputHandler - The CWInputHandler option, if provided, supplies an alternative CWFileHandler from which source modules are retrieved.

OuputHandler - The CWOutputHandler option, if provided, supplies an alternative CWFileHandler to which the resulting test scripts are written.

Returns a new CWTest::Inline object on success.

Returns CWundef if there is a problem with one of the options.

The CWInputHandler method returns the file handler object that will be used to find and load the source code.

The CWExtractHandler accessor returns the object that will be used to extract the test sections from the source code.

The CWContentHandler accessor return the script content generation handler.

The CWOutputHandler accessor returns the file handler object that the generated test scripts will be written to. The CWadd method is a parameter-sensitive method for adding something to the build schedule.

It takes as argument a file path, a directory path, a reference to a SCALAR containing perl code, or an IO::Handle (or subclass) object. It will retrieve code from the parameter as appropriate, parse it, and create zero or more Test::Inline::Script objects representing the test scripts that will be generated for that source code.

Returns the number of test scripts added, which could be zero, or CWundef on error.

  $Tests->add_class( 'Foo::Bar' );
  $Tests->add_class( 'Foo::Bar', recursive => 1 );

The CWadd_class method adds a class to the list of those to have their tests generated. Optionally, the CWrecursive option can be provided to add not just the class you provide, but all classes below it as well.

Returns the number of classes found with inline tests, and added, including CW0 if no classes with tests are found. Returns CWundef if an error occurs while adding the class or it's children.

The CWadd_all method will search the CWInputHandler for all *.pm files, and add them to the generation set.

Returns the total number of test scripts added, which may be zero, or CWundef on error.

The CWclasses method returns a list of the names of all the classes that have been added to the CWTest::Inline object, or the null list CW() if nothing has been added.

For a given class name, fetches the Test::Inline::Script object for that class, if it has been added to the CWTest::Inline object. Returns CWundef if the class has not been added to the CWTest::Inline object.

For all of the classes added, the CWfilenames method generates a map of the filenames that the test files for the various classes should be written to.

Returns a reference to a hash with the classes as keys, and filenames as values.

Returns CW0 if there are no files to write.

Returns CWundef on error.

While the CWfilenames method generates a map of the files for the various classes, the CWschedule returns the list of file names in the order in which they should actually be executed.

Returns a reference to an array containing the file names as strings.

Returns CW0 if there are no files to write.

Returns CWundef on error.

The CWmanifest generates the contents of the manifest file, if it is both wanted and needed.

Returns the contents of the manifest file as a normal string, false if it is either not wanted or needed, or CWundef on error.

  $Tests->save;

The CWsave method generates the test files for all classes, and saves them to the CWoutput directory.

Returns the number of test files generated. Returns CWundef on error.

The Extended =begin syntax used for non-trivial sections is not really considered part of the spec yet. While simple '=begin testing' sections are find and will pass POD testing, extended begin sections may cause POD errors.

- Add support for CWexample sections

- Add support for CW=for sections

Bugs should always be submitted via the CPAN bug tracker

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Inline>

Professional support, assistance, or customisations for large scale uses of CWTest::Inline are available from <http://phase-n.com/>.

For other issues, contact the maintainer.

Adam Kennedy <cpan@ali.as>, <http://ali.as/>

Thank you to Phase N (<http://phase-n.com/>) for permitting the open sourcing and release of this distribution.

Copyright (c) 2004 - 2005 Phase N Austalia. All rights reserved.

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

The full text of the license can be found in the LICENSE file included with this module.