1Test::LectroTest::GenerUasteorr(C3o)ntributed Perl DocumTeenstta:t:iLoenctroTest::Generator(3)
2
6 Test::LectroTest::Generator - Random value generators and combinators
7
9 version 0.5001
10
12 use Test::LectroTest::Generator qw(:common :combinators);
13 my $int_gen = Int;
15 my $pct_gen = Int( range=>[0,100] );
16 my $flt_gen = Float( range=>[0,1] );
17 my $bln_gen = Bool;
18 my $chr_gen = Char( charset=>"a-z" );
19 my $str_gen = String( charset=>"A-Z0-9", length=>[3,] );
20 my $ary_gen = List( Int(sized=>0) );
21 my $hsh_gen = Hash( $str_gen, $pct_gen );
22 my $uni_gen = Unit( "e" ); # always returns "e"
23 my $elm_gen = Elements("e1", "e2", "e3", "e4");
24 for my $sizing_guidance (1..100) {
26 my $i = $int_gen->generate( $sizing_guidance );
27 print "$i ";
28 }
29 print "\n";
30 # generates single digits
32 my $digit_gen = Elements( 0..9 ); # or Int(range=>[0,9],sized=>0)
33 # generates SSNs like "910-77-2236"
35 my $ssn_gen = Paste( Paste( ($digit_gen) x 3 ),
36 Paste( ($digit_gen) x 2 ),
37 Paste( ($digit_gen) x 4 ),
38 glue => "-" );
39 # print 10 SSNs
41 print( map {$ssn_gen->generate($_)."\n"} 1..10 );
42 my $english_dist_vowel_gen =
44 Frequency( [8.167,Unit("a")], [12.702,Unit("e")],
45 [6.996,Unit("i")], [ 7.507,Unit("o")],
46 [2.758,Unit("u")] );
47 # Source: http://www.csm.astate.edu/~rossa/datasec/frequency.html
48
50 This module provides random value generators for common data types and
51 provides an interface and tools for creating your own generators. It
52 also provides generator combinators that can be used to create more-
53 complex generators by combining simple ones.
54 A generator is an object having a method "generate", which takes a
56 single argument, size and returns a new random value. The generated
57 value is always a scalar. Generators that produce data structures
58 return references to them.
59 Sizing guidance
61 The "generate" method interprets its size argument as guidance about
62 the complexity of the value it should create. Typically, smaller size
63 values result in smaller generated numbers and shorter generated
64 strings and lists. Some generators, for which sizing doesn't make
65 sense, ignore sizing guidance altogether; those that do use sizing
66 guidance can be told to ignore it via the sized modifier.
67 The purpose of sizing is to allow LectroTest to generate simple values
69 at first and then, as testing progresses, to slowly ramp up the
70 complexity. In this way, counterexamples for obvious problems will be
71 easier for you to understand.
72 Generators
74 The following functions create fully-formed generators, ready to use.
75 These functions are exported into your code's namespace if you ask for
76 ":generators" or ":all" when you "use" this module.
77 Each generator has a "generate" method that you can call to extract a
79 new, random value from the generator.
80 Int
82 my $gen = Int( range=>[0,9], sized=>0 );
83 Creates a generator for integer values, by default in the range
85 [-32768,32767], inclusive, but this can be changed via the optional
86 range modifier.
87 Int( range=>[low, high] )
89 Causes the generated values to be constrained to the range
90 [low, high], inclusive. By default, the range is [-32768,
91 32767].
92 Note: If your range is empty (i.e., low > high), LectroTest
94 will complain.
95 Note: If zero is not within the range you provide, sizing makes
97 no sense because the intersection of your range and the sizing
98 range can be empty, and thus you must turn off sizing with
99 "sized=>0". If you forget, LectroTest will complain.
100 Int( sized=>bool )
102 If true (the default), constrains the absolute value of the
103 generated integers to the sizing guidance provided to the
104 "generate" method. Otherwise, the generated values are
105 constrained only by the range.
106 Float
108 my $gen = Float( range=>[-2.0,2.0], sized=>1 );
109 Creates a generator for floating-point values, by default in the
111 range [-32768.0,32768.0), but this can be changed via the optional
112 range modifier. By default Float generators are sized.
113 Float( range=>[low, high] )
115 Causes the generated values to be constrained to the range
116 [low, high). By default, the range is [-32768.0,32768.0).
117 (Note that the high value itself can never be generated, but
118 values infinitesimally close to it can.)
119 Note: If your range is empty (i.e., low > high), LectroTest
121 will complain.
122 Note: If zero is not within the range you provide, sizing makes
124 no sense because the intersection of your range and the sizing
125 range can be empty, and thus you must turn off sizing with
126 "sized=>0". If you forget, LectroTest will complain.
127 Float( sized=>bool )
129 If true (the default), constrains the absolute value of the
130 generated values to the sizing guidance provided to the
131 "generate" method. Otherwise, the generated values are
132 constrained only by the range.
133 Bool
135 my $gen = Bool;
136 Creates a generator for boolean values: 0 for false, 1 for true.
138 The generator ignores sizing guidance.
139 Char
141 my $gen = Char( charset=>"A-Za-z0-9_" );
142 Creates a generator for characters. By default the characters are
144 in the ASCII range [0,127], inclusive, but this behavior can be
145 changed with the charset modifier:
146 Char( charset=>cset )
148 Characters will be drawn from the character set given by the
149 character-set specification cset. The syntax of cset is
150 similar the Perl "tr" built-in and is a string comprised of
151 characters and character ranges:
152 c Adds the character c to the set.
154 c-d Adds the characters in the range c through d (inclusive) to
156 the set. Note: If c is lexicographically greater than d,
157 the range is empty, and no characters will be added to the
158 set.
159 Examples:
161 charset=>"abcdwxyz"
163 The characters "a", "b", "c", "d", "w", "x", "y", and "z"
164 are in the set.
165 charset=>"a-dx-z"
167 Shorter version of the previous example.
168 charset=>"\x00-\x7f"
170 The ASCII character set.
171 charset=>"-_A-Za-z0-9"
173 The character set contains "-", "_", upper- and lower-case
174 ASCII letters, and the digits 0-9. Notice that the dash
175 must occur first so that it is not misinterpreted as
176 denoting a range of characters.
177 List(elemgen)
179 my $gen = List( Bool, length=>[1,10] );
180 Creates a generator for lists (which are returned as array refs).
182 The elements of the lists are generated by the generator given as
183 elemgen. The lengths of the generated lists are constrained by
184 sizing guidance at the time of generation. You can override the
185 default sizing behavior using the optional length modifier:
186 When the list generator calls the element generator, it divides the
188 sizing guidance by the length of the list. For example, if the
189 list being generated will have 7 elements, when the list generator
190 calls the element generator to generate each element, it will scale
191 the sizing guidance by 1/7. In this way the sizing guidance
192 provides a rough constraint on the total number of elements
193 produced, regardless of the depth of the list structure being
194 generated.
195 List( ..., length=>N )
197 Generated lists are exactly length N.
198 List( ..., length=>[M,] )
200 Generated lists are at least length M. (Maximum length is
201 constrained by sizing factor.)
202 List( ..., length=>[M,N] )
204 Generated lists are of length between M and N, inclusive.
205 Sizing guidance is ignored.
206 Advanced Note: If more than one elemgen is given, they will be used
208 in turn to create successive elements. In this case, the length of
209 the list will be multiplied by the number of generators given. For
210 example, providing two generators will create double-length lists.
211 Hash(keygen, valgen)
213 my $gen = Hash( String( charset=>"A-Z", length=>3 ),
214 Float( range=>[0.0, 100.0] );
215 Creates a generator for hashes (which are returned as hash refs).
217 The keys of the hash are generated by the generator given as
218 keygen, and the values are generated by the generator valgen.
219 The Hash generator takes an optional length modifier that specifies
221 the desired hash length (= number of keys):
222 Hash( ..., length=>length-spec )
224 Specifies the desired length of the generated hashes, using the
225 same length-spec syntax as for the List generator. Note that
226 the generated hashes may be smaller than expected because of
227 key collision.
228 String
230 my $gen = String( length=>[3,], charset=>"A-Z" );
231 Creates a generator for strings. By default the strings will be
233 drawn from the ASCII character set (0 through 127) and be of length
234 constrained by the sizing factor. Both defaults can be changed
235 using modifiers:
236 String( charset=>cset )
238 Characters will be drawn from the character set given by the
239 character-set specification cset. The syntax of cset is
240 similar the Perl "tr" operator and is a string comprised of
241 characters and character ranges. See Char for a full
242 description.
243 String( length=>length-spec )
245 Specifies the desired length of generated strings, using the
246 same length-spec syntax as for the List generator.
247 Elements(e1, e2, ...)
249 my $gen = Elements( "alpha", "beta", "gamma" );
250 Creates a generator that chooses among the given elements e1, e2,
252 ... with equal probability. Each call to the "generate" method
253 will return one of the element values. Sizing guidance has no
254 effect on this generator.
255 Note: This generator builder does not accept modifiers. If you
257 pass any, they will be interpreted as elements to be added to the
258 pool from which the generator randomly selects, which is probably
259 not what you want.
260 Unit(e)
262 my $gen = Unit( "alpha" );
263 Creates a generator that always returns the value e. Not too
265 useful on its own but can be handy as a building block for
266 combinators to chew on. Naturally, sizing guidance has no effect
267 on this generator.
268 Note: This generator builder does not accept modifiers.
270 Generator combinators
272 The following combinators allow you to build more complicated
273 generators from simpler ones. These combinators are exported into your
274 code's namespace if you ask for ":combinators" or ":all" when you "use"
275 this module.
276 Paste(gens..., glue=>str)
278 my $gen = Paste( (String(charset=>"0-9",length=>4)) x 4,
279 glue => " " );
280 # gens credit-card numbers like "4592 9459 9023 1369"
281 my $lgen = Paste( List( String(charset=>"0-9",length=>4)
283 , length=>4 ), glue => " " );
284 # another way of doing the same
285 Creates a combined generator that generates values by joining the
287 values generated by each of the supplied sub-generators gens.
288 (Generated list values will have their elements "flattened" into
289 the rest of the generated results before joining.) The resulting
290 string is returned.
291 The values are joined using the given glue string str. If no glue
293 modifier is provided, the default glue is the empty string.
294 The sizing guidance given to the combined generator will be passed
296 unchanged to each of the sub-generators.
297 OneOf(gens...)
299 my $gen = OneOf( Unit(0), List(Int,length=>3) );
300 # generates scalar 0 or a 3-element list of integers
301 Creates a combined generator that generates each value by selecting
303 at random (with equal probability) one of the sub-generators in
304 gens and using that generator to generate the output value.
305 The sizing guidance given to the combined generator will be passed
307 unchanged to the selected sub-generator.
308 Note: This combinator does not accept modifiers.
310 Frequency([freq1, gen1], [freq2, gen2], ...)
312 my $gen = Frequency( [50, Unit("common" )],
313 [35, Unit("less common")],
314 [15, Unit("uncommon" )] );
315 # generates one of "common", "less common", or
316 # "uncommon" with respective probabilities
317 # 50%, 35%, and 15%.
318 Creates a combined generator that generates each value by selecting
320 at random one of the generators gen1 or gen2 or ... and using that
321 generator to generate the output value. Each generator is selected
322 with probability proportional to its associated frequency. (If all
323 of the given frequencies are the same, the Frequency combinator
324 effectively becomes OneOf.) The frequencies can be any non-
325 negative numerical values you want and will be normalized to a
326 0-to-1 scale internally. At least one frequency must be greater
327 than zero.
328 The sizing guidance given to the combined generator will be passed
330 unchanged to the selected sub-generator.
331 Note: This combinator does not accept modifiers.
333 Each(gens...)
335 my $gen = Each( Unit(1), Unit("X") );
336 # always generates [ 1, "X" ]
337 Creates a generator that returns a list (array ref) whose
339 successive elements are the successive values generated by the
340 given generators gens.
341 The sizing guidance given to the combined generator will be passed
343 unchanged to each sub-generator.
344 Note: This combinator does not accept modifiers.
346 (Note for technical buffs: Each(...) is exactly equivalent to
348 "List(..., length=>1)").
349 Apply(fn, gens...)
351 my $gen = Apply( sub { $_[0] x $_[1] }
352 , Unit("X"), Unit(4) );
353 # always generates "XXXX"
354 Creates a generator that applies the given function fn to arguments
356 generated from each of the given sub-generators gens and returns
357 the resulting value. Each sub-generator contributes one value, and
358 the values are passed to fn as arguments in the same order as the
359 sub-generators were given to Apply.
360 The sizing guidance given to the combined generator will be passed
362 unchanged to each sub-generator.
363 Note: The function fn is always evaluated in scalar context. If
365 you need to generate an array, return it as an array reference.
366 Note: This combinator does not accept modifiers.
368 Map(fn, gens...)
370 my $gen = Map( sub { "X" x $_[0] }
371 , Unit(4), Unit(3), Unit(0) );
372 # always generates [ "XXXX", "XXX", "" ]
373 Creates a generator that applies the given function fn to the
375 values generated by the given generators gen one at a time and
376 returns a list (array ref) whose elements are each of the
377 successive results.
378 The sizing guidance given to the combined generator will be passed
380 unchanged to each sub-generator.
381 Note: The function fn is always evaluated in scalar context. If
383 you need to generate an array, return it as an array reference.
384 Note: This combinator does not accept modifiers.
386 Concat(gens...)
388 my $gen = Concat( List( Unit(1), length=>3 )
389 , List( Unit("x"), length=>1 ) );
390 # always generates [1, 1, 1, "x"]
391 Creates a generator that concatenates the values generated by each
393 of its sub-generators, resulting in a list (which is returned as a
394 array reference). The values returned by the sub-generators are
395 expected to be lists (array refs). If a sub-generator returns a
396 scalar value, it will be treated like a single-element list that
397 contains the value.
398 The sizing guidance given to the combined generator will be passed
400 unchanged to each sub-generator.
401 Note: If a sub-generator returns something other than a list or
403 scalar, you will get a run-time error.
404 Note: This combinator does not accept modifiers.
406 Flatten(gens...)
408 my $gen = Flatten( Unit( [[[[[[ 1 ]]]]]] ) );
409 # generates [1]
410 Flatten is just like Concat except that it recursively flattens any
412 sublists generated by the generators gen and then concatenates them
413 to generate a final a list of depth one, regardless of the depth of
414 any sublists.
415 The sizing guidance given to the combined generator will be passed
417 unchanged to each sub-generator.
418 Note: If a sub-generator returns something other than a list or
420 scalar, you will get a run-time error.
421 Note: This combinator does not accept modifiers.
423 ConcatMap(fn, gens)
425 sub take_odds { my $x = shift;
426 $x % 2 ? [$x] : [] }
427 my $gen = ConcatMap( \&take_odds
428 , Unit(1), Unit(2), Unit(3) );
429 # generates [1, 3]
430 Creates a generator that applies the function fn to each of the
432 values generated by the given generators gen in turn, and then
433 concatenates the results.
434 The sizing guidance given to the combined generator will be passed
436 unchanged to each sub-generator.
437 Note: The function fn is always evaluated in scalar context. If
439 you need to generate an array, return it as an array reference.
440 Note: If a sub-generator returns something other than a list or
442 scalar, you will get a run-time error.
443 Note: This combinator does not accept modifiers.
445 FlattenMap(fn, gens)
447 my $gen = FlattenMap( sub { [ ($_[0]) x 3 ] }
448 , Unit([1]), Unit([[2]]) );
449 # generates [1, 1, 1, 2, 2, 2]
450 Creates a generator that applies the function fn to each of the
452 values generated by the given generators gen in turn, and then
453 flattens and concatenates the results.
454 The sizing guidance given to the combined generator will be passed
456 unchanged to each sub-generator.
457 Note: The function fn is always evaluated in scalar context. If
459 you need to generate an array, return it as an array reference.
460 Note: If a sub-generator returns something other than a list or
462 scalar, you will get a run-time error.
463 Note: This combinator does not accept modifiers.
465 Sized(fn, gen)
467 my $gen = Sized { 2 * $_[0] } List(Int);
468 # ^ magnify sizing guidance by factor of two
469 my $gen2 = Sized { 10 } Int;
470 # ^ use constant guidance of 10
471 Creates a generator that adjusts sizing guidance by passing it
473 through the function fn. Then it calls the generator gen with the
474 adjusted guidance and returns the result.
475 Note: This combinator does not accept modifiers.
477 Rolling your own generators
479 You can create your own generators by creating any object that has a
480 "generate" method. Your method should accept as its first argument
481 sizing guidance size and, if it makes sense, adjust the complexity of
482 the values it generates accordingly.
483 The easiest way to create a generator is by using the magic function
485 "Gen". It promotes a block of code into a generator. For example,
486 here's a home-brew generator for times in ctime(3) format that is built
487 on top of an Int generator:
488 use Test::LectroTest::Generator qw( :common Gen );
490 my $time_gen = Int(range=>[0, 2_147_483_647], sized=>0);
492 my $ctime_gen = Gen {
493 scalar localtime $time_gen->generate( @_ );
494 };
495 print($ctime_gen->generate($_), "\n") for 1..5;
497 # Fri Jun 2 18:13:21 1978
498 # Thu Mar 28 00:55:51 1974
499 # Wed Mar 26 06:41:09 2025
500 # Sun Sep 11 15:39:44 2016
501 # Fri Dec 26 00:39:31 1975
502 Alternatively, we could build the generator using the Apply combinator:
504 my $ctime_gen2 = Apply { localtime $_[0] } $time_gen;
506 Note: "Gen" is not exported into your code's namespace by default. If
508 you want to use it, you must import it by name or import ":all" when
509 you use this module.
510
512 Here are some examples to consider.
513 Simple examples
515 use strict;
516 use Test::LectroTest::Generator qw(:common);
517 show("Ints (sized by default)", Int);
519 show("Floats (sized by default)", Float);
521 show("Percentages (unsized)",
523 Int( range=>[0,100], sized=>0 ));
524 show("Lists (sized by default) of Ints (unsized) in [0,10]",
526 List( Int( sized=>0, range=>[0,10] ) ));
527 show("Uppercase-alpha identifiers at least 3 chars long",
529 String( length=>[3,], charset=>"A-Z" ));
530 show("Hashes (sized by default) of form AAA=>Digit",
533 Hash( String( length=>3, charset=>"A-Z" ),
534 Int( sized=>0, range=>[0,9] ) ));
535 sub show {
537 print "\n", shift(), "\n";
538 my ($gen) = @_;
539 for (1..10) {
540 my $val = $gen->generate($_);
541 printf "Size %2d: ", $_;
542 if (ref $val eq "HASH") {
543 my @pairs = map {"$_=>$val->{$_}"} keys %$val;
544 print "{ @pairs }";
545 }
546 elsif (ref $val eq "ARRAY") {
547 print "[ @$val ]"
548 }
549 else {
550 print $val;
551 }
552 print "\n";
553 }
554 }
555 Advanced examples
557 For these examples we use "Data::Dumper" to inspect the data structures
558 we generate. Also, we import not only the common generator
559 constructors (like Int) but also the generic Gen constructor, which
560 lets us build generators out of blocks on the fly.
561 use Data::Dumper;
563 use Test::LectroTest::Generator qw(:common Gen);
564 First, here's a recipe for building a list of lists of integers:
566 my $loloi_gen = List( List( Int(sized=>0) ) );
568 print Dumper($loloi_gen->generate(10));
569 You may want to run the example several times to get a feel for the
571 distribution of the generated output.
572 Now, a more complicated example. Here we build sized trees of random
574 depth using a recursive set of generators.
575 my $tree_gen = do {
577 my $density = 0.5;
578 my $leaf_gen = Int( sized=>0 );
579 my $tree_helper = \1;
580 my $branch_gen = List( Gen { $$tree_helper->generate(@_) } );
581 $tree_helper = \Gen {
582 my ($size) = @_;
583 return rand($size) < $density
584 ? $leaf_gen->generate($size)
585 : $branch_gen->generate($size + 1);
586 };
587 $$tree_helper;
588 };
589 print Dumper($tree_gen->generate(30));
591 We define a tree as either a leaf or a branch, and we randomly decide
593 between the two at each node in the growing tree. Leaves are just
594 integers and become more likely when the sizing guidance diminishes
595 (which happens as we go deeper). The code uses $density as a control
596 knob for leaf density. (Try re-running the above code after changing
597 the value of $density. Try 0, 1, and 2.) Branches, on the other hand,
598 are lists of trees. Because branches generate trees, and trees
599 generate branches, we use a reference trick to set up the mutually
600 recursive relationship. This we encapsulate within a do block for
601 tidiness.
602
604 Test::LectroTest gives a quick overview of automatic, specification-
605 based testing with LectroTest.
606
608 Tom Moertel (tom@moertel.com)
609
611 The LectroTest project was inspired by Haskell's QuickCheck module by
612 Koen Claessen and John Hughes:
613 http://www.cs.chalmers.se/~rjmh/QuickCheck/.
614
616 Copyright (c) 2004-13 by Thomas G Moertel. All rights reserved.
617 This program is free software; you can redistribute it and/or modify it
619 under the same terms as Perl itself.
620perl v5.36.0 2023-01-20 Test::LectroTest::Generator(3)