1Test::LectroTest(3)   User Contributed Perl Documentation  Test::LectroTest(3)
2
3
4

NAME

6       Test::LectroTest - Easy, automatic, specification-based tests
7

VERSION

9       version 0.5001
10

SYNOPSIS

12           #!/usr/bin/perl -w
13
14           use MyModule;  # contains code we want to test
15           use Test::LectroTest;
16
17           Property {
18               ##[ x <- Int, y <- Int ]##
19               MyModule::my_function( $x, $y ) >= 0;
20           }, name => "my_function output is non-negative" ;
21
22           Property { ... }, name => "yet another property" ;
23
24           # more properties to check here
25

DESCRIPTION

27       This module provides a simple (yet full featured) interface to
28       LectroTest, an automated, specification-based testing system for Perl.
29       To use it, declare properties that specify the expected behavior of
30       your software.  LectroTest then checks your software to see whether
31       those properties hold.
32
33       Declare properties using the "Property" function, which takes a block
34       of code and promotes it to a Test::LectroTest::Property:
35
36           Property {
37               ##[ x <- Int, y <- Int ]##
38               MyModule::my_function( $x, $y ) >= 0;
39           }, name => "my_function output is non-negative" ;
40
41       The first part of the block must contain a generator-binding
42       declaration.  For example:
43
44               ##[  x <- Int, y <- Int  ]##
45
46       (Note the special bracketing, which is required.)  This particular
47       binding says, "For all integers x and y."  (By the way, you aren't
48       limited to integers.  LectroTest also gives you booleans, strings,
49       lists, hashes, and more, and it lets you define your own generator
50       types.  See Test::LectroTest::Generator for more.)
51
52       The second part of the block is simply a snippet of code that makes use
53       of the variables we bound earlier to test whether a property holds for
54       the piece of software we are testing:
55
56               MyModule::my_function( $x, $y ) >= 0;
57
58       In this case, it asserts that "MyModule::my_function($x,$y)" returns a
59       non-negative result.  (Yes, $x and $y refer to the same x and y that we
60       bound to the generators earlier.  LectroTest automagically loads these
61       lexically bound Perl variables with values behind the scenes.)
62
63       Note: If you want to use testing assertions like "ok" from Test::Simple
64       or "is", "like", or "cmp_ok" from Test::More (and the related family of
65       Test::Builder-based testing modules), see Test::LectroTest::Compat,
66       which lets you mix and match LectroTest with these modules.
67
68       Finally, we give the whole Property a name, in this case "my_function
69       output is non-negative."  It's a good idea to use a meaningful name
70       because LectroTest refers to properties by name in its output.
71
72       Let's take a look at the finished property specification:
73
74           Property {
75               ##[ x <- Int, y <- Int ]##
76               MyModule::my_function( $x, $y ) >= 0;
77           }, name => "my_function output is non-negative" ;
78
79       It says, "For all integers x and y, we assert that my_function's output
80       is non-negative."
81
82       To check whether this property holds, simply put it in a Perl program
83       that uses the Test::LectroTest module.  (See the "SYNOPSIS" for an
84       example.)  When you run the program, LectroTest will load the property
85       (and any others in the file) and check it by running random trials
86       against the software you're testing.
87
88       Note: If you want to place LectroTest property checks into a test plan
89       managed by Test::Builder-based modules such as Test::Simple or
90       Test::More, see Test::LectroTest::Compat.
91
92       If LectroTest is able to "break" your software during the property
93       check, it will emit a counterexample to your property's assertions and
94       stop.  You can plug the counterexample back into your software to debug
95       the problem.  (You might also want to add the counterexample to a list
96       of regression tests.)
97
98       A successful LectroTest looks like this:
99
100         1..1
101         ok 1 - 'my_function output is non-negative' (1000 attempts)
102
103       On the other hand, if you're not so lucky:
104
105         1..1
106         not ok 1 - 'my_function output is non-negative' falsified \
107             in 324 attempts
108         # Counterexample:
109         # $x = -34
110         # $y = 0
111

EXIT CODE

113       The exit code returned by running a suite of property checks is the
114       number of failed checks.  The code is 0 if all properties passed their
115       checks or N if N properties failed. (If more than 254 properties
116       failed, the exit code will be 254.)
117

ADJUSTING THE TESTING PARAMETERS

119       There is one testing parameter (among others) that you might wish to
120       change from time to time: the number of trials to run for each property
121       checked.  By default it is 1,000.  If you want to try more or fewer
122       trials, pass the "trials=>"N flag:
123
124         use Test::LectroTest trials => 10_000;
125

TESTING FOR REGRESSIONS AND CORNER CASES

127       LectroTest can record failure-causing test cases to a file, and it can
128       play those test cases back as part of its normal testing strategy.  The
129       easiest way to take advantage of this feature is to set the regressions
130       parameter when you "use" this module:
131
132           use Test::LectroTest
133               regressions => "regressions.txt";
134
135       This tells LectroTest to use the file "regressions.txt" for both
136       recording and playing back failures.  If you want to record and play
137       back from separate files, or want only to record or play back, use the
138       record_failures and/or playback_failures options:
139
140           use Test::LectroTest
141               playback_failures => "regression_suite_for_my_module.txt",
142               record_failures   => "failures_in_the_field.txt";
143
144       See Test::LectroTest::RegressionTesting for more.
145

CAVEATS

147       When you use this module, it imports all of the generator-building
148       functions from Test::LectroTest::Generator into the your code's
149       namespace.  This is almost always what you want, but I figured I ought
150       to say something about it here to reduce the possibility of surprise.
151
152       A Property specification must appear in the first column, i.e., without
153       any indentation, in order for it to be automatically loaded and
154       checked.  If this poses a problem, let me know, and this restriction
155       can be lifted.
156

SEE ALSO

158       For a gentle introduction to LectroTest, see
159       Test::LectroTest::Tutorial.  Also, the slides from my LectroTest talk
160       for the Pittsburgh Perl Mongers make for a great introduction.
161       Download a copy from the LectroTest home (see below).
162
163       Test::LectroTest::RegressionTesting explains how to test for
164       regressions and corner cases using LectroTest.
165
166       Test::LectroTest::Compat lets you mix LectroTest with the popular
167       family of Test::Builder-based modules such as Test::Simple and
168       Test::More.
169
170       Test::LectroTest::Property explains in detail what you can put inside
171       of your property specifications.
172
173       Test::LectroTest::Generator describes the many generators and generator
174       combinators that you can use to define the test or condition space that
175       you want LectroTest to search for bugs.
176
177       Test::LectroTest::TestRunner describes the objects that check your
178       properties and tells you how to turn their control knobs.  You'll want
179       to look here if you're interested in customizing the testing procedure.
180

LECTROTEST HOME

182       The LectroTest home is http://community.moertel.com/LectroTest.  There
183       you will find more documentation, presentations, mailing-list archives,
184       a wiki, and other helpful LectroTest-related resources.  It's also the
185       best place to ask questions.
186

AUTHOR

188       Tom Moertel (tom@moertel.com)
189

INSPIRATION

191       The LectroTest project was inspired by Haskell's QuickCheck module by
192       Koen Claessen and John Hughes:
193       http://www.cs.chalmers.se/~rjmh/QuickCheck/.
194
196       Copyright (c) 2004-05 by Thomas G Moertel.  All rights reserved.
197
198       This program is free software; you can redistribute it and/or modify it
199       under the same terms as Perl itself.
200
201
202
203perl v5.34.0                      2021-07-23               Test::LectroTest(3)
Impressum