NAME

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

SYNOPSIS

#!/usr/bin/perl -w

use MyModule;  # contains code we want to test
use Test::LectroTest;

Property {
    ##[ x <- Int, y <- Int ]##
    MyModule::my_function( $x, $y ) >= 0;
}, name => "my_function output is non-negative" ;

Property { ... }, name => "yet another property" ;

# more properties to check here

DESCRIPTION

This module provides a simple (yet full featured) interface to LectroTest, automated, specification-based testing system for Perl. To use it, you declare properties that specify the expected behavior of your software. LectroTest then checks to see whether those properties hold.

You declare properties using the Property function, which takes a block and promotes it to a LectroTest::Property:

Property {
    ##[ x <- Int, y <- Int ]##
    MyModule::my_function( $x, $y ) >= 0;
}, name => "my_function output is non-negative" ;

The first part of the block must contain a generator-binding declaration. For example:

##[  x <- Int, y <- Int  ]##

(Note the special bracketing, which must be present.) This particular binding says, "For all integers x and y." (See LectroTest::Generator to see the whopping passel of generators that are at your disposal.)

The second part of the block is just a bit of code that makes use of the variables we bound earlier to test whether a property holds for the piece of software we are testing:

MyModule::my_function( $x, $y ) >= 0;

In this case, it asserts that MyModule::my_function($x,$y) returns a non-negative result. (Yes, $x and $y refer to the same x and y that we bound to the generators earlier. LectroTest automagically loads these Perl variables with values behind the scenes.)

Finally, we give the whole Property a name, in this case "my_function output is non-negative." It's a good idea to use a meaningful name because LectroTest refers to properties by name in its output.

Let's take a look at the finished property:

Property {
    ##[ x <- Int, y <- Int ]##
    MyModule::my_function( $x, $y ) >= 0;
}, name => "my_function output is non-negative" ;

It says, "For all integers x and y, we assert that my_function's output is non-negative."

To check whether this property holds, simply put it in a Perl program that uses the Test::LectroTest module. (See the "SYNOPSIS" for an example.) When you run the program, LectroTest will load the property (and any others in the file) and check it by running random trials against the software. If LectroTest "breaks" your software, it will emit a counterexample and stop. You can plug the counterexample back into your software to debug the problem. (You might also want to add the counterexample to a list of regression tests.)

A successful LectroTest looks like this:

1..1
ok 1 - 'my_function output is non-negative' (1000 attempts)

On the other hand, if you're not so lucky:

1..1
not ok 1 - 'my_function output is non-negative' falsified \
    in 324 attempts
# Counterexample:
# $x = -34
# $y = 0

ADJUSTING THE TESTING PARAMETERS

There is one testing parameter that you may wish to change: The number of trials to run against each property checked. By default it is 1,000. If you want to try more or fewer trials, pass the trials=>N flag:

use Test::LectroTest trials => 10_000;

SEE ALSO

For a more in-depth introduction to LectroTest, see LectroTest::Tutorial. For more information on the various parts of LectroTest, see LectroTest::Property, LectroTest::Generator, and LectroTest::TestRunner.

Also, the slides from my LectroTest talk for the Pittsburgh Perl Mongers is a great introduction. Download a copy from the LectroTest home (see below).

LECTROTEST HOME

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

AUTHOR

Tom Moertel (tom@moertel.com)

INSPIRATION

The LectroTest project was inspired by Haskell's fabulous QuickCheck module by Koen Claessen and John Hughes: http://www.cs.chalmers.se/~rjmh/QuickCheck/.

COPYRIGHT and LICENSE

Copyright 2004 by Thomas G Moertel. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Test::LectroTest

perl -MCPAN -e shell
install Test::LectroTest