Repository files navigation

PropEr (PROPerty-based testing tool for ERlang) is a QuickCheck-inspiredopen-source property-based testing tool for Erlang, developed by ManolisPapadakis, Eirini Arvaniti, and Kostis Sagonas. The base PropEr system waswritten mainly by Manolis Papadakis, and the stateful code testing subsystemby Eirini Arvaniti. Kostis Sagonas has been actively maintaining its codebase since 2012.

You can reach PropEr's developers in the following ways:

• on the web: atthe project's home pageorthe project's github page
• by email: take the tool's name (all lowercase), add a @ followed bysoftlab dot ntua dot gr

We welcome user contributions and feedback (comments, suggestions, featurerequests, bug reports, patches, etc.).

Copyright 2010-2025 by Manolis Papadakis, Eirini Arvaniti, and Kostis Sagonas.

This program is distributed under theGPL,version 3 or later. Please see theCOPYING file for details.

Traditional testing methodologies essentially involve software testers writing aseries of test inputs for their programs, along with their correspondingexpected outputs, then running the program with these inputs and observingwhether it behaves as expected. This method of testing, while simple and easy toautomate, suffers from a few problems, such as:

• Writing test cases by hand is tedious and time consuming.
• It is hard to know whether the test suite covers all aspects of the softwareunder test.

Property-based testing is a novel approach to software testing, where the testerneeds only specify the generic structure of valid inputs for the program undertest, plus certain properties (regarding the program's behaviour and theinput-output relation) which are expected to hold for every valid input.A property-based testing tool, when supplied with this information, should randomlyproduce progressively more complex valid inputs, then apply those inputs to theprogram while monitoring its execution, to ensure that it behaves according toits specification, as outlined in the supplied properties.

Here are a few examples of simple properties a user may wish to test, expressedin natural language:

• The program should accept any character string and convert all lowercaseletters inside the string to uppercase.
• The program should accept any list of integers. If the input list is atleast 4 elements long, the program should return the 4th largest integer inthe list, else it should throw an exception.

PropEr is such a property-based testing tool, designed to test programs writtenin the Erlang programming language. Its focus is on testing the behaviour ofpure functions. On top of that, it is equipped with two library modules that canbe used for testing stateful code. The input domain of functions is specifiedthrough the use of a type system, modeled closely after the type system of thelanguage itself. Properties are written using Erlang expressions, with the helpof a few predefined macros.

PropEr is also tightly integrated with Erlang's type language:

• Types expressed in the Erlang type language can be used instead ofgenerators written in PropEr's own type system as input data specifications.
• Generators for ADTs can be constructed automatically using the ADTs' APIfunctions.
• PropEr can test functions automatically, based solely on informationprovided in their specs.

• Obtain a copy of PropEr's sources. You can either get a tagged version ofthe tool (look underTags on github) or you can clone the current codebase:

  git clone git@github.com:proper-testing/proper.git

• Compile PropEr: Simply runmake if you just want to build PropEr.If you want to do some changes to PropEr or submit some pull request youmost likely will want to issue amake test to run its unit tests andamake dialyzer call to also run dialyzer on PropEr's code base.To do the above but also build PropEr's documentation issue amake allcall; in that case, you are going to need thesyntax_tools applicationand a recent version ofEDoc).

• If you are usingHomebrew, you can simply:

  brew install proper

  and continue following the instructions below.

• Add PropEr's base directory to your Erlang library path, using one of thefollowing methods:

  1. ERL_LIBS environment variable: Add the following line to your shellstartup file (~/.bashrc in the case of the Bash shell):

     export ERL_LIBS=/full/path/to/proper

  2. Erlang resource file: Add the following line to your~/.erlang file:

     code:load_abs("/full/path/to/proper").

• Add the following include line to all source files that contain properties:

  -include_lib("proper/include/proper.hrl").

• Compile those source files, preferably withdebug_info enabled.

• For each property, run:

  proper:quickcheck(your_module:some_property()).

  See also the section common problems below if you want to runPropEr from EUnit.

To get started on using PropEr, see the tutorials and testing tips provided onPropEr's home page. On the same site you canfind a copy of PropEr's API documentation (you can also build this from sourceif you prefer, by runningmake doc), as well as links to more resources onproperty-based testing.

The main issue is that both systems define a?LET macro. To avoid apotential clash, simply include PropEr's header file before EUnit's. Thatway, any instance of?LET will count as a PropEr?LET.

Another issue is thatEUnit captures standard output,so normally PropEr output is not visible whenproper:quickcheck() isinvoked from EUnit. You can work around this by passing the option{to_file, user} toproper:quickcheck/2. For example:

?assertEqual(true,proper:quickcheck(your_mod:some_prop(), [{to_file,user}])).

This will make PropEr properties visible also when invoked from EUnit.

PropEr's notation and output format has been kept quite similar to that ofQuviQ's QuickCheck in order to ease the reuse of existing testing code writtenfor that tool. However, incompatibilities are to be expected, since we neverrun or owned a copy of QuviQ's QuickCheck and the two programs probably bearlittle resemblance under the hood. Here we provide a nonexhaustive list ofknown incompatibilities:

• ?SUCHTHATMAYBE behaves differently in PropEr.
• proper_gen:pick/1 differs fromeqc_gen:pick/1 in return value format.
• PropEr handlessize differently from QuickCheck.
• proper:module/2 accepts options in the second argument instead of thefirst; this is for consistency with othermodule/2 functions in Erlang/OTP.

All the above are from circa 2010. Most likely, there exist many moreincompatibilities between the two tools by now.