A rebar3 plugin to enable the execution of Erlang QuickCheck properties
This plugin provides the ability to run all or a subset of the EQC
properties defined in a project's applications with a simple rebar3
command. For a property to be found and executed by the plugin it must
use the prop_* naming convention and be exported from the module in
which it resides. Otherwise, the property name may be given using the
--properties option. The number of times each property is executed
is configurable as shown in the Configuration and Usage sections
below with the default being 100 times. For users of the full version
of EQC it is also possible to have each property execute for a certain
period of time as opposed to a fixed number of iterations per
property.
The plugin takes the approach of executing EQC properties directly as opposed to the common pattern of indirect execution via another test framework. There are still cases where it may be useful to use eunit or common_test for execution of EQC properties, but there are many cases where that is not required.
The plugin scans all source modules for EQC properties. Additionally
it looks for standalone EQC properties in a top-level eqc directory.
The default plugin behavior is to execute all properties found in the
application source code or the eqc directory. This behavior can be
overridden by using the --properties option to specify a
comma-separated list of properties to be executed. List entries may be
of the form ModuleName:PropertyName or simply PropertyName if the
property name is unique within the project.
The plugin also has a counterexample mode. When a property fails when
run using the plugin a counterexample file is written to an .eqc
sub-directory in the project directory. The counterexample files are
named for the properties that generate them. This allows for
rechecking a set of properties using their respective counterexample
files except in cases where a project has properties sharing the same
name in different modules. The --properties option may also be used
with counterexample mode to recheck a specific property or set of
properties.
To install the plugin using the Hex package manaage, add the following to the rebar.config file:
{plugins, [rebar3_eqc]}
Alternatively, to install the plugin from github use the following:
{plugins, [
{rebar3_eqc, ".*", {git, "https://github.com/kellymclaughlin/rebar3-eqc-plugin.git", {tag, "0.0.10"}}}
]}.
To set the number of test executions to 500 instead of the default of 100, add the following rebar.config entry:
{eqc_opts, [{numtests, 500}]}.
To specify that each property execute for 30 seconds, use this entry instead:
{eqc_opts, [{testing_time, 30}]}.
The numtests and testing_time options are mutually exclusive. If
both are specified, the testing_time setting is ignored.
To view the plugin usage menu with a full list of options and their
descriptions use ./rebar3 help eqc. The following are some example
scenarios of plugin usage.
Execute each property the configured number of times or for the configured duration:
./rebar3 eqc
Override the configuration in rebar.config or the default and
execute each property 10 times:
./rebar3 eqc -n 10
Similarly, override the configuration in rebar.config or the default
and execute each property for 45 seconds:
./rebar3 eqc -t 45
To only execute the property prop_test1 in the module test_module
for 1000 iterations use the following:
./rebar3 eqc -n 1000 -p test_module:prop_test1
To execute the same test, but to have the plugin determine the module name use the following:
./rebar3 eqc -n 1000 -p prop_test1