.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Test::Inline 3pm"
.TH Test::Inline 3pm "2013-08-16" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Inline \- Embed your tests in your code, next to what is being tested
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Embedding tests allows tests to be placed near the code being tested.
.PP
This is a nice supplement to the traditional .t files.
.SS "How does it work?"
.IX Subsection "How does it work?"
\&\f(CW\*(C`Test::Inline\*(C'\fR 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 \s-1POD\s0 segment, like the
following.
.PP
.Vb 1
\&  =begin testing
\&  
\&  # This code assumes we have a cpuinfo file
\&  ok( \-f /proc/cpuinfo, \*(AqHost has a standard /proc/cpuinfo file\*(Aq );
\&  
\&  =end testing
\&  
\&  =begin testing label
\&  
\&  # Test generation of the <label> HTML tag
\&  is( My::HTML\->label(\*(Aqfoo\*(Aq),        \*(Aq<label>foo</label>\*(Aq,           \*(Aq\->label(simple) works\*(Aq );
\&  is( My::HTML\->label(\*(Aqbar\*(Aq, \*(Aqfoo\*(Aq), \*(Aq<label for="bar">foo</label>\*(Aq, \*(Aq\->label(for) works\*(Aq    );
\&  
\&  =end testing
.Ve
.PP
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
independent of each other. Each chunk of testing code should not die
or crash if it is run before or after another chunk.
.PP
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.
.PP
These test scripts can then be executed as normal.
.SS "What is Test::Inline good for?"
.IX Subsection "What is Test::Inline good for?"
\&\f(CW\*(C`Test::Inline\*(C'\fR is incredibly useful for doing ad-hoc unit testing.
.PP
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.
.PP
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.
.PP
If your assumption is ever wrong, it gets picked up at install-time and
based on the test failures, you can correct your assumption.
.PP
It's also extremely useful for systematically testing self-contained code.
.PP
That is, any code which can be independent tested without the need for
external systems such as databases, and that has no side-effects on external
systems.
.PP
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
\&\s-1API\s0, or anything you like, in fine detail.
.PP
Test::Inline also introduces the concept of unit-tested documentation.
.PP
Not only can your code be tested, but if you have a \s-1FAQ\s0 or some other
pure documentation module, you can validate that the documentation is
correct for the version of the module installed.
.PP
If the module ever changes to break the documentation, you can catch it
and correct the documentation.
.SS "What is Test::Inline bad for?"
.IX Subsection "What is Test::Inline bad for?"
\&\f(CW\*(C`Test::Inline\*(C'\fR is \fBnot\fR a complete testing solution, and there are several
types of testing you probably \s-1DON\s0'T want to use it for.
.IP "\(bu" 4
Static testing across the entire codebase
.IP "\(bu" 4
Functional testing
.IP "\(bu" 4
Tests with side-effects such as those that might change a testing database
.SS "Getting Started"
.IX Subsection "Getting Started"
Because Test::Inline creates test scripts with file names that \fBdon't\fR
start with a number (for ordering purposes), the first step is to create
your normal test scripts using file names in the \s-1CPAN\s0 style of
\&\fI01_compile.t\fR, \fI02_main.t\fR, \fI03_foobar.t\fR, and so on.
.PP
You can then add your testing fragments wherever you like throughout
your code, and use the \fIinline2test\fR 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.
.PP
Tests for Class::Name will end up in the file \f(CW\*(C`class_name.t\*(C'\fR.
.PP
These test files sit quite happily alongside your number test scripts.
.PP
When you run the test suite as you normally would, the inline scripts
will be run after the numbered tests.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 6
\&  my $Tests = Test::Inline\->new(
\&      verbose  => 1,
\&      readonly => 1,
\&      output   => \*(Aqauto\*(Aq,
\&      manifest => \*(Aqauto/manifest\*(Aq,
\&  );
.Ve
.PP
The \f(CW\*(C`new\*(C'\fR constructor creates a new test generation framework. Once the
constructor has been used to create the generator, the \f(CW\*(C`add_class\*(C'\fR method
can be used to specify classes, or class heirachies, to generate tests for.
.PP
\&\fBverbose\fR \- The \f(CW\*(C`verbose\*(C'\fR option causes the generator to write state and
debugging information to \s-1STDOUT\s0 as it runs.
.PP
\&\fBmanifest\fR \- The \f(CW\*(C`manifest\*(C'\fR 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 preferred order they
should be processed to best satisfy the class-level dependency of the
tests.
.PP
\&\fBcheck_count\fR \- The \f(CW\*(C`check_count\*(C'\fR value controls how strictly the
test script will watch the number of tests that have been executed.
.PP
When set to false, the script does no count checking other than the
standard total count for scripts (where all section counts are known)
.PP
When set to \f(CW1\fR (the default), \f(CW\*(C`Test::Inline\*(C'\fR does smart count checking,
doing section-by-section checking for known-count sections \fBonly\fR when
the total for the entire script is not known.
.PP
When set to \f(CW2\fR or higher, \f(CW\*(C`Test::Inline\*(C'\fR does full count checking,
doing section-by-section checking for every section with a known number
of tests.
.PP
\&\fBfile_content\fR \- The \f(CW\*(C`file_content\*(C'\fR option should be provided as a \s-1CODE\s0
reference, which will be passed as arguments the \f(CW\*(C`Test::Inline\*(C'\fR 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 \f(CW\*(C`OutputHandler\*(C'\fR.
.PP
\&\fBoutput\fR \- The \f(CW\*(C`output\*(C'\fR 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 \f(CW\*(C`OutputHandler\*(C'\fR, the value of \f(CW\*(C`output\*(C'\fR should
refer to the location \fBwithin the OutputHandler\fR that the files will be
written to.
.PP
\&\fBreadonly\fR \- The \f(CW\*(C`readonly\*(C'\fR 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).
.PP
This option is currently disabled by default, by may be enabled by default
in a future release, so if you do \s-1NOT\s0 want your tests being created as
read-only, you should explicitly set this option to false.
.PP
\&\fBInputHandler\fR \- The \f(CW\*(C`InputHandler\*(C'\fR option, if provided, supplies an
alternative \f(CW\*(C`FileHandler\*(C'\fR from which source modules are retrieved.
.PP
\&\fBOuputHandler\fR \- The \f(CW\*(C`OutputHandler\*(C'\fR option, if provided, supplies an
alternative \f(CW\*(C`FileHandler\*(C'\fR to which the resulting test scripts are written.
.PP
Returns a new \f(CW\*(C`Test::Inline\*(C'\fR object on success.
.PP
Returns \f(CW\*(C`undef\*(C'\fR if there is a problem with one of the options.
.SS "exception"
.IX Subsection "exception"
The \f(CW\*(C`exception\*(C'\fR method returns a flag which indicates whether error will
be returned via exceptions.
.SS "InputHandler"
.IX Subsection "InputHandler"
The \f(CW\*(C`InputHandler\*(C'\fR method returns the file handler object that will be
used to find and load the source code.
.SS "ExtractHandler"
.IX Subsection "ExtractHandler"
The \f(CW\*(C`ExtractHandler\*(C'\fR accessor returns the object that will be used
to extract the test sections from the source code.
.SS "ContentHandler"
.IX Subsection "ContentHandler"
The \f(CW\*(C`ContentHandler\*(C'\fR accessor return the script content generation handler.
.SS "OutputHandler"
.IX Subsection "OutputHandler"
The \f(CW\*(C`OutputHandler\*(C'\fR accessor returns the file handler object that the
generated test scripts will be written to.
.ie n .SS "add $file, $directory, \e$source, $Handle"
.el .SS "add \f(CW$file\fP, \f(CW$directory\fP, \e$source, \f(CW$Handle\fP"
.IX Subsection "add $file, $directory, $source, $Handle"
The \f(CW\*(C`add\*(C'\fR method is a parameter-sensitive method for adding something
to the build schedule.
.PP
It takes as argument a file path, a directory path, a reference to a \s-1SCALAR\s0
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.
.PP
Returns the number of test scripts added, which could be zero, or \f(CW\*(C`undef\*(C'\fR
on error.
.SS "add_class"
.IX Subsection "add_class"
.Vb 2
\&  $Tests\->add_class( \*(AqFoo::Bar\*(Aq );
\&  $Tests\->add_class( \*(AqFoo::Bar\*(Aq, recursive => 1 );
.Ve
.PP
The \f(CW\*(C`add_class\*(C'\fR method adds a class to the list of those to have their tests
generated. Optionally, the \f(CW\*(C`recursive\*(C'\fR option can be provided to add not just
the class you provide, but all classes below it as well.
.PP
Returns the number of classes found with inline tests, and added, including 
\&\f(CW0\fR if no classes with tests are found. Returns \f(CW\*(C`undef\*(C'\fR if an error occurs 
while adding the class or it's children.
.SS "add_all"
.IX Subsection "add_all"
The \f(CW\*(C`add_all\*(C'\fR method will search the \f(CW\*(C`InputHandler\*(C'\fR for all *.pm files,
and add them to the generation set.
.PP
Returns the total number of test scripts added, which may be zero, or
\&\f(CW\*(C`undef\*(C'\fR on error.
.SS "classes"
.IX Subsection "classes"
The \f(CW\*(C`classes\*(C'\fR method returns a list of the names of all the classes that
have been added to the \f(CW\*(C`Test::Inline\*(C'\fR object, or the null list \f(CW\*(C`()\*(C'\fR if
nothing has been added.
.SS "class"
.IX Subsection "class"
For a given class name, fetches the Test::Inline::Script object for that
class, if it has been added to the \f(CW\*(C`Test::Inline\*(C'\fR object. Returns \f(CW\*(C`undef\*(C'\fR
if the class has not been added to the \f(CW\*(C`Test::Inline\*(C'\fR object.
.SS "filenames"
.IX Subsection "filenames"
For all of the classes added, the \f(CW\*(C`filenames\*(C'\fR method generates a map of the
filenames that the test files for the various classes should be written to.
.PP
Returns a reference to a hash with the classes as keys, and filenames as
values.
.PP
Returns \f(CW0\fR if there are no files to write.
.PP
Returns \f(CW\*(C`undef\*(C'\fR on  error.
.SS "schedule"
.IX Subsection "schedule"
While the \f(CW\*(C`filenames\*(C'\fR method generates a map of the files for the
various classes, the \f(CW\*(C`schedule\*(C'\fR returns the list of file names in the
order in which they should actually be executed.
.PP
Returns a reference to an array containing the file names as strings.
.PP
Returns \f(CW0\fR if there are no files to write.
.PP
Returns \f(CW\*(C`undef\*(C'\fR on error.
.SS "manifest"
.IX Subsection "manifest"
The \f(CW\*(C`manifest\*(C'\fR generates the contents of the manifest file, if it is both
wanted and needed.
.PP
Returns the contents of the manifest file as a normal string, false if it
is either not wanted or needed, or \f(CW\*(C`undef\*(C'\fR on error.
.SS "save"
.IX Subsection "save"
.Vb 1
\&  $Tests\->save;
.Ve
.PP
The \f(CW\*(C`save\*(C'\fR method generates the test files for all classes, and saves them
to the \f(CW\*(C`output\*(C'\fR directory.
.PP
Returns the number of test files generated. Returns \f(CW\*(C`undef\*(C'\fR on error.
.SH "BUGS"
.IX Header "BUGS"
The \*(L"Extended =begin\*(R" syntax used for non-trivial sections is not formalised
as part of the \s-1POD\s0 spec yet, although it is on the track to being included.
.PP
While simple '=begin testing' sections are fine and will pass \s-1POD\s0 testing,
extended begin sections may cause \s-1POD\s0 errors.
.SH "TO DO"
.IX Header "TO DO"
\&\- Add support for \f(CW\*(C`example\*(C'\fR sections
.PP
\&\- Add support for \f(CW\*(C`=for\*(C'\fR sections
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs should always be submitted via the \s-1CPAN\s0 bug tracker
.PP
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test\-Inline <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Inline>
.PP
Professional support, assistance, or customisations for large scale
uses of \f(CW\*(C`Test::Inline\*(C'\fR are available from http://phase\-n.com/ <http://phase-n.com/>.
.PP
For other issues, contact the maintainer.
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thank you to Phase N (http://phase\-n.com/ <http://phase-n.com/>) for permitting
the open sourcing and release of this distribution.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004 \- 2013 Adam Kennedy.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.