1More(3) User Contributed Perl Documentation More(3)
2
6 Carp::Assert::More - convenience wrappers around Carp::Assert
7
9 Version 1.20
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_arrayref( $ref [, $name] )
206 assert_listref( $ref [,$name] )
207 Asserts that $ref is defined, and is a reference to a (possibly empty)
208 list.
209 NB: The same caveat about objects whose underlying structure is a hash
211 (see "assert_hashref") applies here; this method returns false even for
212 objects whose underlying structure is an array.
213 "assert_listref" is an alias for "assert_arrayref" and may go away in
215 the future. Use "assert_arrayref" instead.
216 assert_aoh( $ref [, $name ] )
218 Verifies that $array is an arrayref, and that every element is a
219 hashref.
220 The array $array can be an empty arraref and the assertion will pass.
222 assert_coderef( $ref [,$name] )
224 Asserts that $ref is defined, and is a reference to a closure.
225
227 assert_datetime( $date )
228 Asserts that $date is a DateTime object.
229
231 assert_in( $string, \@inlist [,$name] );
232 Asserts that $string is defined and matches one of the elements of
233 \@inlist.
234 \@inlist must be an array reference of defined strings.
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.
251 assert_lacks( \%users, 'root', 'Root is not in the user table' );
253 assert_lacks( \%users, [qw( root admin nobody )], 'No bad usernames found' );
255 assert_all_keys_in( \%hash, \@names [, $name ] )
257 Asserts that each key in %hash is in the list of @names.
258 This is used to ensure that there are no extra keys in a given hash.
260 assert_all_keys_in( $obj, [qw( height width depth )], '$obj can only contain height, width and depth keys' );
262
264 assert_fail( [$name] )
265 Assertion that always fails. "assert_fail($msg)" is exactly the same
266 as calling "assert(0,$msg)", but it eliminates that case where you
267 accidentally use "assert($msg)", which of course never fires.
268
270 Copyright 2005-2019 Andy Lester.
271 This program is free software; you can redistribute it and/or modify it
273 under the terms of the Artistic License version 2.0.
274
276 Thanks to Eric A. Zarko, Bob Diss, Pete Krawczyk, David Storrs, Dan
277 Friedman, Allard Hoeve, Thomas L. Shinnick, and Leland Johnson for code
278 and fixes.
279perl v5.32.0 2020-07-28 More(3)