Test::Assert(3pm) | User Contributed Perl Documentation | Test::Assert(3pm) |
NAME¶
Test::Assert - Assertion methods for those who like JUnit.
SYNOPSIS¶
# Use as imported methods # package My::Test; use Test::Assert ':all'; assert_true(1, "pass"); assert_true(0, "fail"); use Test::More; assert_test(sub { require_ok($module) }); # Use for debugging purposes # Assertions are compiled only if Test::Assert was used # from the main package. # package My::Package; use Test::Assert ':assert'; my $state = do_something(); assert_true($state >= 1 && $state <=2) if ASSERT; if ($state == 1) { # 1st state do_foo(); } elsif ($state == 2) { # 2nd and last state do_bar(); } my $a = get_a(); my $b = get_b(); assert_num_not_equals(0, $b) if ASSERT; my $c = $a / $b; # Clean the namespace no Test::Assert; # From command line $ perl -MTest::Assert script.pl # sets Test::Assert::ASSERT to 1
DESCRIPTION¶
This class provides a set of assertion methods useful for writing tests. The API is based on JUnit4 and Test::Unit::Lite and the methods die on failure.
These assertion methods might be not useful for common Test::Builder-based (Test::Simple, Test::More, etc.) test units.
The assertion methods can be used in class which is derived from "Test::Assert" or used as standard Perl functions after importing them into user's namespace.
"Test::Assert" can also wrap standard Test::Simple, Test::More or other Test::Builder-based tests.
The assertions can be also used for run-time checking.
EXCEPTIONS¶
- Exception::Assertion
- Thrown whether an assertion failed.
USAGE¶
By default, the class does not export its symbols.
- use Test::Assert;
- Enables debug mode if it is used in
"main" package.
package main; use Test::Assert; # Test::Assert::ASSERT is set to TRUE $ perl -MTest::Assert script.pl # ditto
- use Test::Assert 'assert_true', 'fail', ...;
- Imports some methods.
- use Test::Assert ':all';
- Imports all "assert_*" methods, "fail" method and "ASSERT" constant.
- use Test::Assert ':assert';
- Imports all "assert_*" methods and "ASSERT" constant.
- no Test::Assert;
- Disables debug mode if it is used in "main" package.
CONSTANTS¶
- ASSERT
- This constant is set to true value if
"Test::Assert" module is used from
"main" package. It allows to enable
debug mode globally from command line. The debug mode is disabled by
default.
package My::Test; use Test::Assert ':assert'; assert_true( 0 ) if ASSERT; # fails only if debug mode is enabled $ perl -MTest::Assert script.pl # enable debug mode
METHODS¶
- fail( message : Str = undef, reason : Str = undef )
- Immediate fail the test. The Exception::Assertion object will have set message and reason attribute based on arguments.
- assert_true( boolean : Bool, message : Str = undef )
- Checks if boolean expression returns true value.
- assert_false( boolean : Bool, message : Str = undef )
- Checks if boolean expression returns false value.
- assert_null( value : Any, message : Str = undef )
- assert_not_null( value : Any, message : Str = undef )
- Checks if value is defined or not defined.
- assert_equals( value1 : Defined, value2 : Defined, message : Str = undef )
- assert_not_equals( value1 : Defined, value2 : Defined, message : Str = undef )
- Checks if value1 and value2 are equals or not equals. If value1 and value2 look like numbers then they are compared with '==' operator, otherwise the string 'eq' operator is used.
- assert_num_equals( value1 : Defined, value2 : Defined, message : Str = undef )
- assert_num_not_equals( value1 : Defined, value2 : Defined, message : Str = undef )
- Force numeric comparation.
- assert_str_equals( value1 : Defined, value2 : Defined, message : Str = undef )
- assert_str_not_equals( value1 : Defined, value2 : Defined, message : Str = undef )
- Force string comparation.
- assert_matches( regexp : RegexpRef, value : Str, message : Str = undef )
- assert_not_matches( regexp : RegexpRef, value : Str, message : Str = undef )
- Checks if value matches pattern regexp.
- assert_deep_equals( value1 : Ref, value2 : Ref, message : Str = undef )
- assert_deep_not_equals( value1 : Ref, value2 : Ref, message : Str = undef )
- Checks if reference value1 is a deep copy of reference value2 or not. The references can be deep structure. If they are different, the message will display the place where they start differing.
- assert_isa( class : Str, object : Defined, message : Str = undef )
- assert_not_isa( class : Str, object : Defined, message : Str = undef )
- Checks if value is a class or not.
assert_isa( 'My::Class', $obj );
- assert_raises( expected : Any, code : CodeRef, message : Str = undef )
- Runs the code and checks if it raises the expected
exception.
If raised exception is an Exception::Base object, the assertion passes if the exception "matches" expected argument (via "Exception::Base->matches" method).
If raised exception is not an Exception::Base object, several conditions are checked. If expected argument is a string or array reference, the assertion passes if the raised exception is a given class. If the argument is a regexp, the string representation of exception is matched against regexp.
use Test::Assert 'assert_raises'; assert_raises( 'foo', sub { die 'foo' } ); assert_raises( ['Exception::Base'], sub { Exception::Base->throw } );
- assert_test( code : CodeRef, message : Str = undef )
- Wraps Test::Builder based test function and throws Exception::Assertion if
the test is failed. The plan test have to be disabled manually. The
Test::More module imports the "fail"
method by default which conflicts with
"Test::Assert"
"fail" method.
use Test::Assert ':all'; use Test::More ignore => [ '!fail' ]; Test::Builder->new->no_plan; Test::Builder->new->no_ending(1); assert_test( sub { cmp_ok($got, '==', $expected, $test_name) } );
SEE ALSO¶
Exception::Assertion, Test::Unit::Lite.
BUGS¶
If you find the bug or want to implement new features, please report it at <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Assert>
AUTHOR¶
Piotr Roszatycki <dexter@cpan.org>
COPYRIGHT¶
Copyright (C) 2008, 2009 by Piotr Roszatycki <dexter@cpan.org>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
2011-08-24 | perl v5.40.0 |