Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Test::LectroTest(3)   User Contributed Perl Documentation  Test::LectroTest(3)

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

VERSION
       version 0.5001

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, an automated, specification-based testing system for	Perl.
       To use it, declare properties that specify the expected behavior	of
       your software.  LectroTest then checks your software to see whether
       those properties	hold.

       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
       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. (If more than 254 properties
       failed, the exit	code will be 254.)

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;

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 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
       When you	use this module, it imports all	of the generator-building
       functions from Test::LectroTest::Generator into the 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.

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

perl v5.24.1			  2013-05-16		   Test::LectroTest(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | EXIT CODE | ADJUSTING THE TESTING PARAMETERS | TESTING FOR REGRESSIONS AND CORNER CASES | CAVEATS | SEE ALSO | LECTROTEST HOME | AUTHOR | INSPIRATION | COPYRIGHT and LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Test::LectroTest&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help