1More(3) User Contributed Perl Documentation More(3)
2
3
4
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
14 use Carp::Assert::More;
15
16 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
23 Everything in here is effectively syntactic sugar. There's no
24 technical difference between calling one of these functions:
25
26 assert_datetime( $foo );
27 assert_isa( $foo, 'DateTime' );
28
29 that are provided by Carp::Assert::More and calling these assertions
30 from Carp::Assert
31
32 assert( defined $foo );
33 assert( ref($foo) eq 'DateTime' );
34
35 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
42 assert_isnt( $string, $unmatch [,$name] )
43 Asserts that $string does NOT match $unmatch.
44
45 assert_cmp( $x, $op, $y [,$name] )
46 Asserts that the relation "$x $op $y" is true. For example:
47
48 assert_cmp( $divisor, '!=', 0, 'Divisor must not be zero' );
49
50 is the same as:
51
52 assert( $divisor != 0, 'Divisor must not be zero' );
53
54 but with better error reporting.
55
56 The following operators are supported:
57
58 • == numeric equal
59
60 • != numeric not equal
61
62 • > numeric greater than
63
64 • >= numeric greater than or equal
65
66 • < numeric less than
67
68 • <= numeric less than or equal
69
70 • lt string less than
71
72 • le string less than or equal
73
74 • gt string less than
75
76 • ge string less than or equal
77
78 There is no support for "eq" or "ne" because those already have
79 "assert_is" and "assert_isnt", respectively.
80
81 If either $x or $y is undef, the assertion will fail.
82
83 If the operator is numeric, and $x or $y are not numbers, the assertion
84 will fail.
85
86 assert_like( $string, qr/regex/ [,$name] )
87 Asserts that $string matches qr/regex/.
88
89 The assertion fails either the string or the regex are undef.
90
91 assert_unlike( $string, qr/regex/ [,$name] )
92 Asserts that $string matches qr/regex/.
93
94 The assertion fails if the regex is undef.
95
96 assert_defined( $this [, $name] )
97 Asserts that $this is defined.
98
99 assert_undefined( $this [, $name] )
100 Asserts that $this is not defined.
101
102 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
110 assert_integer( $this [, $name ] )
111 Asserts that $this is an integer, which may be zero or negative.
112
113 assert_integer( 0 ); # pass
114 assert_integer( 14 ); # pass
115 assert_integer( -14 ); # pass
116 assert_integer( '14.' ); # FAIL
117
118 assert_nonzero( $this [, $name ] )
119 Asserts that the numeric value of $this is defined and is not zero.
120
121 assert_nonzero( 0 ); # FAIL
122 assert_nonzero( -14 ); # pass
123 assert_nonzero( '14.' ); # pass
124
125 assert_positive( $this [, $name ] )
126 Asserts that $this is defined, numeric and greater than zero.
127
128 assert_positive( 0 ); # FAIL
129 assert_positive( -14 ); # FAIL
130 assert_positive( '14.' ); # pass
131
132 assert_nonnegative( $this [, $name ] )
133 Asserts that $this is defined, numeric and greater than or equal to
134 zero.
135
136 assert_nonnegative( 0 ); # pass
137 assert_nonnegative( -14 ); # FAIL
138 assert_nonnegative( '14.' ); # pass
139 assert_nonnegative( 'dog' ); # pass
140
141 assert_negative( $this [, $name ] )
142 Asserts that the numeric value of $this is defined and less than zero.
143
144 assert_negative( 0 ); # FAIL
145 assert_negative( -14 ); # pass
146 assert_negative( '14.' ); # FAIL
147
148 assert_nonzero_integer( $this [, $name ] )
149 Asserts that the numeric value of $this is defined, an integer, and not
150 zero.
151
152 assert_nonzero_integer( 0 ); # FAIL
153 assert_nonzero_integer( -14 ); # pass
154 assert_nonzero_integer( '14.' ); # FAIL
155
156 assert_positive_integer( $this [, $name ] )
157 Asserts that the numeric value of $this is defined, an integer and
158 greater than zero.
159
160 assert_positive_integer( 0 ); # FAIL
161 assert_positive_integer( -14 ); # FAIL
162 assert_positive_integer( '14.' ); # FAIL
163 assert_positive_integer( '14' ); # pass
164
165 assert_nonnegative_integer( $this [, $name ] )
166 Asserts that the numeric value of $this is defined, an integer, and not
167 less than zero.
168
169 assert_nonnegative_integer( 0 ); # pass
170 assert_nonnegative_integer( -14 ); # FAIL
171 assert_nonnegative_integer( '14.' ); # FAIL
172
173 assert_negative_integer( $this [, $name ] )
174 Asserts that the numeric value of $this is defined, an integer, and
175 less than zero.
176
177 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
185 assert_isa_in( $obj, \@types [, $description] )
186 Assert that the blessed $obj isa one of the types in "\@types".
187
188 assert_isa_in( $obj, [ 'My::Foo', 'My::Bar' ], 'Must pass either a Foo or Bar object' );
189
190 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
198 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
206 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
214 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
222 assert_nonref( $this [, $name ] )
223 Asserts that $this is not undef and not a reference.
224
225 assert_hashref( $ref [,$name] )
226 Asserts that $ref is defined, and is a reference to a (possibly empty)
227 hash.
228
229 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
232 (a) you shouldn't rely on the underlying data structure of a particular
233 class, and
234
235 (b) you should use "assert_isa" instead.
236
237 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
241 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
246 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
250 "assert_listref" is an alias for "assert_arrayref" and may go away in
251 the future. Use "assert_arrayref" instead.
252
253 assert_arrayref_nonempty( $ref [, $name] )
254 Asserts that $ref is reference to an array that has at least one
255 element in it.
256
257 assert_aoh( $ref [, $name ] )
258 Verifies that $array is an arrayref, and that every element is a
259 hashref.
260
261 The array $array can be an empty arraref and the assertion will pass.
262
263 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
275 \@inlist must be an array reference of non-ref strings. If any element
276 is a reference, the assertion fails.
277
278 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
283 assert_exists( \%custinfo, 'name', 'Customer has a name field' );
284
285 assert_exists( \%custinfo, [qw( name addr phone )],
286 'Customer has name, address and phone' );
287
288 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
294 assert_lacks( \%users, 'root', 'Root is not in the user table' );
295
296 assert_lacks( \%users, [qw( root admin nobody )], 'No bad usernames found' );
297
298 assert_all_keys_in( \%hash, \@names [, $name ] )
299 Asserts that each key in %hash is in the list of @names.
300
301 This is used to ensure that there are no extra keys in a given hash.
302
303 assert_all_keys_in( $obj, [qw( height width depth )], '$obj can only contain height, width and depth keys' );
304
305 You can pass an empty list of @names.
306
307 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
316 Given this function:
317
318 sub something {
319 ...
320
321 assert_context_scalar();
322
323 return $important_value;
324 }
325
326 These calls to "something" will pass:
327
328 my $val = something();
329 my @things = something();
330
331 but this will fail:
332
333 something();
334
335 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
340 Given this function:
341
342 sub something {
343 ...
344
345 assert_context_scalar();
346
347 return $important_value;
348 }
349
350 This call to "something" will pass:
351
352 my $val = something();
353
354 but these will fail:
355
356 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
368 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.
375
376
377
378perl v5.36.0 2023-02-13 More(3)