NAME

VERSION

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

Declare properties using the "Property" function, which takes a block of code and promotes it to a Test::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 is required.) This particular binding says, "For all integers x and y." (By the way, you aren't limited to integers. LectroTest also gives you booleans, strings, lists, hashes, and more, and it lets you define your own generator types. See Test::LectroTest::Generator for more.)

The second part of the block is simply a snippet 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 lexically bound Perl variables with values behind the scenes.)

Note: If you want to use testing assertions like "ok" from Test::Simple or "is", "like", or "cmp_ok" from Test::More (and the related family of Test::Builder-based testing modules), see Test::LectroTest::Compat, which lets you mix and match LectroTest with these modules.

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 specification:

    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 you're testing.

Note: If you want to place LectroTest property checks into a test plan managed by Test::Builder-based modules such as Test::Simple or Test::More, see Test::LectroTest::Compat.

If LectroTest is able to "break" your software during the property check, it will emit a counterexample to your property's assertions 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

EXIT CODE

ADJUSTING THE TESTING PARAMETERS

  use Test::LectroTest trials => 10_000;

TESTING FOR REGRESSIONS AND CORNER CASES

    use Test::LectroTest
        regressions => "regressions.txt";

This tells LectroTest to use the file "regressions.txt" for both recording and playing back failures. If you want to record and play back from separate files, or want only to record or play back, use the record_failures and/or playback_failures options:

    use Test::LectroTest
        playback_failures => "regression_suite_for_my_module.txt",
        record_failures   => "failures_in_the_field.txt";

See Test::LectroTest::RegressionTesting for more.

CAVEATS

A Property specification must appear in the first column, i.e., without any indentation, in order for it to be automatically loaded and checked. If this poses a problem, let me know, and this restriction can be lifted.

SEE ALSO

Test::LectroTest::RegressionTesting explains how to test for regressions and corner cases using LectroTest.

Test::LectroTest::Compat lets you mix LectroTest with the popular family of Test::Builder-based modules such as Test::Simple and Test::More.

Test::LectroTest::Property explains in detail what you can put inside of your property specifications.

Test::LectroTest::Generator describes the many generators and generator combinators that you can use to define the test or condition space that you want LectroTest to search for bugs.

Test::LectroTest::TestRunner describes the objects that check your properties and tells you how to turn their control knobs. You'll want to look here if you're interested in customizing the testing procedure.

LECTROTEST HOME

AUTHOR

INSPIRATION

COPYRIGHT and LICENSE

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