Test::...operty(3pm)

✨ NAME ✨

Test::LectroTest::Property — bestie, this is the module that lets you write Properties: testable claims about your software. Claims that a robot can check for you. Over and over. With random inputs. It's giving main character energy for your test suite. 💅

---

🌸 VERSION 🌸

version 0.5001 — yes, that's the one, no cap. 💖

---

🎀 SYNOPSIS 🎀

okay so here's the whole vibe in one go:

use MyModule;  # provides my_function_to_test

use Test::LectroTest::Generator qw( :common );
use Test::LectroTest::Property qw( Test );
use Test::LectroTest::TestRunner;

my $prop_non_neg = Property {
    ##[ x <- Int, y <- Int ]##
    $tcon->label("negative") if $x < 0;
    $tcon->label("odd")      if $x % 2;
    $tcon->retry             if $y == 0;  # 0 can't be used in test
    my_function_to_test( $x, $y ) >= 0;
}, name => "my_function_to_test output is non-negative";

my $runner = Test::LectroTest::TestRunner->new();
$runner->run_suite(
    $prop_non_neg,
    # ... more properties here ...
);

look at that. immaculate. 🦋

---

💜 DESCRIPTION 💜

STOP! 🛑 Bestie. If you're just looking for an easy way to write and run unit tests, go read Test::LectroTest first, fr fr. Once you're comfy with what's in there and you're ready to delve into the full offerings of properties — the whole menu, the deluxe experience — then this is the document for you. 💖

This module lets you define Properties that Test::LectroTest can check automatically for you. And what even is a Property? It's a specification of your software's required behavior over a given set of conditions. The set of conditions? That comes from a generator-binding specification. The required behavior? That's defined implicitly by a block of code that tests your software against a given set of generated conditions. If your software matches the expected behavior, the block returns true. If it doesn't — false. That's it. That's the whole deal. 🎯

This doc is the reference documentation for LectroTest Properties. If you don't understand the basics of Properties yet, lowkey go read "OVERVIEW" in Test::LectroTest::Tutorial before continuing. No shame, we've all been there. 🫶

---

🧚 Two ways to create Properties 🧚

There are exactly two ways to create a property, and both are valid, and I love that for us:

1. Use the Property function to promote a block of code — one that contains both a generator-binding specification and a behavior test — into a Test::LectroTest::Property object. This is the preferred method. Periodt. ✨

my $prop1 = Property {
    ##[ x <- Int ]##
    thing_to_test($x) >= 0;
}, name => "thing_to_test is non-negative";

2. Use the new method of Test::LectroTest::Property and hand it the necessary ingredients via named parameters:

my $prop2 = Test::LectroTest::Property->new(
    inputs => [ x => Int ],
    test   => sub { my ($tcon,$x) = @_;
                    thing_to_test($x) >= 0 },
    name   => "thing_to_test is non-negative"
);

Both are equivalent, okay? But the first one is concise, easier to read, and lets LectroTest do some of the heavy lifting for you — which is the dream, honestly. 💅 The second one is probably better though if you're constructing property specifications programmatically, iykyk. 🤖

---

🌈 Generator-binding specification 🌈

The generator-binding specification is where you declare that certain variables are gonna be bound to certain kinds of random-value generators during the tests of your software's behavior. The number and kind of generators define the "condition space" that gets examined during property checks. It's the map of everything you're about to explore. 🗺️

If you use the Property function to create your properties, your generator-binding specification must come first in your code block, and you must use this syntax:

##[ var1 <- gen1, var2 <- gen2, ... ]##

⚠️ Comments are not allowed within the specification. Sorry bestie. But you can break it across multiple lines:

##[ var1 <- gen1,
    var2 <- gen2, ...
]##

or

##[
    var1 <- gen1,
    var2 <- gen2, ...
]##

And here's a cute lil trick: for better integration with syntax-highlighting IDEs, that terminating ]## delimiter may be preceded by a hash symbol # and optional whitespace, so it looks like a comment and your editor chills out:

##[
    var1 <- gen1,
    var2 <- gen2, ...
# ]##

On the other hand 👀 — if you use Test::LectroTest::Property->new() to create your objects, the generator-binding specification takes the form of an array reference containing variable-generator pairs, passed to new() via the parameter named inputs:

inputs => [ var1 => gen1, var2 => gen2, ... ]

Normal Perl syntax applies here. Nothing wild. 🍓

---

🦋 Specifying multiple sets of generator bindings 🦋

Sometimes you wanna repeat a property check with multiple sets of generator bindings. When does that happen? Say your condition space is absolutely vast and you want to make sure a particular portion of it gets focused coverage while still sampling the overall space. Times like this, bestie! You can list multiple sets of bindings inside the ##[ and ]## delimiters, like so:

##[ var1 <- gen1A, ... ],
  [ var1 <- gen1B, ... ],
  ... more sets of bindings ...
  [ var1 <- gen1N, ... ]##

Note that only the first and last set need the special delimiters. 👑

The equivalent when using new() is as follows:

inputs => [ [ var1 => gen1A, ... ],
            [ var1 => gen1B, ... ],
            ...
            [ var1 => gen1N, ... ] ]

