Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Test::Inline(3)	      User Contributed Perl Documentation      Test::Inline(3)

       Test::Inline - Embed your tests in your code, next to what is being

       Embedding tests allows tests to be placed near the code being tested.

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

   How does it work?
       "Test::Inline" lets you write small fragments of	general	or function-
       specific	testing	code, and insert it anywhere you want in your modules,
       inside a	specific tagged	POD segment, like the following.

	 =begin	testing

	 # This	code assumes we	have a cpuinfo file
	 ok( -f	/proc/cpuinfo, 'Host has a standard /proc/cpuinfo file'	);

	 =end testing

	 =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 logically
       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.

   What	is Test::Inline	good for?
       "Test::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.

       This also makes it great	for testing assumptions	you normally wouldn't
       bother to write run-time	code to	test. It ensures that your assumptions
       about the way Perl does some operation, or about	the state of the host,
       are confirmed at	install-time.

       If your assumption is ever wrong, it gets picked	up at install-time and
       based on	the test failures, you can correct your	assumption.

       It's also extremely useful for systematically testing self-contained

       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.

       Test::Inline also introduces the	concept	of unit-tested documentation.

       Not only	can your code be tested, but if	you have a FAQ or some other
       pure documentation module, you can validate that	the documentation is
       correct for the version of the module installed.

       If the module ever changes to break the documentation, you can catch it
       and correct the documentation.

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

       o   Static testing across the entire codebase

       o   Functional testing

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

   Getting Started
       Because Test::Inline creates test scripts with file names that don't
       start with a number (for	ordering purposes), the	first step is to
       create your normal test scripts using file names	in the CPAN style of
       01_compile.t, 02_main.t,	03_foobar.t, and so on.

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

       Tests for Class::Name will end up in the	file "class_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,
	     readonly => 1,
	     output   => 'auto',
	     manifest => 'auto/manifest',

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

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

       manifest	- The "manifest" 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 "check_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 1 (the default), "Test::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 2 or	higher,	"Test::Inline" does full count checking, doing
       section-by-section checking for every section with a known number of

       file_content - The "file_content" option	should be provided as a	CODE
       reference, which	will be	passed as arguments the	"Test::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 "OutputHandler".

       output -	The "output" 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 "OutputHandler", the value of "output"
       should refer to the location within the OutputHandler that the files
       will be written to.

       readonly	- The "readonly" option, if provided, indicates	that any
       generated test files should be created (or set when updated) with read-
       only permissions, to prevent accidentally adding	to or editing the test
       scripts directly	(instead of via	the classes).

       This option is currently	disabled by default, by	may be enabled by
       default in a future release, so if you do NOT want your tests being
       created as read-only, you should	explicitly set this option to false.

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

       OuputHandler - The "OutputHandler" option, if provided, supplies	an
       alternative "FileHandler" to which the resulting	test scripts are

       Returns a new "Test::Inline" object on success.

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

       The "exception" method returns a	flag which indicates whether error
       will be returned	via exceptions.

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

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

       The "ContentHandler" accessor return the	script content generation

       The "OutputHandler" accessor returns the	file handler object that the
       generated test scripts will be written to.

   add $file, $directory, \$source, $Handle
       The "add" 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
       "undef" on error.

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

       The "add_class" method adds a class to the list of those	to have	their
       tests generated.	Optionally, the	"recursive" 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 0 if no classes with tests are	found. Returns "undef" if an
       error occurs while adding the class or it's children.

       The "add_all" method will search	the "InputHandler" for all *.pm	files,
       and add them to the generation set.

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

       The "classes" method returns a list of the names	of all the classes
       that have been added to the "Test::Inline" object, or the null list
       "()" 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 "Test::Inline" object. Returns
       "undef" if the class has	not been added to the "Test::Inline" object.

       For all of the classes added, the "filenames" 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 0 if there are no files to write.

       Returns "undef" on  error.

       While the "filenames" method generates a	map of the files for the
       various classes,	the "schedule" 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 0 if there are no files to write.

       Returns "undef" on error.

       The "manifest" 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 "undef" on	error.


       The "save" method generates the test files for all classes, and saves
       them to the "output" directory.

       Returns the number of test files	generated. Returns "undef" on error.

       The "Extended =begin" syntax used for non-trivial sections is not
       formalised as part of the POD spec yet, although	it is on the track to
       being included.

       While simple '=begin testing' sections are fine and will	pass POD
       testing,	extended begin sections	may cause POD errors.

       - Add support for "example" sections

       - Add support for "=for"	sections

       Bugs should always be submitted via the CPAN bug	tracker


       Professional support, assistance, or customisations for large scale
       uses of "Test::Inline" are available from <>.

       For other issues, contact the maintainer.

       Adam Kennedy <>

       Thank you to Phase N (<>) for	permitting the open
       sourcing	and release of this distribution.

       Copyright 2004 -	2013 Adam Kennedy.

       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.

perl v5.32.0			  2013-04-09		       Test::Inline(3)


Want to link to this manual page? Use this URL:

home | help