.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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 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.
.\"
.\" 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::Unit::Assert 3pm"
.TH Test::Unit::Assert 3pm "2015-12-30" "perl v5.22.1" "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::Unit::Assert \- unit testing framework assertion class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    # this class is not intended to be used directly, 
\&    # normally you get the functionality by subclassing from 
\&    # Test::Unit::TestCase
\&
\&    use Test::Unit::TestCase;
\&
\&    # more code here ...
\&
\&    $self\->assert($your_condition_here, $your_optional_message_here);
\&
\&    # or, for regular expression comparisons:
\&    $self\->assert(qr/some_pattern/, $result);
\&
\&    # or, for functional style coderef tests:
\&    $self\->assert(sub {
\&                      $_[0] == $_[1]
\&                        or $self\->fail("Expected $_[0], got $_[1]");
\&                  }, 1, 2); 
\&
\&    # or, for old style regular expression comparisons
\&    # (strongly deprecated; see warning below)
\&    $self\->assert(scalar("foo" =~ /bar/), $your_optional_message_here);
\&
\&    # Or, if you don\*(Aqt mind us guessing
\&    $self\->assert_equals(\*(Aqexpected\*(Aq, $actual [, $optional_message]);
\&    $self\->assert_equals(1,$actual);
\&    $self\->assert_not_equals(\*(Aqnot expected\*(Aq, $actual [, $optional_message]);
\&    $self\->assert_not_equals(0,1);
\&
\&    # Or, if you want to force the comparator
\&    $self\->assert_num_equals(1,1);
\&    $self\->assert_num_not_equals(1,0);
\&    $self\->assert_str_equals(\*(Aqstring\*(Aq,\*(Aqstring\*(Aq);
\&    $self\->assert_str_not_equals(\*(AqstringA\*(Aq, \*(AqstringB\*(Aq);
\&
\&    # assert defined/undefined status
\&    $self\->assert_null(undef);
\&    $self\->assert_not_null(\*(Aq\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class contains the various standard assertions used within the
framework. With the exception of the \f(CW\*(C`assert(CODEREF, @ARGS)\*(C'\fR, all
the assertion methods take an optional message after the mandatory
fields. The message can either be a single string, or a list, which
will get concatenated.
.PP
Although you can specify a message, it is hoped that the default error
messages generated when an assertion fails will be good enough for
most cases.
.SS "Methods"
.IX Subsection "Methods"
.IP "assert_equals(\s-1EXPECTED, ACTUAL\s0 [, \s-1MESSAGE\s0])" 4
.IX Item "assert_equals(EXPECTED, ACTUAL [, MESSAGE])"
.PD 0
.IP "assert_not_equals(\s-1NOTEXPECTED, ACTUAL\s0 [, \s-1MESSAGE\s0])" 4
.IX Item "assert_not_equals(NOTEXPECTED, ACTUAL [, MESSAGE])"
.PD
The catch all assertions of (in)equality. We make a guess about
whether to test for numeric or string (in)equality based on the first
argument. If it looks like a number then we do a numeric test, if it
looks like a string, we do a string test.
.Sp
If the first argument is an object, we check to see if the \f(CW\*(Aq==\*(Aq\fR
operator has been overloaded and use that if it has, otherwise we do
the string test.
.IP "assert_num_equals" 4
.IX Item "assert_num_equals"
.PD 0
.IP "assert_num_not_equals" 4
.IX Item "assert_num_not_equals"
.PD
Force numeric comparison with these two.
.IP "assert_str_equals" 4
.IX Item "assert_str_equals"
.PD 0
.IP "assert_str_not_equals" 4
.IX Item "assert_str_not_equals"
.PD
Force string comparison
.IP "assert_matches(qr/PATTERN/, \s-1STRING\s0 [, \s-1MESSAGE\s0])" 4
.IX Item "assert_matches(qr/PATTERN/, STRING [, MESSAGE])"
.PD 0
.IP "assert_does_not_match(qr/PATTERN/, \s-1STRING\s0 [, \s-1MESSAGE\s0])" 4
.IX Item "assert_does_not_match(qr/PATTERN/, STRING [, MESSAGE])"
.PD
Assert that \s-1STRING\s0 does or does not match the \s-1PATTERN\s0 regex.
.IP "assert_deep_equals(A, B [, \s-1MESSAGE \s0])" 4
.IX Item "assert_deep_equals(A, B [, MESSAGE ])"
Assert that reference A is a deep copy of reference B.  The references
can be complex, deep structures.  If they are different, the default
message will display the place where they start differing.
.Sp
\&\fB\s-1NOTE\s0\fR This is \s-1NOT\s0 well-tested on circular references.  Nor am I
quite sure what will happen with filehandles.
.IP "assert_null(\s-1ARG\s0 [, \s-1MESSAGE\s0])" 4
.IX Item "assert_null(ARG [, MESSAGE])"
.PD 0
.IP "assert_not_null(\s-1ARG\s0 [, \s-1MESSAGE\s0])" 4
.IX Item "assert_not_null(ARG [, MESSAGE])"
.PD
Assert that \s-1ARG\s0 is defined or not defined.
.IP "assert(\s-1BOOLEAN\s0 [, \s-1MESSAGE\s0])" 4
.IX Item "assert(BOOLEAN [, MESSAGE])"
Checks if the \s-1BOOLEAN\s0 expression returns a true value that is neither
a \s-1CODE\s0 ref nor a \s-1REGEXP. \s0 Note that \s-1MESSAGE\s0 is almost non optional in
this case, otherwise all the assertion has to go on is the truth or
otherwise of the boolean.
.Sp
If you want to use the \*(L"old\*(R" style for testing regular expression
matching, please be aware of this: the arguments to \fIassert()\fR are
evaluated in list context, e.g. making a failing regex \*(L"pull\*(R" the
message into the place of the first argument. Since this is usually
just plain wrong, please use \fIscalar()\fR to force the regex comparison
to yield a useful boolean value.
.IP "assert(qr/PATTERN/, \s-1ACTUAL\s0 [, \s-1MESSAGE\s0])" 4
.IX Item "assert(qr/PATTERN/, ACTUAL [, MESSAGE])"
Matches \s-1ACTUAL\s0 against the \s-1PATTERN\s0 regex.  If you omit \s-1MESSAGE,\s0 you
should get a sensible error message.
.ie n .IP "assert(\s-1CODEREF,\s0 @ARGS)" 4
.el .IP "assert(\s-1CODEREF,\s0 \f(CW@ARGS\fR)" 4
.IX Item "assert(CODEREF, @ARGS)"
Calls \s-1CODEREF\-\s0>(@ARGS).  Assertion fails if this returns false (or
throws Test::Unit::Failure)
.IP "assert_raises(\s-1EXCEPTION_CLASS, CODEREF\s0 [, \s-1MESSAGE\s0])" 4
.IX Item "assert_raises(EXCEPTION_CLASS, CODEREF [, MESSAGE])"
Calls \s-1CODEREF\-\s0>().  Assertion fails unless an exception of class
\&\s-1EXCEPTION_CLASS\s0 is raised.
.ie n .IP "multi_assert(\s-1ASSERTION,\s0 @ARGSETS)" 4
.el .IP "multi_assert(\s-1ASSERTION,\s0 \f(CW@ARGSETS\fR)" 4
.IX Item "multi_assert(ASSERTION, @ARGSETS)"
Calls \f(CW$self\fR\->assert(\s-1ASSERTION,\s0 @$ARGSET) for each \f(CW$ARGSET\fR in \f(CW@ARGSETS\fR.
.IP "ok(@ARGS)" 4
.IX Item "ok(@ARGS)"
Simulates the behaviour of the Test module.  \fBDeprecated.\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 2000\-2002, 2005 the PerlUnit Development Team
(see Test::Unit or the \fI\s-1AUTHORS\s0\fR file included in this
distribution).
.PP
All rights reserved. This program is free software; you can
redistribute it and/or modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Test::Unit::Assertion
.IP "\(bu" 4
Test::Unit::Assertion::Regexp
.IP "\(bu" 4
Test::Unit::Assertion::CodeRef
.IP "\(bu" 4
Test::Unit::Assertion::Boolean
.IP "\(bu" 4
Test::Unit::TestCase
.IP "\(bu" 4
Test::Unit::Exception
.IP "\(bu" 4
The framework self-testing suite
(t::tlib::AllTests)