phpman > perldoc > Test::Unit::Assert(3pm)

NAME
    Test::Unit::Assert - unit testing framework assertion class

SYNOPSIS
        # 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't mind us guessing
        $self->assert_equals('expected', $actual [, $optional_message]);
        $self->assert_equals(1,$actual);
        $self->assert_not_equals('not expected', $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('string','string');
        $self->assert_str_not_equals('stringA', 'stringB');

        # assert defined/undefined status
        $self->assert_null(undef);
        $self->assert_not_null('');

DESCRIPTION
    This class contains the various standard assertions used within the framework. With the
    exception of the "assert(CODEREF, @ARGS)", 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.

    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.

  Methods
    assert_equals(EXPECTED, ACTUAL [, MESSAGE])
    assert_not_equals(NOTEXPECTED, ACTUAL [, MESSAGE])
        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.

        If the first argument is an object, we check to see if the '==' operator has been overloaded
        and use that if it has, otherwise we do the string test.

    assert_num_equals
    assert_num_not_equals
        Force numeric comparison with these two.

    assert_str_equals
    assert_str_not_equals
        Force string comparison

    assert_matches(qr/PATTERN/, STRING [, MESSAGE])
    assert_does_not_match(qr/PATTERN/, STRING [, MESSAGE])
        Assert that STRING does or does not match the PATTERN regex.

    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.

        NOTE This is NOT well-tested on circular references. Nor am I quite sure what will happen
        with filehandles.

    assert_null(ARG [, MESSAGE])
    assert_not_null(ARG [, MESSAGE])
        Assert that ARG is defined or not defined.

    assert(BOOLEAN [, MESSAGE])
        Checks if the BOOLEAN expression returns a true value that is neither a CODE ref nor a
        REGEXP. Note that MESSAGE is almost non optional in this case, otherwise all the assertion
        has to go on is the truth or otherwise of the boolean.

        If you want to use the "old" style for testing regular expression matching, please be aware
        of this: the arguments to assert() are evaluated in list context, e.g. making a failing
        regex "pull" the message into the place of the first argument. Since this is usually just
        plain wrong, please use scalar() to force the regex comparison to yield a useful boolean
        value.

    assert(qr/PATTERN/, ACTUAL [, MESSAGE])
        Matches ACTUAL against the PATTERN regex. If you omit MESSAGE, you should get a sensible
        error message.

    assert(CODEREF, @ARGS)
        Calls CODEREF->(@ARGS). Assertion fails if this returns false (or throws
        Test::Unit::Failure)

    assert_raises(EXCEPTION_CLASS, CODEREF [, MESSAGE])
        Calls CODEREF->(). Assertion fails unless an exception of class EXCEPTION_CLASS is raised.

    multi_assert(ASSERTION, @ARGSETS)
        Calls $self->assert(ASSERTION, @$ARGSET) for each $ARGSET in @ARGSETS.

    ok(@ARGS)
        Simulates the behaviour of the Test module. Deprecated.

AUTHOR
    Copyright (c) 2000-2002, 2005 the PerlUnit Development Team (see Test::Unit or the AUTHORS file
    included in this distribution).

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

SEE ALSO
    *   Test::Unit::Assertion

    *   Test::Unit::Assertion::Regexp

    *   Test::Unit::Assertion::CodeRef

    *   Test::Unit::Assertion::Boolean

    *   Test::Unit::TestCase

    *   Test::Unit::Exception

    *   The framework self-testing suite (t::tlib::AllTests)