1More(3) User Contributed Perl Documentation More(3)
2
6 Carp::Assert::More - convenience wrappers around Carp::Assert
7
9 Version 1.26
10
12 A set of convenience functions for common assertions.
13 use Carp::Assert::More;
15 my $obj = My::Object;
17 assert_isa( $obj, 'My::Object', 'Got back a correct object' );
18
20 Carp::Assert::More is a set of wrappers around the Carp::Assert
21 functions to make the habit of writing assertions even easier.
22 Everything in here is effectively syntactic sugar. There's no
24 technical reason to use
25 assert_isa( $foo, 'HTML::Lint' );
27 instead of
29 assert( defined $foo );
31 assert( ref($foo) eq 'HTML::Lint' );
32 other than readability and simplicity of the code.
34 My intent here is to make common assertions easy so that we as
36 programmers have no excuse to not use them.
37
39 I haven't specifically done anything to make Carp::Assert::More be
40 backwards compatible with anything besides Perl 5.6.1, much less back
41 to 5.004. Perhaps someone with better testing resources in that area
42 can help me out here.
43
45 assert_is( $string, $match [,$name] )
46 Asserts that $string matches $match.
47 assert_isnt( $string, $unmatch [,$name] )
49 Asserts that $string does NOT match $unmatch.
50 assert_like( $string, qr/regex/ [,$name] )
52 Asserts that $string matches qr/regex/.
53 The assertion fails either the string or the regex are undef.
55 assert_unlike( $string, qr/regex/ [,$name] )
57 Asserts that $string matches qr/regex/.
58 The assertion fails if the regex is undef.
60 assert_defined( $this [, $name] )
62 Asserts that $this is defined.
63 assert_undefined( $this [, $name] )
65 Asserts that $this is not defined.
66 assert_nonblank( $this [, $name] )
68 Asserts that $this is not blank and not a reference.
69
71 assert_numeric( $n [, $name] )
72 Asserts that $n looks like a number, according to
73 "Scalar::Util::looks_like_number".
74 assert_integer( $this [, $name ] )
76 Asserts that $this is an integer, which may be zero or negative.
77 assert_integer( 0 ); # pass
79 assert_integer( 14 ); # pass
80 assert_integer( -14 ); # pass
81 assert_integer( '14.' ); # FAIL
82 assert_nonzero( $this [, $name ] )
84 Asserts that the numeric value of $this is not zero.
85 assert_nonzero( 0 ); # FAIL
87 assert_nonzero( -14 ); # pass
88 assert_nonzero( '14.' ); # pass
89 Asserts that the numeric value of $this is not zero.
91 assert_positive( $this [, $name ] )
93 Asserts that the numeric value of $this is greater than zero.
94 assert_positive( 0 ); # FAIL
96 assert_positive( -14 ); # FAIL
97 assert_positive( '14.' ); # pass
98 assert_nonnegative( $this [, $name ] )
100 Asserts that the numeric value of $this is greater than or equal to
101 zero. Since non-numeric strings evaluate to zero, this means that any
102 non-numeric string will pass.
103 assert_nonnegative( 0 ); # pass
105 assert_nonnegative( -14 ); # FAIL
106 assert_nonnegative( '14.' ); # pass
107 assert_nonnegative( 'dog' ); # pass
108 assert_negative( $this [, $name ] )
110 Asserts that the numeric value of $this is less than zero.
111 assert_negative( 0 ); # FAIL
113 assert_negative( -14 ); # pass
114 assert_negative( '14.' ); # FAIL
115 assert_nonzero_integer( $this [, $name ] )
117 Asserts that the numeric value of $this is not zero, and that $this is
118 an integer.
119 assert_nonzero_integer( 0 ); # FAIL
121 assert_nonzero_integer( -14 ); # pass
122 assert_nonzero_integer( '14.' ); # FAIL
123 assert_positive_integer( $this [, $name ] )
125 Asserts that the numeric value of $this is greater than zero, and that
126 $this is an integer.
127 assert_positive_integer( 0 ); # FAIL
129 assert_positive_integer( -14 ); # FAIL
130 assert_positive_integer( '14.' ); # FAIL
131 assert_positive_integer( '14' ); # pass
132 assert_nonnegative_integer( $this [, $name ] )
134 Asserts that the numeric value of $this is not less than zero, and that
135 $this is an integer.
136 assert_nonnegative_integer( 0 ); # pass
138 assert_nonnegative_integer( -14 ); # pass
139 assert_nonnegative_integer( '14.' ); # FAIL
140 assert_negative_integer( $this [, $name ] )
142 Asserts that the numeric value of $this is less than zero, and that
143 $this is an integer.
144 assert_negative_integer( 0 ); # FAIL
146 assert_negative_integer( -14 ); # pass
147 assert_negative_integer( '14.' ); # FAIL
148
150 assert_isa( $this, $type [, $name ] )
151 Asserts that $this is an object of type $type.
152 assert_isa_in( $obj, \@types [, $description] )
154 Assert that the blessed $obj isa one of the types in "\@types".
155 assert_isa_in( $obj, [ 'My::Foo', 'My::Bar' ], 'Must pass either a Foo or Bar object' );
157 assert_empty( $this [, $name ] )
159 $this must be a ref to either a hash or an array. Asserts that that
160 collection contains no elements. Will assert (with its own message,
161 not $name) unless given a hash or array ref. It is OK if $this has
162 been blessed into objecthood, but the semantics of checking an object
163 to see if it does not have keys (for a hashref) or returns 0 in scalar
164 context (for an array ref) may not be what you want.
165 assert_empty( 0 ); # FAIL
167 assert_empty( 'foo' ); # FAIL
168 assert_empty( undef ); # FAIL
169 assert_empty( {} ); # pass
170 assert_empty( [] ); # pass
171 assert_empty( {foo=>1} );# FAIL
172 assert_empty( [1,2,3] ); # FAIL
173 assert_nonempty( $this [, $name ] )
175 $this must be a ref to either a hash or an array. Asserts that that
176 collection contains at least 1 element. Will assert (with its own
177 message, not $name) unless given a hash or array ref. It is OK if
178 $this has been blessed into objecthood, but the semantics of checking
179 an object to see if it has keys (for a hashref) or returns >0 in scalar
180 context (for an array ref) may not be what you want.
181 assert_nonempty( 0 ); # FAIL
183 assert_nonempty( 'foo' ); # FAIL
184 assert_nonempty( undef ); # FAIL
185 assert_nonempty( {} ); # FAIL
186 assert_nonempty( [] ); # FAIL
187 assert_nonempty( {foo=>1} );# pass
188 assert_nonempty( [1,2,3] ); # pass
189 assert_nonref( $this [, $name ] )
191 Asserts that $this is not undef and not a reference.
192 assert_hashref( $ref [,$name] )
194 Asserts that $ref is defined, and is a reference to a (possibly empty)
195 hash.
196 NB: This method returns false for objects, even those whose underlying
198 data is a hashref. This is as it should be, under the assumptions that:
199 (a) you shouldn't rely on the underlying data structure of a particular
201 class, and
202 (b) you should use "assert_isa" instead.
204 assert_hashref_nonempty( $ref [,$name] )
206 Asserts that $ref is defined and is a reference to a hash with at least
207 one key/value pair.
208 assert_arrayref( $ref [, $name] )
210 assert_listref( $ref [,$name] )
211 Asserts that $ref is defined, and is a reference to an array, which may
212 or may not be empty.
213 NB: The same caveat about objects whose underlying structure is a hash
215 (see "assert_hashref") applies here; this method returns false even for
216 objects whose underlying structure is an array.
217 "assert_listref" is an alias for "assert_arrayref" and may go away in
219 the future. Use "assert_arrayref" instead.
220 assert_arrayref_nonempty( $ref [, $name] )
222 Asserts that $ref is reference to an array that has at least one
223 element in it.
224 assert_aoh( $ref [, $name ] )
226 Verifies that $array is an arrayref, and that every element is a
227 hashref.
228 The array $array can be an empty arraref and the assertion will pass.
230 assert_coderef( $ref [,$name] )
232 Asserts that $ref is defined, and is a reference to a closure.
233
235 assert_datetime( $date )
236 Asserts that $date is a DateTime object.
237
239 assert_in( $string, \@inlist [,$name] );
240 Asserts that $string is defined and matches one of the elements of
241 \@inlist.
242 \@inlist must be an array reference of defined strings.
244 assert_exists( \%hash, $key [,$name] )
246 assert_exists( \%hash, \@keylist [,$name] )
247 Asserts that %hash is indeed a hash, and that $key exists in %hash, or
248 that all of the keys in @keylist exist in %hash.
249 assert_exists( \%custinfo, 'name', 'Customer has a name field' );
251 assert_exists( \%custinfo, [qw( name addr phone )],
253 'Customer has name, address and phone' );
254 assert_lacks( \%hash, $key [,$name] )
256 assert_lacks( \%hash, \@keylist [,$name] )
257 Asserts that %hash is indeed a hash, and that $key does NOT exist in
258 %hash, or that none of the keys in @keylist exist in %hash.
259 assert_lacks( \%users, 'root', 'Root is not in the user table' );
261 assert_lacks( \%users, [qw( root admin nobody )], 'No bad usernames found' );
263 assert_all_keys_in( \%hash, \@names [, $name ] )
265 Asserts that each key in %hash is in the list of @names.
266 This is used to ensure that there are no extra keys in a given hash.
268 assert_all_keys_in( $obj, [qw( height width depth )], '$obj can only contain height, width and depth keys' );
270 assert_keys_are( \%hash, \@keys [, $name ] )
272 Asserts that the keys for %hash are exactly @keys, no more and no less.
273
275 assert_fail( [$name] )
276 Assertion that always fails. "assert_fail($msg)" is exactly the same
277 as calling "assert(0,$msg)", but it eliminates that case where you
278 accidentally use "assert($msg)", which of course never fires.
279
281 Copyright 2005-2020 Andy Lester.
282 This program is free software; you can redistribute it and/or modify it
284 under the terms of the Artistic License version 2.0.
285
287 Thanks to Eric A. Zarko, Bob Diss, Pete Krawczyk, David Storrs, Dan
288 Friedman, Allard Hoeve, Thomas L. Shinnick, and Leland Johnson for code
289 and fixes.
290perl v5.32.1 2021-01-26 More(3)