1Test::Assert(3)       User Contributed Perl Documentation      Test::Assert(3)
2
3
4

NAME

6       Test::Assert - Assertion methods for those who like JUnit.
7

SYNOPSIS

9         # Use as base class
10         package My::TestMethod;
11         use base 'Test::Assert';
12         sub test_method {
13           my $self = shift;
14           $self->assert_true(1, "pass");
15           $self->assert_true(0, "fail");
16         }
17
18         # Use as imported methods
19         package My::Test;
20         use Test::Assert ':all';
21         assert_true(1, "pass");
22         assert_true(0, "fail");
23         use Test::More;
24         assert_test(sub { require_ok($module) });
25
26         # Use for debugging purposes
27         # Assertions are compiled only if Test::Assert was used
28         # in the main package.
29         package My::Package;
30         use Test::Assert 'fail', 'ASSERT';
31         my $state = do_something();
32         assert_true($state >= 1 && $state <=2) if ASSERT;
33         if ($state == 1) {
34             # 1st state
35             do_foo();
36         } elsif ($state == 2) {
37             # 2nd and last state
38             do_bar();
39         }
40         my $a = get_a();
41         my $b = get_b();
42         assert_num_not_equals(0, $b) if ASSERT;
43         my $c = $a / $b;
44
45         $ perl -MTest::Assert script.pl  # sets Test::Assert::ASSERT to 1
46

DESCRIPTION

48       This class provides a set of assertion methods useful for writing
49       tests.  The API is based on JUnit4 and Test::Unit and the methods die
50       on failure.
51
52       The assertion methods can be used in class which is derived from
53       Test::Assert or used as standard Perl functions after importing them
54       into user's namespace.
55
56       Test::Assert can also wrap standard Test::Simple, Test::More or other
57       Test::Builder-based tests.
58
59       The assertions can be also used for run-time checking.
60

EXCEPTIONS

62       Exception::Assertion
63           Thrown whether an assertion failed.
64

IMPORTS

66       By default, the class does not export its symbols.
67
68       use Test::Assert;
69           Enables debug mode if it is used in "main" package.
70
71             package main;
72             use Test::Assert;    # Test::Assert::ASSERT is set to TRUE
73
74             $ perl -MTest::Assert script.pl    # ditto
75
76       use Test::Assert 'assert_true', 'fail', ...;
77           Imports some methods.
78
79       use Test::Assert ':all';
80           Imports all "assert_*" methods, "fail" method and "ASSERT"
81           constant.
82
83       use Test::Assert ':assert';
84           Imports all "assert_*" methods and "ASSERT" constant.
85
86       no Test::Assert;
87           Disables debug mode if it is used in "main" package.
88

CONSTANTS

90       ASSERT
91           This constant is set to true value if "Test::Assert" module is used
92           from "main" package.  It allows to enable debug mode globally from
93           command line.  The debug mode is disabled by default.
94
95             package My::Test;
96             use Test::Assert ':assert';
97             assert_true( 0 ) if ASSERT;  # fails only if debug mode is enabled
98
99             $ perl -MTest::Assert script.pl  # enable debug mode
100

METHODS

102       fail( message : Str = undef, reason : Str = undef )
103           Immediate fail the test.  The Exception::Assertion object will have
104           set message and reason attribute based on arguments.
105
106       assert_true( boolean : Bool, message : Str = undef )
107           Checks if boolean expression returns true value.
108
109       assert_false( boolean : Bool, message : Str = undef )
110           Checks if boolean expression returns false value.
111
112       assert_null( value : Any, message : Str = undef )
113       assert_not_null( value : Any, message : Str = undef )
114           Checks if value is defined or not defined.
115
116       assert_equals( value1 : Defined, value2 : Defined, message : Str =
117       undef )
118       assert_not_equals( value1 : Defined, value2 : Defined, message : Str =
119       undef )
120           Checks if value1 and value2 are equals or not equals.  If value1
121           and value2 look like numbers then they are compared with '=='
122           operator, otherwise the string 'eq' operator is used.
123
124       assert_num_equals( value1 : Defined, value2 : Defined, message : Str =
125       undef )
126       assert_num_not_equals( value1 : Defined, value2 : Defined, message :
127       Str = undef )
128           Force numeric comparation.
129
130       assert_str_equals( value1 : Defined, value2 : Defined, message : Str =
131       undef )
132       assert_str_not_equals( value1 : Defined, value2 : Defined, message :
133       Str = undef )
134           Force string comparation.
135
136       assert_matches( regexp : RegexpRef, value : Str, message : Str = undef
137       )
138       assert_not_matches( regexp : RegexpRef, value : Str, message : Str =
139       undef )
140           Checks if value matches pattern regexp.
141
142       assert_deep_equals( value1 : Ref, value2 : Ref, message : Str = undef )
143       assert_deep_not_equals( value1 : Ref, value2 : Ref, message : Str =
144       undef )
145           Checks if reference value1 is a deep copy of reference value2 or
146           not.  The references can be deep structure.  If they are different,
147           the message will display the place where they start differing.
148
149       assert_isa( class : Str, object : Defined, message : Str = undef )
150       assert_not_isa( class : Str, object : Defined, message : Str = undef )
151           Checks if value is a class or not.
152
153             assert_isa( 'My::Class', $obj );
154
155       assert_raises( expected : Any, code : CoreRef, message : Str = undef )
156           Runs the code and checks if it raises the expected exception.
157
158           If raised exception is an Exception::Base object, the assertion
159           passes if the exception "matches" expected argument (via
160           "Exception::Base->matches" method).
161
162           If raised exception is not an Exception::Base object, several
163           conditions are checked.  If expected argument is a string or array
164           reference, the assertion passes if the raised exception is a given
165           class.  If the argument is a regexp, the string representation of
166           exception is matched against regexp.
167
168             use Test::Assert 'assert_raises';
169
170             assert_raises( 'foo', sub { die 'foo' } );
171             assert_raises( ['Exception::Base'], sub { Exception::Base->throw } );
172
173       assert_test( code : CoreRef, message : Str = undef )
174           Wraps Test::Builder based test function and throws
175           Exception::Assertion if the test is failed.  The plan test have to
176           be disabled manually.  The Test::More module imports the "fail"
177           method by default which conflicts with "Test::Assert" "fail"
178           method.
179
180             use Test::Assert ':all';
181             use Test::More ignore => [ '!fail' ];
182
183             Test::Builder->new->no_plan;
184             Test::Builder->new->no_ending(1);
185
186             assert_test( sub { cmp_ok($got, '==', $expected, $test_name) } );
187

SEE ALSO

189       Exception::Assertion, Test::Unit::Lite.
190

BUGS

192       If you find the bug, please report it.
193

AUTHOR

195       Piotr Roszatycki <dexter@debian.org>
196

COPYRIGHT

198       Copyright (C) 2008, 2009 by Piotr Roszatycki <dexter@debian.org>.
199
200       This program is free software; you can redistribute it and/or modify it
201       under the same terms as Perl itself.
202
203       See <http://www.perl.com/perl/misc/Artistic.html>
204
205
206
207perl v5.12.0                      2010-05-06                   Test::Assert(3)