1More(3) User Contributed Perl Documentation More(3)
2
6 Carp::Assert::More - Convenience assertions for common situations
7
9 Version 2.3.0
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 convenient set of assertions to make the habit
21 of writing assertions even easier.
22 Everything in here is effectively syntactic sugar. There's no
24 technical difference between calling one of these functions:
25 assert_datetime( $foo );
27 assert_isa( $foo, 'DateTime' );
28 that are provided by Carp::Assert::More and calling these assertions
30 from Carp::Assert
31 assert( defined $foo );
33 assert( ref($foo) eq 'DateTime' );
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 assert_is( $string, $match [,$name] )
40 Asserts that $string is the same string value as $match.
41 "undef" is not converted to an empty string. If both strings are
43 "undef", they match. If only one string is "undef", they don't match.
44 assert_isnt( $string, $unmatch [,$name] )
46 Asserts that $string does NOT have the same string value as $unmatch.
47 "undef" is not converted to an empty string.
49 assert_cmp( $x, $op, $y [,$name] )
51 Asserts that the relation "$x $op $y" is true. It lets you know why the
52 comparsison failed, rather than simply that it did fail, by giving
53 better diagnostics than a plain assert(), as well as showing the
54 operands in the stacktrace.
55 Plain assert():
57 assert( $nitems <= 10, 'Ten items or fewer in the express lane' );
59 Assertion (Ten items or fewer in the express lane) failed!
61 Carp::Assert::assert("", "Ten items or fewer in the express lane") called at foo.pl line 12
62 With assert_cmp():
64 assert_cmp( $nitems, '<=', 10, 'Ten items or fewer in the express lane' );
66 Assertion (Ten items or fewer in the express lane) failed!
68 Failed: 14 <= 10
69 Carp::Assert::More::assert_cmp(14, "<=", 10, "Ten items or fewer in the express lane") called at foo.pl line 11
70 The following operators are supported:
72 • == numeric equal
74 • != numeric not equal
76 • > numeric greater than
78 • >= numeric greater than or equal
80 • < numeric less than
82 • <= numeric less than or equal
84 • lt string less than
86 • le string less than or equal
88 • gt string less than
90 • ge string less than or equal
92 There is no support for "eq" or "ne" because those already have
94 "assert_is" and "assert_isnt", respectively.
95 If either $x or $y is undef, the assertion will fail.
97 If the operator is numeric, and $x or $y are not numbers, the assertion
99 will fail.
100 assert_like( $string, qr/regex/ [,$name] )
102 Asserts that $string matches qr/regex/.
103 The assertion fails either the string or the regex are undef.
105 assert_unlike( $string, qr/regex/ [,$name] )
107 Asserts that $string matches qr/regex/.
108 The assertion fails if the regex is undef.
110 assert_defined( $this [, $name] )
112 Asserts that $this is defined.
113 assert_undefined( $this [, $name] )
115 Asserts that $this is not defined.
116 assert_nonblank( $this [, $name] )
118 Asserts that $this is not a reference and is not an empty string.
119
121 assert_numeric( $n [, $name] )
122 Asserts that $n looks like a number, according to
123 "Scalar::Util::looks_like_number". "undef" will always fail.
124 assert_integer( $this [, $name ] )
126 Asserts that $this is an integer, which may be zero or negative.
127 assert_integer( 0 ); # pass
129 assert_integer( 14 ); # pass
130 assert_integer( -14 ); # pass
131 assert_integer( '14.' ); # FAIL
132 assert_nonzero( $this [, $name ] )
134 Asserts that the numeric value of $this is defined and is not zero.
135 assert_nonzero( 0 ); # FAIL
137 assert_nonzero( -14 ); # pass
138 assert_nonzero( '14.' ); # pass
139 assert_positive( $this [, $name ] )
141 Asserts that $this is defined, numeric and greater than zero.
142 assert_positive( 0 ); # FAIL
144 assert_positive( -14 ); # FAIL
145 assert_positive( '14.' ); # pass
146 assert_nonnegative( $this [, $name ] )
148 Asserts that $this is defined, numeric and greater than or equal to
149 zero.
150 assert_nonnegative( 0 ); # pass
152 assert_nonnegative( -14 ); # FAIL
153 assert_nonnegative( '14.' ); # pass
154 assert_nonnegative( 'dog' ); # pass
155 assert_negative( $this [, $name ] )
157 Asserts that the numeric value of $this is defined and less than zero.
158 assert_negative( 0 ); # FAIL
160 assert_negative( -14 ); # pass
161 assert_negative( '14.' ); # FAIL
162 assert_nonzero_integer( $this [, $name ] )
164 Asserts that the numeric value of $this is defined, an integer, and not
165 zero.
166 assert_nonzero_integer( 0 ); # FAIL
168 assert_nonzero_integer( -14 ); # pass
169 assert_nonzero_integer( '14.' ); # FAIL
170 assert_positive_integer( $this [, $name ] )
172 Asserts that the numeric value of $this is defined, an integer and
173 greater than zero.
174 assert_positive_integer( 0 ); # FAIL
176 assert_positive_integer( -14 ); # FAIL
177 assert_positive_integer( '14.' ); # FAIL
178 assert_positive_integer( '14' ); # pass
179 assert_nonnegative_integer( $this [, $name ] )
181 Asserts that the numeric value of $this is defined, an integer, and not
182 less than zero.
183 assert_nonnegative_integer( 0 ); # pass
185 assert_nonnegative_integer( -14 ); # FAIL
186 assert_nonnegative_integer( '14.' ); # FAIL
187 assert_negative_integer( $this [, $name ] )
189 Asserts that the numeric value of $this is defined, an integer, and
190 less than zero.
191 assert_negative_integer( 0 ); # FAIL
193 assert_negative_integer( -14 ); # pass
194 assert_negative_integer( '14.' ); # FAIL
195
197 assert_isa( $this, $type [, $name ] )
198 Asserts that $this is an object of type $type.
199 assert_isa_in( $obj, \@types [, $description] )
201 Assert that the blessed $obj isa one of the types in "\@types".
202 assert_isa_in( $obj, [ 'My::Foo', 'My::Bar' ], 'Must pass either a Foo or Bar object' );
204 assert_empty( $this [, $name ] )
206 $this must be a ref to either a hash or an array. Asserts that that
207 collection contains no elements. Will assert (with its own message,
208 not $name) unless given a hash or array ref. It is OK if $this has
209 been blessed into objecthood, but the semantics of checking an object
210 to see if it does not have keys (for a hashref) or returns 0 in scalar
211 context (for an array ref) may not be what you want.
212 assert_empty( 0 ); # FAIL
214 assert_empty( 'foo' ); # FAIL
215 assert_empty( undef ); # FAIL
216 assert_empty( {} ); # pass
217 assert_empty( [] ); # pass
218 assert_empty( {foo=>1} );# FAIL
219 assert_empty( [1,2,3] ); # FAIL
220 assert_nonempty( $this [, $name ] )
222 $this must be a ref to either a hash or an array. Asserts that that
223 collection contains at least 1 element. Will assert (with its own
224 message, not $name) unless given a hash or array ref. It is OK if
225 $this has been blessed into objecthood, but the semantics of checking
226 an object to see if it has keys (for a hashref) or returns >0 in scalar
227 context (for an array ref) may not be what you want.
228 assert_nonempty( 0 ); # FAIL
230 assert_nonempty( 'foo' ); # FAIL
231 assert_nonempty( undef ); # FAIL
232 assert_nonempty( {} ); # FAIL
233 assert_nonempty( [] ); # FAIL
234 assert_nonempty( {foo=>1} );# pass
235 assert_nonempty( [1,2,3] ); # pass
236 assert_nonref( $this [, $name ] )
238 Asserts that $this is not undef and not a reference.
239 assert_hashref( $ref [,$name] )
241 Asserts that $ref is defined, and is a reference to a (possibly empty)
242 hash.
243 NB: This method returns false for objects, even those whose underlying
245 data is a hashref. This is as it should be, under the assumptions that:
246 (a) you shouldn't rely on the underlying data structure of a particular
248 class, and
249 (b) you should use "assert_isa" instead.
251 assert_hashref_nonempty( $ref [,$name] )
253 Asserts that $ref is defined and is a reference to a hash with at least
254 one key/value pair.
255 assert_arrayref( $ref [, $name] )
257 assert_listref( $ref [,$name] )
258 Asserts that $ref is defined, and is a reference to an array, which may
259 or may not be empty.
260 NB: The same caveat about objects whose underlying structure is a hash
262 (see "assert_hashref") applies here; this method returns false even for
263 objects whose underlying structure is an array.
264 "assert_listref" is an alias for "assert_arrayref" and may go away in
266 the future. Use "assert_arrayref" instead.
267 assert_arrayref_nonempty( $ref [, $name] )
269 Asserts that $ref is reference to an array that has at least one
270 element in it.
271 assert_arrayref_of( $ref, $type [, $name] )
273 Asserts that $ref is reference to an array that has at least one
274 element in it, and every one of those elements is of type $type.
275 For example:
277 my @users = get_users();
279 assert_arrayref_of( \@users, 'My::User' );
280 assert_aoh( $ref [, $name ] )
282 Verifies that $array is an arrayref, and that every element is a
283 hashref.
284 The array $array can be an empty arraref and the assertion will pass.
286 assert_coderef( $ref [,$name] )
288 Asserts that $ref is defined, and is a reference to a closure.
289
291 assert_datetime( $date )
292 Asserts that $date is a DateTime object.
293
295 assert_in( $string, \@inlist [,$name] );
296 Asserts that $string matches one of the elements of \@inlist. $string
297 may be undef.
298 \@inlist must be an array reference of non-ref strings. If any element
300 is a reference, the assertion fails.
301 assert_exists( \%hash, $key [,$name] )
303 assert_exists( \%hash, \@keylist [,$name] )
304 Asserts that %hash is indeed a hash, and that $key exists in %hash, or
305 that all of the keys in @keylist exist in %hash.
306 assert_exists( \%custinfo, 'name', 'Customer has a name field' );
308 assert_exists( \%custinfo, [qw( name addr phone )],
310 'Customer has name, address and phone' );
311 assert_lacks( \%hash, $key [,$name] )
313 assert_lacks( \%hash, \@keylist [,$name] )
314 Asserts that %hash is indeed a hash, and that $key does NOT exist in
315 %hash, or that none of the keys in @keylist exist in %hash. The list
316 @keylist cannot be empty.
317 assert_lacks( \%users, 'root', 'Root is not in the user table' );
319 assert_lacks( \%users, [qw( root admin nobody )], 'No bad usernames found' );
321 assert_all_keys_in( \%hash, \@names [, $name ] )
323 Asserts that each key in %hash is in the list of @names.
324 This is used to ensure that there are no extra keys in a given hash.
326 assert_all_keys_in( $obj, [qw( height width depth )], '$obj can only contain height, width and depth keys' );
328 You can pass an empty list of @names.
330 assert_keys_are( \%hash, \@keys [, $name ] )
332 Asserts that the keys for %hash are exactly @keys, no more and no less.
333
335 assert_context_nonvoid( [$name] )
336 Verifies that the function currently being executed has not been called
337 in void context. This is to ensure the calling function is not
338 ignoring the return value of the executing function.
339 Given this function:
341 sub something {
343 ...
344 assert_context_scalar();
346 return $important_value;
348 }
349 These calls to "something" will pass:
351 my $val = something();
353 my @things = something();
354 but this will fail:
356 something();
358 assert_context_scalar( [$name] )
360 Verifies that the function currently being executed has been called in
361 scalar context. This is to ensure the calling function is not ignoring
362 the return value of the executing function.
363 Given this function:
365 sub something {
367 ...
368 assert_context_scalar();
370 return $important_value;
372 }
373 This call to "something" will pass:
375 my $val = something();
377 but these will fail:
379 something();
381 my @things = something();
382
384 assert_fail( [$name] )
385 Assertion that always fails. assert_fail($msg) is exactly the same as
386 calling "assert(0,$msg)", but it eliminates that case where you
387 accidentally use assert($msg), which of course never fires.
388
390 Copyright 2005-2023 Andy Lester
391 This program is free software; you can redistribute it and/or modify it
393 under the terms of the Artistic License version 2.0.
394
396 Thanks to Eric A. Zarko, Bob Diss, Pete Krawczyk, David Storrs, Dan
397 Friedman, Allard Hoeve, Thomas L. Shinnick, and Leland Johnson for code
398 and fixes.
399perl v5.38.0 2023-07-20 More(3)