Test::LectroTest(3pm)

✨ Test::LectroTest ✨

okay bestie, gather round, because this is the Perl module that is literally going to test your code for you, and I am obsessed 💖

It's Test::LectroTest — easy, automatic, specification-based tests. No cap.

💫 VERSION 💫

version 0.5001 — iconic, timeless, a little vintage but she works 🎀

🌸 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

like. look at that. that's the whole vibe. you just describe what your code should do and she goes and checks it. slay 💅

🦋 DESCRIPTION 🦋

So this module gives you a simple (yet full featured, she contains multitudes) interface to LectroTest, which is an automated, specification-based testing system for Perl. The way it works: you declare properties that specify the expected behavior of your software, and then LectroTest goes and checks your software to see whether those properties actually hold. It's giving "trust but verify" but make it cute 🌈

You declare properties with 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. Like, for example:

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

(Note the special bracketing — it's required, do not skip it, she will not work without it 🙈). This particular binding says, "For all integers x and y." And bestie, you are not limited to integers — LectroTest also gives you booleans, strings, lists, hashes, and more, and it lets you define your own generator types too. See Test::LectroTest::Generator for more, iykyk.

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're testing:

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

In this case, it asserts that MyModule::my_function($x,$y) returns a non-negative result. And 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. main character magic, honestly ✨

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. (future you, debugging at 2am, will thank present you 😭)

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." Periodt.

To check whether this property holds, simply put it in a Perl program that uses the Test::LectroTest module. (See the "SYNOPSIS" above 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. Random trials! She's out here stress-testing your code like a true queen 👑

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 that counterexample right back into your software to debug the problem. (You might also want to add the counterexample to a list of regression tests — lowkey genius move.)

A successful LectroTest looks like this, and it is gorgeous:

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

and there it is, the exact inputs that ruined your day. iconic behaviour 💀

---

🚪 EXIT CODE 🚪

The exit code returned by running a suite of property checks is the number of failed checks. The code is 0 if all properties passed their checks, or N if N properties failed. (And if more than 254 properties failed, the exit code will be 254 — she caps out, she has limits.)

🎀 ADJUSTING THE TESTING PARAMETERS 🎀

There is one testing parameter (among others) that you might wish to change from time to time: the number of trials to run for 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;

go big or go home, bestie 💅

🧚 TESTING FOR REGRESSIONS AND CORNER CASES 🧚

LectroTest can record failure-causing test cases to a file, and it can play those test cases back as part of its normal testing strategy. The easiest way to take advantage of this feature is to set the regressions parameter when you use this module:

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 only to 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. she never forgets a bug 🍓

🫶 CAVEATS 🫶

When you use this module, it imports all of the generator-building functions from Test::LectroTest::Generator into your code's namespace. This is almost always what you want, but I figured I ought to say something about it here to reduce the possibility of surprise. (surprise! but the good kind, usually ✨)

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. (no indenting, bestie. she's picky about that one specific thing 🙈)

👑 SEE ALSO 👑

For a gentle introduction to LectroTest, see Test::LectroTest::Tutorial. Also, the slides from my LectroTest talk for the Pittsburgh Perl Mongers make for a great introduction. Download a copy from the LectroTest home (see below).

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 🌈

The LectroTest home is http://community.moertel.com/LectroTest. There you will find more documentation, presentations, mailing-list archives, 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 QuickCheck module by Koen Claessen and John Hughes: http://www.cs.chalmers.se/~rjmh/QuickCheck/.

💖 COPYRIGHT and LICENSE 💖

Copyright (c) 2004-05 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.

---

and that's the whole page, bestie 🎀 this was Test::LectroTest version 0.5001, rendered from perl v5.34.0 on 2022-06-21 — go write some properties, she's waiting for you 💅✨