1More(3) User Contributed Perl Documentation More(3)
2
6 Carp::Assert::More - Convenience assertions for common situations
7
9 Version 2.2.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 matches $match.
41 assert_isnt( $string, $unmatch [,$name] )
43 Asserts that $string does NOT match $unmatch.
44 assert_cmp( $x, $op, $y [,$name] )
46 Asserts that the relation "$x $op $y" is true. For example:
47 assert_cmp( $divisor, '!=', 0, 'Divisor must not be zero' );
49 is the same as:
51 assert( $divisor != 0, 'Divisor must not be zero' );
53 but with better error reporting.
55 The following operators are supported:
57 • == numeric equal
59 • != numeric not equal
61 • > numeric greater than
63 • >= numeric greater than or equal
65 • < numeric less than
67 • <= numeric less than or equal
69 • lt string less than
71 • le string less than or equal
73 • gt string less than
75 • ge string less than or equal
77 There is no support for "eq" or "ne" because those already have
79 "assert_is" and "assert_isnt", respectively.
80 If either $x or $y is undef, the assertion will fail.
82 If the operator is numeric, and $x or $y are not numbers, the assertion
84 will fail.
85 assert_like( $string, qr/regex/ [,$name] )
87 Asserts that $string matches qr/regex/.
88 The assertion fails either the string or the regex are undef.
90 assert_unlike( $string, qr/regex/ [,$name] )
92 Asserts that $string matches qr/regex/.
93 The assertion fails if the regex is undef.
95 assert_defined( $this [, $name] )
97 Asserts that $this is defined.
98 assert_undefined( $this [, $name] )
100 Asserts that $this is not defined.
101 assert_nonblank( $this [, $name] )
103 Asserts that $this is not a reference and is not an empty string.
104
106 assert_numeric( $n [, $name] )
107 Asserts that $n looks like a number, according to
108 "Scalar::Util::looks_like_number". "undef" will always fail.
109 assert_integer( $this [, $name ] )
111 Asserts that $this is an integer, which may be zero or negative.
112 assert_integer( 0 ); # pass
114 assert_integer( 14 ); # pass
115 assert_integer( -14 ); # pass
116 assert_integer( '14.' ); # FAIL
117 assert_nonzero( $this [, $name ] )
119 Asserts that the numeric value of $this is defined and is not zero.
120 assert_nonzero( 0 ); # FAIL
122 assert_nonzero( -14 ); # pass
123 assert_nonzero( '14.' ); # pass
124 assert_positive( $this [, $name ] )
126 Asserts that $this is defined, numeric and greater than zero.
127 assert_positive( 0 ); # FAIL
129 assert_positive( -14 ); # FAIL
130 assert_positive( '14.' ); # pass
131 assert_nonnegative( $this [, $name ] )
133 Asserts that $this is defined, numeric and greater than or equal to
134 zero.
135 assert_nonnegative( 0 ); # pass
137 assert_nonnegative( -14 ); # FAIL
138 assert_nonnegative( '14.' ); # pass
139 assert_nonnegative( 'dog' ); # pass
140 assert_negative( $this [, $name ] )
142 Asserts that the numeric value of $this is defined and less than zero.
143 assert_negative( 0 ); # FAIL
145 assert_negative( -14 ); # pass
146 assert_negative( '14.' ); # FAIL
147 assert_nonzero_integer( $this [, $name ] )
149 Asserts that the numeric value of $this is defined, an integer, and not
150 zero.
151 assert_nonzero_integer( 0 ); # FAIL
153 assert_nonzero_integer( -14 ); # pass
154 assert_nonzero_integer( '14.' ); # FAIL
155 assert_positive_integer( $this [, $name ] )
157 Asserts that the numeric value of $this is defined, an integer and
158 greater than zero.
159 assert_positive_integer( 0 ); # FAIL
161 assert_positive_integer( -14 ); # FAIL
162 assert_positive_integer( '14.' ); # FAIL
163 assert_positive_integer( '14' ); # pass
164 assert_nonnegative_integer( $this [, $name ] )
166 Asserts that the numeric value of $this is defined, an integer, and not
167 less than zero.
168 assert_nonnegative_integer( 0 ); # pass
170 assert_nonnegative_integer( -14 ); # FAIL
171 assert_nonnegative_integer( '14.' ); # FAIL
172 assert_negative_integer( $this [, $name ] )
174 Asserts that the numeric value of $this is defined, an integer, and
175 less than zero.
176 assert_negative_integer( 0 ); # FAIL
178 assert_negative_integer( -14 ); # pass
179 assert_negative_integer( '14.' ); # FAIL
180
182 assert_isa( $this, $type [, $name ] )
183 Asserts that $this is an object of type $type.
184 assert_isa_in( $obj, \@types [, $description] )
186 Assert that the blessed $obj isa one of the types in "\@types".
187 assert_isa_in( $obj, [ 'My::Foo', 'My::Bar' ], 'Must pass either a Foo or Bar object' );
189 assert_empty( $this [, $name ] )
191 $this must be a ref to either a hash or an array. Asserts that that
192 collection contains no elements. Will assert (with its own message,
193 not $name) unless given a hash or array ref. It is OK if $this has
194 been blessed into objecthood, but the semantics of checking an object
195 to see if it does not have keys (for a hashref) or returns 0 in scalar
196 context (for an array ref) may not be what you want.
197 assert_empty( 0 ); # FAIL
199 assert_empty( 'foo' ); # FAIL
200 assert_empty( undef ); # FAIL
201 assert_empty( {} ); # pass
202 assert_empty( [] ); # pass
203 assert_empty( {foo=>1} );# FAIL
204 assert_empty( [1,2,3] ); # FAIL
205 assert_nonempty( $this [, $name ] )
207 $this must be a ref to either a hash or an array. Asserts that that
208 collection contains at least 1 element. Will assert (with its own
209 message, not $name) unless given a hash or array ref. It is OK if
210 $this has been blessed into objecthood, but the semantics of checking
211 an object to see if it has keys (for a hashref) or returns >0 in scalar
212 context (for an array ref) may not be what you want.
213 assert_nonempty( 0 ); # FAIL
215 assert_nonempty( 'foo' ); # FAIL
216 assert_nonempty( undef ); # FAIL
217 assert_nonempty( {} ); # FAIL
218 assert_nonempty( [] ); # FAIL
219 assert_nonempty( {foo=>1} );# pass
220 assert_nonempty( [1,2,3] ); # pass
221 assert_nonref( $this [, $name ] )
223 Asserts that $this is not undef and not a reference.
224 assert_hashref( $ref [,$name] )
226 Asserts that $ref is defined, and is a reference to a (possibly empty)
227 hash.
228 NB: This method returns false for objects, even those whose underlying
230 data is a hashref. This is as it should be, under the assumptions that:
231 (a) you shouldn't rely on the underlying data structure of a particular
233 class, and
234 (b) you should use "assert_isa" instead.
236 assert_hashref_nonempty( $ref [,$name] )
238 Asserts that $ref is defined and is a reference to a hash with at least
239 one key/value pair.
240 assert_arrayref( $ref [, $name] )
242 assert_listref( $ref [,$name] )
243 Asserts that $ref is defined, and is a reference to an array, which may
244 or may not be empty.
245 NB: The same caveat about objects whose underlying structure is a hash
247 (see "assert_hashref") applies here; this method returns false even for
248 objects whose underlying structure is an array.
249 "assert_listref" is an alias for "assert_arrayref" and may go away in
251 the future. Use "assert_arrayref" instead.
252 assert_arrayref_nonempty( $ref [, $name] )
254 Asserts that $ref is reference to an array that has at least one
255 element in it.
256 assert_aoh( $ref [, $name ] )
258 Verifies that $array is an arrayref, and that every element is a
259 hashref.
260 The array $array can be an empty arraref and the assertion will pass.
262 assert_coderef( $ref [,$name] )
264 Asserts that $ref is defined, and is a reference to a closure.
265
267 assert_datetime( $date )
268 Asserts that $date is a DateTime object.
269
271 assert_in( $string, \@inlist [,$name] );
272 Asserts that $string matches one of the elements of \@inlist. $string
273 may be undef.
274 \@inlist must be an array reference of non-ref strings. If any element
276 is a reference, the assertion fails.
277 assert_exists( \%hash, $key [,$name] )
279 assert_exists( \%hash, \@keylist [,$name] )
280 Asserts that %hash is indeed a hash, and that $key exists in %hash, or
281 that all of the keys in @keylist exist in %hash.
282 assert_exists( \%custinfo, 'name', 'Customer has a name field' );
284 assert_exists( \%custinfo, [qw( name addr phone )],
286 'Customer has name, address and phone' );
287 assert_lacks( \%hash, $key [,$name] )
289 assert_lacks( \%hash, \@keylist [,$name] )
290 Asserts that %hash is indeed a hash, and that $key does NOT exist in
291 %hash, or that none of the keys in @keylist exist in %hash. The list
292 @keylist cannot be empty.
293 assert_lacks( \%users, 'root', 'Root is not in the user table' );
295 assert_lacks( \%users, [qw( root admin nobody )], 'No bad usernames found' );
297 assert_all_keys_in( \%hash, \@names [, $name ] )
299 Asserts that each key in %hash is in the list of @names.
300 This is used to ensure that there are no extra keys in a given hash.
302 assert_all_keys_in( $obj, [qw( height width depth )], '$obj can only contain height, width and depth keys' );
304 You can pass an empty list of @names.
306 assert_keys_are( \%hash, \@keys [, $name ] )
308 Asserts that the keys for %hash are exactly @keys, no more and no less.
309
311 assert_context_nonvoid( [$name] )
312 Verifies that the function currently being executed has not been called
313 in void context. This is to ensure the calling function is not
314 ignoring the return value of the executing function.
315 Given this function:
317 sub something {
319 ...
320 assert_context_scalar();
322 return $important_value;
324 }
325 These calls to "something" will pass:
327 my $val = something();
329 my @things = something();
330 but this will fail:
332 something();
334 assert_context_scalar( [$name] )
336 Verifies that the function currently being executed has been called in
337 scalar context. This is to ensure the calling function is not ignoring
338 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 This call to "something" will pass:
351 my $val = something();
353 but these will fail:
355 something();
357 my @things = something();
358
360 assert_fail( [$name] )
361 Assertion that always fails. assert_fail($msg) is exactly the same as
362 calling "assert(0,$msg)", but it eliminates that case where you
363 accidentally use assert($msg), which of course never fires.
364
366 Copyright 2005-2023 Andy Lester
367 This program is free software; you can redistribute it and/or modify it
369 under the terms of the Artistic License version 2.0.
370
372 Thanks to Eric A. Zarko, Bob Diss, Pete Krawczyk, David Storrs, Dan
373 Friedman, Allard Hoeve, Thomas L. Shinnick, and Leland Johnson for code
374 and fixes.
375perl v5.36.0 2023-02-13 More(3)