1More(3) User Contributed Perl Documentation More(3)
2
6 Carp::Assert::More - Convenience assertions for common situations
7
9 Version 2.0.1
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_like( $string, qr/regex/ [,$name] )
46 Asserts that $string matches qr/regex/.
47 The assertion fails either the string or the regex are undef.
49 assert_unlike( $string, qr/regex/ [,$name] )
51 Asserts that $string matches qr/regex/.
52 The assertion fails if the regex is undef.
54 assert_defined( $this [, $name] )
56 Asserts that $this is defined.
57 assert_undefined( $this [, $name] )
59 Asserts that $this is not defined.
60 assert_nonblank( $this [, $name] )
62 Asserts that $this is not a reference and is not an empty string.
63
65 assert_numeric( $n [, $name] )
66 Asserts that $n looks like a number, according to
67 "Scalar::Util::looks_like_number". "undef" will always fail.
68 assert_integer( $this [, $name ] )
70 Asserts that $this is an integer, which may be zero or negative.
71 assert_integer( 0 ); # pass
73 assert_integer( 14 ); # pass
74 assert_integer( -14 ); # pass
75 assert_integer( '14.' ); # FAIL
76 assert_nonzero( $this [, $name ] )
78 Asserts that the numeric value of $this is defined and is not zero.
79 assert_nonzero( 0 ); # FAIL
81 assert_nonzero( -14 ); # pass
82 assert_nonzero( '14.' ); # pass
83 assert_positive( $this [, $name ] )
85 Asserts that $this is defined, numeric and greater than zero.
86 assert_positive( 0 ); # FAIL
88 assert_positive( -14 ); # FAIL
89 assert_positive( '14.' ); # pass
90 assert_nonnegative( $this [, $name ] )
92 Asserts that $this is defined, numeric and greater than or equal to
93 zero.
94 assert_nonnegative( 0 ); # pass
96 assert_nonnegative( -14 ); # FAIL
97 assert_nonnegative( '14.' ); # pass
98 assert_nonnegative( 'dog' ); # pass
99 assert_negative( $this [, $name ] )
101 Asserts that the numeric value of $this is defined and less than zero.
102 assert_negative( 0 ); # FAIL
104 assert_negative( -14 ); # pass
105 assert_negative( '14.' ); # FAIL
106 assert_nonzero_integer( $this [, $name ] )
108 Asserts that the numeric value of $this is defined, an integer, and not
109 zero.
110 assert_nonzero_integer( 0 ); # FAIL
112 assert_nonzero_integer( -14 ); # pass
113 assert_nonzero_integer( '14.' ); # FAIL
114 assert_positive_integer( $this [, $name ] )
116 Asserts that the numeric value of $this is defined, an integer and
117 greater than zero.
118 assert_positive_integer( 0 ); # FAIL
120 assert_positive_integer( -14 ); # FAIL
121 assert_positive_integer( '14.' ); # FAIL
122 assert_positive_integer( '14' ); # pass
123 assert_nonnegative_integer( $this [, $name ] )
125 Asserts that the numeric value of $this is defined, an integer, and not
126 less than zero.
127 assert_nonnegative_integer( 0 ); # pass
129 assert_nonnegative_integer( -14 ); # FAIL
130 assert_nonnegative_integer( '14.' ); # FAIL
131 assert_negative_integer( $this [, $name ] )
133 Asserts that the numeric value of $this is defined, an integer, and
134 less than zero.
135 assert_negative_integer( 0 ); # FAIL
137 assert_negative_integer( -14 ); # pass
138 assert_negative_integer( '14.' ); # FAIL
139
141 assert_isa( $this, $type [, $name ] )
142 Asserts that $this is an object of type $type.
143 assert_isa_in( $obj, \@types [, $description] )
145 Assert that the blessed $obj isa one of the types in "\@types".
146 assert_isa_in( $obj, [ 'My::Foo', 'My::Bar' ], 'Must pass either a Foo or Bar object' );
148 assert_empty( $this [, $name ] )
150 $this must be a ref to either a hash or an array. Asserts that that
151 collection contains no elements. Will assert (with its own message,
152 not $name) unless given a hash or array ref. It is OK if $this has
153 been blessed into objecthood, but the semantics of checking an object
154 to see if it does not have keys (for a hashref) or returns 0 in scalar
155 context (for an array ref) may not be what you want.
156 assert_empty( 0 ); # FAIL
158 assert_empty( 'foo' ); # FAIL
159 assert_empty( undef ); # FAIL
160 assert_empty( {} ); # pass
161 assert_empty( [] ); # pass
162 assert_empty( {foo=>1} );# FAIL
163 assert_empty( [1,2,3] ); # FAIL
164 assert_nonempty( $this [, $name ] )
166 $this must be a ref to either a hash or an array. Asserts that that
167 collection contains at least 1 element. Will assert (with its own
168 message, not $name) unless given a hash or array ref. It is OK if
169 $this has been blessed into objecthood, but the semantics of checking
170 an object to see if it has keys (for a hashref) or returns >0 in scalar
171 context (for an array ref) may not be what you want.
172 assert_nonempty( 0 ); # FAIL
174 assert_nonempty( 'foo' ); # FAIL
175 assert_nonempty( undef ); # FAIL
176 assert_nonempty( {} ); # FAIL
177 assert_nonempty( [] ); # FAIL
178 assert_nonempty( {foo=>1} );# pass
179 assert_nonempty( [1,2,3] ); # pass
180 assert_nonref( $this [, $name ] )
182 Asserts that $this is not undef and not a reference.
183 assert_hashref( $ref [,$name] )
185 Asserts that $ref is defined, and is a reference to a (possibly empty)
186 hash.
187 NB: This method returns false for objects, even those whose underlying
189 data is a hashref. This is as it should be, under the assumptions that:
190 (a) you shouldn't rely on the underlying data structure of a particular
192 class, and
193 (b) you should use "assert_isa" instead.
195 assert_hashref_nonempty( $ref [,$name] )
197 Asserts that $ref is defined and is a reference to a hash with at least
198 one key/value pair.
199 assert_arrayref( $ref [, $name] )
201 assert_listref( $ref [,$name] )
202 Asserts that $ref is defined, and is a reference to an array, which may
203 or may not be empty.
204 NB: The same caveat about objects whose underlying structure is a hash
206 (see "assert_hashref") applies here; this method returns false even for
207 objects whose underlying structure is an array.
208 "assert_listref" is an alias for "assert_arrayref" and may go away in
210 the future. Use "assert_arrayref" instead.
211 assert_arrayref_nonempty( $ref [, $name] )
213 Asserts that $ref is reference to an array that has at least one
214 element in it.
215 assert_aoh( $ref [, $name ] )
217 Verifies that $array is an arrayref, and that every element is a
218 hashref.
219 The array $array can be an empty arraref and the assertion will pass.
221 assert_coderef( $ref [,$name] )
223 Asserts that $ref is defined, and is a reference to a closure.
224
226 assert_datetime( $date )
227 Asserts that $date is a DateTime object.
228
230 assert_in( $string, \@inlist [,$name] );
231 Asserts that $string matches one of the elements of \@inlist. $string
232 may be undef.
233 \@inlist must be an array reference of non-ref strings. If any element
235 is a reference, the assertion fails.
236 assert_exists( \%hash, $key [,$name] )
238 assert_exists( \%hash, \@keylist [,$name] )
239 Asserts that %hash is indeed a hash, and that $key exists in %hash, or
240 that all of the keys in @keylist exist in %hash.
241 assert_exists( \%custinfo, 'name', 'Customer has a name field' );
243 assert_exists( \%custinfo, [qw( name addr phone )],
245 'Customer has name, address and phone' );
246 assert_lacks( \%hash, $key [,$name] )
248 assert_lacks( \%hash, \@keylist [,$name] )
249 Asserts that %hash is indeed a hash, and that $key does NOT exist in
250 %hash, or that none of the keys in @keylist exist in %hash. The list
251 @keylist cannot be empty.
252 assert_lacks( \%users, 'root', 'Root is not in the user table' );
254 assert_lacks( \%users, [qw( root admin nobody )], 'No bad usernames found' );
256 assert_all_keys_in( \%hash, \@names [, $name ] )
258 Asserts that each key in %hash is in the list of @names.
259 This is used to ensure that there are no extra keys in a given hash.
261 assert_all_keys_in( $obj, [qw( height width depth )], '$obj can only contain height, width and depth keys' );
263 You can pass an empty list of @names.
265 assert_keys_are( \%hash, \@keys [, $name ] )
267 Asserts that the keys for %hash are exactly @keys, no more and no less.
268
270 assert_context_nonvoid( [$name] )
271 Verifies that the function currently being executed has not been called
272 in void context. This is to ensure the calling function is not
273 ignoring the return value of the executing function.
274 Given this function:
276 sub something {
278 ...
279 assert_context_scalar();
281 return $important_value;
283 }
284 These calls to "something" will pass:
286 my $val = something();
288 my @things = something();
289 but this will fail:
291 something();
293 assert_context_scalar( [$name] )
295 Verifies that the function currently being executed has been called in
296 scalar context. This is to ensure the calling function is not ignoring
297 the return value of the executing function.
298 Given this function:
300 sub something {
302 ...
303 assert_context_scalar();
305 return $important_value;
307 }
308 This call to "something" will pass:
310 my $val = something();
312 but these will fail:
314 something();
316 my @things = something();
317
319 assert_fail( [$name] )
320 Assertion that always fails. "assert_fail($msg)" is exactly the same
321 as calling "assert(0,$msg)", but it eliminates that case where you
322 accidentally use "assert($msg)", which of course never fires.
323
325 Copyright 2005-2021 Andy Lester.
326 This program is free software; you can redistribute it and/or modify it
328 under the terms of the Artistic License version 2.0.
329
331 Thanks to Eric A. Zarko, Bob Diss, Pete Krawczyk, David Storrs, Dan
332 Friedman, Allard Hoeve, Thomas L. Shinnick, and Leland Johnson for code
333 and fixes.
334perl v5.34.0 2021-08-25 More(3)