Skip to content
Property based Testing for Elixir (based upon PropEr)
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci ci: Store core and crash dumps Mar 21, 2019
config initial checkin Jul 5, 2015
lib Copy previous fix Apr 16, 2019
test Implement let-like bindings for forall Mar 21, 2019
.credo.exs
.gitignore ignore language server files Aug 22, 2018
CHANGELOG.md
LICENSE GPL 3 Jun 11, 2016
README.md Replace CircleCI badge with shields.io Apr 3, 2019
mix.exs Add Credo dependency Mar 20, 2019
mix.lock Add Credo dependency Mar 20, 2019
release.sh Preparing for 1.1.4 Feb 9, 2019

README.md

PropCheck - Property based testing for Elixir

PropCheck is a testing library, that provides a wrapper around PropEr, an Erlang based property testing framework in the spirit of QuickCheck.

CircleCI Hex.pm version

Installation

To use PropCheck with your project, add it as a dependency to mix.exs:

defp deps do
  [
    {:propcheck, "~> 1.1", only: [:test, :dev]}
  ]
end

Changes

Relevant changes are documented in the Changelog, on GitHub
follow this link
.

Basic Usage and Build Configuration

PropCheck allows to define properties, which automatically executed via ExUnit when running mix test. You find relevant information here:

  • details about the property macro are found in PropCheck.Properties,
  • details about how to specify the property conditions are documented in PropCheck,
  • the basic data generators are found in PropCheck.BasicTypes,
  • for property testing of state-based systems take a loot at PropCheck.StateM.DSL for the new DSL (since PropCheck 1.1.0-rc1), which is a layer on top of PropCheck.StateM.
  • The new targeted property based testing approach (TBPT) employing an automated search strategy towards more interesting test data is described in PropCheck.TargetedPBT.

For PropCheck, there is only one configuration option. All counter examples found are stored in a file, the name of which is configurable in mix.exs as part of the project configuration:

def project() do
  [ # many other options
    propcheck: [counter_examples: "filename"]
  ]
end

Per default, the counter examples file is stored in the build directory (_build), independent from the build environment, in the file propcheck.ctex. The file can be removed using mix propcheck.clean. Note that this task is only available if PropCheck is also available in :dev. Otherwise, MIX_ENV=test mix propcheck.clean can be used.

Links to other documentation

The guides for PropEr are an essential set of documents to make full use of PropCheck

Elixir versions of most of PropEr's tutorial material can be found in the test folder on GitHub.

Jesper Andersen and Robert Aloi blog about their thoughts and experience on using QuickCheck which are (mostly) directly transferable to PropCheck (with the notable exception of concurrency and the new state machine DSL from QuickCheck with the possibility to add requirement tags):

Rather new introductory resource are

In contrast to the book, the free website is concerned with Erlang only. The Erlang examples translate easily into Elixir (beside that at least a reading knowledge of Erlang is extremely helpful to survive in the BEAM ecosystem ...). Eventually I will port some of the examples to Elixir and PropCheck and certainly like to accept PRs.

What is not available

PropCheck does not support PropEr's capability to derive automatically type generators from type specifications. This is due to some shortcomings in PropEr, where the specification analysis in certain situation attempt to parse the Erlang source code of the file with the type specification. Apparently, this fails if the types are specified in an Elixir source file.

Effectively this means, that to to support this feature from Elixir, the type management system in PropEr needs to be rewritten completely. Jesper Andersen argues in his aforementioned blog post eloquently that automatically derived type generators are not needed, even more that carefully crafted type generators for specific testing purposes is an essential part of the QuickCheck philosophy. Therefore, this missing feature is not that bad. For the same reason, automatic @spec-checking is of limited value in PropCheck since type generators for functions specification are also generated automatically.

PropCheck has only very limited support for parallel testing since it introduces no new features for concurrency compared to PropEr.

Contributing

Please use the GitHub issue tracker for

  • bug reports and for
  • submitting pull requests

License

PropCheck is provided under the GPL 3 License due to its intimate use of PropEr (which is licensed under GPL 3). In particular, PropEr's exclusion rule of open source software from copyleft applies here as well as described in this discussion on GitHub.

Personally, I would prefer to use the LPGL to differentiate between extending PropEr and PropCheck as GPL-licensed software and the use of PropEr/PropCheck, which would not be infected by GPL's copyleft. But as long as PropEr does not change its licensing, we have no options. PropCheck is clearly an extension of PropEr, so it is derived work falling under GPL's copyleft. Using LGPL or any other license for PropCheck will not help, since GPL's copyleft overrules other licenses or result in an invalid or at least questionable licensing which does not help anybody.

From my understanding of open source licenses as a legal amateur, the situation is currently as follows: Since PropCheck is a testing framework, the system under test is not infected by the CopyLeft of GPL, since PropCheck is only a tool used temporarily during development of the system under test. At least, if you don't distribute your system together with the test code and the test libs as a binary. Another friendly approach is to have the tests in a separate project, such that the tests are a real client of the system under test. But again, this is my personal take. In question, please consult a professional legal advisor.

You can’t perform that action at this time.