/ 
Test-LectroTest-0.2002
River stage three • 5 direct dependents • 287 total dependents
/ LectroTest::Tutorial

NAME

LectroTest::Tutorial - How to use LectroTest to test your software

SYNOPSIS

LectroTest is an automated, specification-based testing system. To use it, you declare properties that specify the expected behavior of your software. LectroTest then checks to see whether those properties hold.

It does this by running repeated random trials against your software. If LectroTest finds that a property doesn't hold, it emits the counterexample that "broke" your software. You can then plug the counterexample into your software to debug the problem. (It's also a good idea to add the counterexample to your list of regression tests.)

OVERVIEW

Think of your software's behavior as a haystack that you're searching for needles. Each error is a needle. You want to find the needles and get rid of them. LectroTest will search the haystack for you -- it's nice that way -- but first you must tell it about the shape of the haystack and how to recognize a needle when it sees one.

The Haystack

The shape of the haystack is defined by a set of "generator bindings," in which variables are bound to the output of value generators:

x <- Int, c <- Char( charset=>"A-Z" )

The above can be read, "For all integers x and all characters c in the range A through Z." The idea is that each unique instance of the pair (x, c) specifies a point in the haystack that we can search for needles.

The Needle Recognizer

The "needle recognizer" is defined by a snippet of code that uses the bound variables to inspect a given point in the haystack. It returns a "thumbs up" (true) if the point is free of needles and a "thumbs down" (false) if it finds a needle:

the_thing_we_are_testing($x, $c) >= 0;

The above asserts for each point in the haystack that the output of the_thing_we_are_testing() must be non-negative.

Put them together to get a Property

The generator bindings and needle recognizer are combined into a LectroTest::Property:

Property {
  ##[ x <- Int, c <- Char( charset=>"A-Z" ) ]##
  the_thing_we_are_testing($x, $c) >= 0;
}, name => "the_thing_we_are_testing(...) is non-negative";

You'll note that we also added a meaningful name. Although not strictly required, it's an excellent practice.

We can read the above property like so: "For all integers x and all characters c in the range A through Z, we assert that the_thing_we_are_testing is non_negative." See? That's not too bad.

Testing whether your Properties hold

When you define properties for your software, just add them to a small Perl program that uses the Test::LectroTest module:

# MyProperties.l.t

use Test::LectroTest;

Property {
  ##[ x <- Int, c <- Char( charset=>"A-Z" ) ]##
  the_thing_we_are_testing($x, $c) >= 0;
}, name => "the_thing_we_are_testing(...) is non-negative";

Then you can test your properties simply by running the program:

$ perl MyProperties.l.t

If your properties check out, you'll see something like this:

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

If something goes wrong, however, LectroTest will tell you where it happened:

1..1
not ok 1 - 'the_thing_we_are_testing(...) is non-negative' \
  falsified in 23 attempts
# Counterexample:
# $x = -4
# $c = "R"

What this means is that at the point (x=-4, c="R") in the haystack, there is a needle (i.e., you're property didn't hold). With this information, you can examine your code to determine the cause of the error.

LET'S DO IT!

Now that we have big-picture understanding of "LectroTesting," let's try a few examples together.

[To do: write the step-by-step tutorial examples. For now, take a look at the slides from my LectroTest talk for two such examples. The slides are available at the LectroTest Home.

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.