.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test::Assertions 3pm"
.TH Test::Assertions 3pm "2022-11-19" "perl v5.36.0" "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::Assertions \- a simple set of building blocks for both unit and runtime testing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&        #ASSERT does nothing
\&        use Test::Assertions;
\&        
\&        #ASSERT warns "Assertion failure"...
\&        use Test::Assertions qw(warn);
\&        
\&        #ASSERT dies with "Assertion failure"...
\&        use Test::Assertions qw(die);
\&        
\&        #ASSERT warns "Assertion failure"... with stack trace
\&        use Test::Assertions qw(cluck);
\&        
\&        #ASSERT dies with "Assertion failure"... with stack trace
\&        use Test::Assertions qw(confess);
\&        
\&        #ASSERT prints ok/not ok
\&        use Test::Assertions qw(test);
\&        
\&        #Will cause an assertion failure
\&        ASSERT(1 == 0);
\&        
\&        #Optional message
\&        ASSERT(0 == 1, "daft");
\&        
\&        #Checks if coderef dies
\&        ASSERT(
\&                DIED( sub {die()} )
\&        );
\&        
\&        #Check if perl compiles OK
\&        ASSERT(
\&                COMPILES(\*(Aqprogram.pl\*(Aq)
\&        );
\&        
\&        #Deep comparisons
\&        ASSERT(
\&                EQUAL(\e@a, \e@b),
\&                "lists of widgets match"        # an optional message
\&        );
\&        ASSERT(
\&                EQUAL(\e%a, \e%b)
\&        );
\&        
\&        #Compare to a canned value
\&        ASSERT(
\&                EQUALS_FILE($foo, \*(Aqbar.dat\*(Aq),
\&                "value matched stored value"
\&        );
\&        
\&        #Compare to a canned value (regex match using file contents as regex)
\&        ASSERT(
\&                MATCHES_FILE($foo, \*(Aqbar.regex\*(Aq)
\&        );
\&        
\&        #Compare file contents
\&        ASSERT(
\&                FILES_EQUAL(\*(Aqfoo.dat\*(Aq, \*(Aqbar.dat\*(Aq)
\&        );
\&        
\&        #returns \*(Aqnot ok for Foo::Bar Tests (1 errors in 3 tests)\*(Aq
\&        ASSESS(
\&                 [\*(Aqok 1\*(Aq, \*(Aqnot ok 2\*(Aq, \*(AqA comment\*(Aq, \*(Aqok 3\*(Aq], \*(AqFoo::Bar Tests\*(Aq, 0
\&        );
\&        
\&        #Collate results from another test script
\&        ASSESS_FILE("test.pl");
\&        
\&        #File routines
\&        $success = WRITE_FILE(\*(Aqbar.dat\*(Aq, \*(Aqhello world\*(Aq);
\&        ASSERT( WRITE_FILE(\*(Aqbar.dat\*(Aq, \*(Aqhello world\*(Aq), \*(Aqfile was written\*(Aq);
\&        $string = READ_FILE(\*(Aqexample.out\*(Aq);
\&        ASSERT( READ_FILE(\*(Aqexample.out\*(Aq), \*(Aqfile has content\*(Aq );
.Ve
.PP
The helper routines don't need to be used inside \s-1\fBASSERT\s0()\fR:
.PP
.Vb 6
\&        if ( EQUALS_FILE($string, $filename) ) {
\&                print "File hasn\*(Aqt changed \- skipping\en";
\&        } else {
\&                my $rc = run_complex_process($string);
\&                print "File changed \- string was reprocessed with result \*(Aq$rc\*(Aq\en";
\&        }
\&        
\&        ($boolean, $output) = COMPILES(\*(Aqfile.pl\*(Aq);
\&        # or...
\&        my $string;
\&        ($boolean, $standard_output) = COMPILES(\*(Aqfile.pl\*(Aq, 1, \e$string);
\&        # $string now contains standard error, separate from $standard_output
.Ve
.PP
In test mode:
.PP
.Vb 5
\&        use Test::Assertions qw(test);
\&        plan tests => 4;
\&        plan tests;                                     #will attempt to deduce the number
\&        only (1,2);                                     #Only report ok/not ok for these tests
\&        ignore 2;                                       #Skip this test
\&
\&        #In test/ok mode...
\&        use Test::Assertions qw(test/ok);
\&        ok(1);                                          #synonym for ASSERT
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Test::Assertions provides a convenient set of tools for constructing tests, such as unit tests or run-time assertion
checks (like C's \s-1ASSERT\s0 macro).
Unlike some of the Test:: modules available on \s-1CPAN,\s0 Test::Assertions is not limited to unit test scripts;
for example it can be used to check output is as expected within a benchmarking script.
When it is used for unit tests, it generates output in the standard form for \s-1CPAN\s0 unit testing (under Test::Harness).
.PP
The package's import method is used to control the behaviour of \s-1ASSERT:\s0 whether it dies,
warns, prints 'ok'/'not ok', or does nothing.
.PP
In 'test' mode the script also exports \fBplan()\fR, \fBonly()\fR and \fBignore()\fR functions.
In 'test/ok' mode an \fBok()\fR function is also exported for compatibility with Test/Test::Harness.
The plan function attempts to count the number of tests if it isn't told a number (this works fine in simple
test scripts but not in loops/subroutines). In either mode, a warning will be emitted if the planned number
of tests is not the same as the number of tests actually run, e.g.
.PP
.Vb 1
\&        # Looks like you planned 2 tests but actually ran 1.
.Ve
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
.ie n .IP "plan $number_of_tests" 4
.el .IP "plan \f(CW$number_of_tests\fR" 4
.IX Item "plan $number_of_tests"
Specify the number of tests to expect. If \f(CW$number_of_tests\fR isn't supplied, \s-1ASSERTION\s0 tries to deduce the number
itself by parsing the calling script and counting the number of calls to \s-1ASSERT.\s0
It also returns the number of tests, should you wish to make use of that figure at some point.
In 'test' and 'test/ok' mode a warning will be emitted if the actual number of tests does not match the number planned,
similar to Test::More.
.IP "only(@test_numbers)" 4
.IX Item "only(@test_numbers)"
Only display the results of these tests
.IP "ignore(@test_numbers)" 4
.IX Item "ignore(@test_numbers)"
Don't display the results of these tests
.ie n .IP "\s-1ASSERT\s0($bool, $comment)" 4
.el .IP "\s-1ASSERT\s0($bool, \f(CW$comment\fR)" 4
.IX Item "ASSERT($bool, $comment)"
The workhorse function.  Behaviour depends on how the module was imported.
\&\f(CW$comment\fR is optional.
.IP "\s-1ASSESS\s0(@result_strings)" 4
.IX Item "ASSESS(@result_strings)"
Collate the results from a set of tests.
In a scalar context returns a result string starting with \*(L"ok\*(R" or \*(L"not ok\*(R"; in a list context returns 1=pass or 0=fail, followed by a description.
.Sp
.Vb 1
\& ($bool, $desc) = ASSESS(@args)
.Ve
.Sp
is equivalent to
.Sp
.Vb 1
\& ($bool, $desc) = INTERPRET(scalar ASSESS(@args))
.Ve
.ie n .IP "\s-1ASSESS_FILE\s0($file, $verbose, $timeout)" 4
.el .IP "\s-1ASSESS_FILE\s0($file, \f(CW$verbose\fR, \f(CW$timeout\fR)" 4
.IX Item "ASSESS_FILE($file, $verbose, $timeout)"
.Vb 2
\& $verbose is an optional boolean
\& default timeout is 60 seconds (0=never timeout)
.Ve
.Sp
In a scalar context returns a result string; in a list context returns 1=pass or 0=fail, followed by a description.
The timeout uses \fBalarm()\fR, but has no effect on platforms which do not implement \fBalarm()\fR.
.ie n .IP "($bool, $desc) = \s-1INTERPRET\s0($result_string)" 4
.el .IP "($bool, \f(CW$desc\fR) = \s-1INTERPRET\s0($result_string)" 4
.IX Item "($bool, $desc) = INTERPRET($result_string)"
Inteprets a result string.  \f(CW$bool\fR indicates 1=pass/0=fail; \f(CW$desc\fR is an optional description.
.ie n .IP "$bool = \s-1EQUAL\s0($item1, $item2)" 4
.el .IP "\f(CW$bool\fR = \s-1EQUAL\s0($item1, \f(CW$item2\fR)" 4
.IX Item "$bool = EQUAL($item1, $item2)"
Deep comparison of 2 data structures (i.e. references to some kind of structure) or scalars.
.ie n .IP "$bool = \s-1EQUALS_FILE\s0($string, $filename)" 4
.el .IP "\f(CW$bool\fR = \s-1EQUALS_FILE\s0($string, \f(CW$filename\fR)" 4
.IX Item "$bool = EQUALS_FILE($string, $filename)"
Compares a string with a canned value in a file.
.ie n .IP "$bool = \s-1MATCHES_FILE\s0($string, $regexfilename)" 4
.el .IP "\f(CW$bool\fR = \s-1MATCHES_FILE\s0($string, \f(CW$regexfilename\fR)" 4
.IX Item "$bool = MATCHES_FILE($string, $regexfilename)"
Compares a value with a regex that is read from a file. The regex has the '^' anchor prepended and the '$' anchor appended,
after being read in from the file.
Handy if you have random numbers or dates in your output.
.ie n .IP "$bool = \s-1FILES_EQUAL\s0($filename1, $filename2)" 4
.el .IP "\f(CW$bool\fR = \s-1FILES_EQUAL\s0($filename1, \f(CW$filename2\fR)" 4
.IX Item "$bool = FILES_EQUAL($filename1, $filename2)"
Test if 2 files' contents are identical
.ie n .IP "$bool = \s-1DIED\s0($coderef)" 4
.el .IP "\f(CW$bool\fR = \s-1DIED\s0($coderef)" 4
.IX Item "$bool = DIED($coderef)"
Test if the coderef died
.ie n .IP "\s-1COMPILES\s0($filename, $strict, $scalar_reference)" 4
.el .IP "\s-1COMPILES\s0($filename, \f(CW$strict\fR, \f(CW$scalar_reference\fR)" 4
.IX Item "COMPILES($filename, $strict, $scalar_reference)"
Test if the perl code in \f(CW$filename\fR compiles \s-1OK,\s0 like perl \-c.
If \f(CW$strict\fR is true, tests with the options \-Mstrict \-w.
.Sp
In scalar context it returns 1 if the code compiled, 0 otherwise. In list context it returns the same boolean,
followed by the output (that is, standard output and standard error \fBcombined\fR) of the syntax check.
.Sp
If \f(CW$scalar_reference\fR is supplied and is a scalar reference then the standard output and standard
error of the syntax check subprocess will be captured \fBseparately\fR. Standard error
will be put into this scalar \- IO::CaptureOutput is loaded on demand to do this \-
and standard output will be returned as described above.
.ie n .IP "$contents = \s-1READ_FILE\s0($filename)" 4
.el .IP "\f(CW$contents\fR = \s-1READ_FILE\s0($filename)" 4
.IX Item "$contents = READ_FILE($filename)"
Reads the specified file and returns the contents.
Returns undef if file cannot be read.
.ie n .IP "$success = \s-1WRITE_FILE\s0($filename, $contents)" 4
.el .IP "\f(CW$success\fR = \s-1WRITE_FILE\s0($filename, \f(CW$contents\fR)" 4
.IX Item "$success = WRITE_FILE($filename, $contents)"
Writes the given contents to the specified file.
Returns undef if file cannot be written.
.SH "OVERHEAD"
.IX Header "OVERHEAD"
When Test::Assertions is imported with no arguments, \s-1ASSERT\s0 is aliased to an empty coderef.
If this is still too much runtime overhead for you, you can use a constant to optimise out \s-1ASSERT\s0 statements at compile time.
See the section on runtime testing in Test::Assertions::Manual for a discussion of overheads, some examples and some benchmark results.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
The following modules are loaded on demand:
.PP
.Vb 5
\& Carp
\& File::Spec
\& Test::More
\& File::Compare
\& IO::CaptureOutput
.Ve
.SH "RELATED MODULES"
.IX Header "RELATED MODULES"
.IP "Test and Test::Simple" 4
.IX Item "Test and Test::Simple"
Minimal unit testing modules
.IP "Test::More" 4
.IX Item "Test::More"
Richer unit testing toolkit compatible with Test and Test::Simple
.IP "Carp::Assert" 4
.IX Item "Carp::Assert"
Runtime testing toolkit
.SH "TODO"
.IX Header "TODO"
.Vb 4
\&        \- Declare ASSERT() with :assertions attribute in versions of perl >= 5.9
\&          so it can be optimised away at runtime. It should be possible to declare
\&          the attribute conditionally in a BEGIN block (with eval) for backwards
\&          compatibility
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test::Assertions::Manual \- A guide to using Test::Assertions
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Revision:\fR 1.54 $ on \f(CW$Date:\fR 2006/08/07 10:44:42 $ by \f(CW$Author:\fR simonf $
.SH "AUTHOR"
.IX Header "AUTHOR"
John Alden with additions from Piers Kent and Simon Flack 
<cpan _at_ bbc _dot_ co _dot_ uk>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
(c) \s-1BBC 2005.\s0 This program is free software; you can redistribute it and/or modify it under the \s-1GNU GPL.\s0
.PP
See the file \s-1COPYING\s0 in this distribution, or http://www.gnu.org/licenses/gpl.txt