Regardless of how you declare the sets of bindings, every single set must provide bindings for the exact same set of variables. (The generators, of course, can be different. That part's fine.) For example, this kind of thing is illegal:

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

The above is illegal because both sets of bindings must use x or both must use y; they can't each use a different variable. Not allowed. Nope. 🚫

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

The above is illegal because the second set has an extra variable that isn't present in the first. Both sets must use exactly the same variables. None of the variables may be extra, none may be missing, and all must be named identically across the sets of bindings. It's giving strict, but it's for your own good. 💀

---

💖 Behavior test 💖

The behavior test is a subroutine that accepts a test-controller object and a given set of input conditions, tests your software's observed behavior against the required behavior with respect to the input conditions, and returns true or false to indicate acceptance or rejection. Simple. Iconic. 🎀

If you're using the Property function to create your property objects, lexically bound variables are created and loaded with values automatically, per your input-generator specification, so you can just go ahead and use the variables immediately:

my $prop = Property {
  ##[ i <- Int, delta <- Float(range=>[0,1]) ]##
  my $lo_val = my_thing_to_test($i);
  my $hi_val = my_thing_to_test($i + $delta);
  $lo_val == $hi_val;
}, name => "my_thing_to_test ignores fractions" ;

On the other hand, if you're using Test::LectroTest::Property->new(), you must declare and initialize these variables manually from Perl's @_ variable in lexicographically increasing order, after receiving $tcon, the test controller object. (This inconvenience, by the way, is exactly why the former method is preferred. Just saying. 🙈) The hard way:

my $prop = Test::LectroTest::Property->new(
  inputs => [ i => Int, delta => Float(range=>[0,1]) ],
  test => sub {
      my ($tcon, $delta, $i) = @_;
      my $lo_val = my_thing_to_test($i);
      my $hi_val = my_thing_to_test($i + $delta);
      $lo_val == $hi_val
  },
  name => "my_thing_to_test ignores fractions"
) ;

---

🔥 Control logic, retries, and labeling 🔥

Inside the behavior test, you have access to a special variable $tcon that lets you interact with the test controller. Through $tcon you can do the following:

• retry the current trial with different inputs (if you don't like the inputs you were given at first) 🔁
• add labels to the current trial for reporting purposes 🏷️
• attach notes and variable dumps to the current trial for diagnostic purposes, should the trial fail 🕵️

(For the full details of what you can do with $tcon, see the "testcontroller" section of Test::LectroTest::TestRunner.) ✨

For example, let's say we've written a function my_sqrt that returns the square root of its input. In order to check whether our implementation fulfills the mathematical definition of square root, we might specify the following property:

my $epsilon = 0.000_001;

Property {
    ##[ x <- Float ]##
    return $tcon->retry if $x < 0;
    $tcon->label("less than one") if $x < 1;
    my $sx = my_sqrt( $x );
    abs($sx * $sx - $x) < $epsilon;
}, name => "my_sqrt satisfies defn of square root";

Because we don't wanna deal with imaginary numbers (respect), our square-root function is defined only over non-negative numbers. To make sure we don't accidentally check our property "at" a negative number, we use the following line to re-start the trial with a different input, should the input we're given at first be negative:

return $tcon->retry if $x < 0;

Here's an interesting fact bestie: for all values x between zero and one, the square root of x is larger than x itself. Wild, right? So maybe our implementation treats such values as a special case. 👀 In order to be confident that we're checking this case, we added the following line:

$tcon->label("less than one") if $x < 1;

And in the property-check output, we can see what percentage of the trials checked this case:

1..1
ok 1 - 'my_sqrt satisfies defn of square root' (1000 attempts)
#   1% less than one

look at that little # 1% less than one sitting there. so informative. so cute. 💅

---

🍓 Trivial cases 🍓

Random-input generators may create some inputs that are trivial and don't provide much testing value. It happens! To make it easy to label such cases, you can use the following from within your behavior tests:

$tcon->trivial if ... ;

And the above is exactly equivalent to the following:

$tcon->label("trivial") if ... ;

same energy, shorter to type. you're welcome. 💖

---

🫶 SEE ALSO 🫶

Test::LectroTest::Generator describes the many generators and generator combinators that you can use to define the test or condition spaces 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 wanna look here if you're interested in customizing the testing procedure. 🎛️

---

🐉 HERE BE SOURCE FILTERS 🐉

The special syntax used to specify generator bindings relies upon a source filter (see Filter::Util::Call). If you don't want to use the syntax, you can disable the filter like so:

use Test::LectroTest::Property qw( NO_FILTER );

no filter, no magic syntax, just vibes. 🌈

---

💜 AUTHOR 💜

Tom Moertel (tom@moertel.com) — king behavior, honestly. 👑

---

⭐ INSPIRATION ⭐

The LectroTest project was inspired by Haskell's QuickCheck module by Koen Claessen and John Hughes:

http://www.cs.chalmers.se/~rjmh/QuickCheck/

(the blueprint! the blueprint!) 🧚

💖 COPYRIGHT and LICENSE 💖

okay bestie, legal era, but make it cute 💅

Copyright (c) 2004-13 by Thomas G Moertel. All rights reserved. 🫶 like, every single right, reserved, no takebacks, periodt.

---

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

That's the whole vibe. Slay, go forth, remix responsibly. ✨

---

and that's a wrap on Test::...operty(3pm) 🎀 this little doc came from perl v5.34.0, dated 2022-06-21 — shoutout to the version and the date, iconic duo, they really carried this footer 💜 🦋 bye bestie, go write some properties 🌈