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

DESCRIPTION

51       This class provides a set of assertion methods useful for writing
52       tests.  The API is based on JUnit4 and Test::Unit::Lite and the methods
53       die on failure.
54
55       These assertion methods might be not useful for common
56       Test::Builder-based (Test::Simple, Test::More, etc.) test units.
57
58       The assertion methods can be used in class which is derived from
59       "Test::Assert" or used as standard Perl functions after importing them
60       into user's namespace.
61
62       "Test::Assert" can also wrap standard Test::Simple, Test::More or other
63       Test::Builder-based tests.
64
65       The assertions can be also used for run-time checking.
66

EXCEPTIONS

68       Exception::Assertion
69           Thrown whether an assertion failed.
70

USAGE

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

CONSTANTS

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

METHODS

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

SEE ALSO

195       Exception::Assertion, Test::Unit::Lite.
196

BUGS

198       If you find the bug or want to implement new features, please report it
199       at <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Assert>
200

AUTHOR

202       Piotr Roszatycki <dexter@cpan.org>
203

COPYRIGHT

205       Copyright (C) 2008, 2009 by Piotr Roszatycki <dexter@cpan.org>.
206
207       This program is free software; you can redistribute it and/or modify it
208       under the same terms as Perl itself.
209
210       See <http://www.perl.com/perl/misc/Artistic.html>
211
212
213
214perl v5.36.0                      2023-01-20                   Test::Assert(3)