PropCheck

https://hexdocs.pm/propcheck
Admin
PropCheck is a property-based testing library for Elixir that provides a wrapper around PropEr, an...
Tokens:83,542
Snippets:948
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Configure counter examples file

Source: https://hexdocs.pm/propcheck/index.html

Set the filename for storing counter examples in your project configuration or application environment.

```elixir
def project() do
  [
    propcheck: [counter_examples: "filename"]
  ]
end
```

```elixir
config :propcheck, counter_examples: "filename"
```

--------------------------------

### start_link()

Source: https://hexdocs.pm/propcheck/PropCheck.OutputAgent-function-start_link.html

Starts the PropCheck.OutputAgent process.

```APIDOC
## start_link()

### Description
Starts the agent process for PropCheck.OutputAgent.

### Method
Function Call

### Endpoint
PropCheck.OutputAgent.start_link()
```

--------------------------------

### Configure PropCheck Counter Examples Filename

Source: https://hexdocs.pm/propcheck/readme.html

Configure the filename for storing counter examples in mix.exs under the project configuration. This setting can be overridden by the application environment.

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

--------------------------------

### Resize usage examples

Source: https://hexdocs.pm/propcheck/PropCheck.BasicTypes-function-resize.html

Demonstrates using resize to control the growth rate of generated lists.

```elixir
iex> quickcheck(forall l <- list(integer()) do
...>   length(l) <= 42
...> end)
true

iex> long_list = sized(size, resize(size * 2, list(integer())))
iex> really_long = such_that_maybe l <- long_list, when:
...>      length(l) > 42
iex> quickcheck(forall l <- really_long do
...>   (length(l) <= 84)
...>   |> measure("List length", length l)
...>   |> collect(length l)
...> end)
true
```

--------------------------------

### Macro: property_setup/2

Source: https://hexdocs.pm/propcheck/PropCheck-macro-property_setup.html

Defines a setup function for a property that executes before the first test and provides a teardown mechanism.

```APIDOC
## property_setup(setup_fun, prop)

### Description
Adds a setup function to the property which will be called before the first test. This function must return a finalize function of arity 0, which should return the atom `:ok`, that will be called after the last test. Multiple `property_setup` macros can be used on the same property.

### Parameters
- **setup_fun** (function) - Required - A function that performs setup and returns a teardown function.
- **prop** (property) - Required - The property to which the setup is applied.
```

--------------------------------

### Configure PropCheck Counter Examples in Application Environment

Source: https://hexdocs.pm/propcheck/readme.html

Configure the filename for storing counter examples using the application environment. This setting takes precedence over the project configuration in mix.exs.

```elixir
config :propcheck, counter_examples: "filename"
```

--------------------------------

### Example Property for PropCheck.FSM

Source: https://hexdocs.pm/propcheck/PropCheck.FSM.html

Provides an example of a property that can be used to test a finite state machine specification.

```APIDOC
## The Property Used

### Description
This is an example of a property that can be used to test a finite state machine specification. It expects a `cleanup` function that takes care of removing all artifacts created during tests to enable a clean start for each test case execution.

```elixir
property "fsm" do
   forall cmds <- commands(__MODULE__) do
     {_history, _state, result} = run_commands(__MODULE__, cmds)
     cleanup()
     result == :ok
  end
end
```
```

--------------------------------

### Implement weight callback

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.DSL-callback-weight.html

Example implementation of the weight function returning a map of command/weight pairs.

```elixir
def weight(state), do: %{x: 1, y: 1, a: 2, b: 2}
```

--------------------------------

### Use PropCheck.equals in tests

Source: https://hexdocs.pm/propcheck/PropCheck-function-equals.html

Examples demonstrating the usage of equals within quickcheck properties.

```elixir
iex> use PropCheck
iex> quickcheck(equals(:ok, :ok))
:true
```

```elixir
iex> use PropCheck
iex> quickcheck(
...> forall x <- :ok do
...>   equals(:ok, x)
...> end)
:true
```

```elixir
iex> use PropCheck
iex> quickcheck(
...> forall x <- :not_ok do
...>   equals(:ok, x)
...> end)
:false
```

--------------------------------

### Example Command Sequence for Process Dictionary

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.html

This sequence demonstrates symbolic calls to manipulate the process dictionary, using symbolic variables to represent results of operations.

```Elixir
[
 {:set, {:var, 1}, {:call, :erlang, :put, [:a, 42]}},
 {:set, {:var, 2}, {:call, :erlang, :erase, [:a]}},
 {:set, {:var, 3}, {:call, :erlang, :put, [:b, {:var, 2}]}}
]
```

--------------------------------

### commands/2

Source: https://hexdocs.pm/propcheck/PropCheck.StateM-function-commands.html

Similar to `commands/1`, but generated command sequences always start at a given state. The first command is always `{:init, initial_state}`.

```APIDOC
## commands/2

### Description
Similar to `commands/1`, but generated command sequences always start at a given state. In this case, the first command is always `{:init, initial_state}` and is used to correctly initialize the state every time the command sequence is run (i.e. during normal execution, while shrinking and when checking a counterexample). In this case, `mod:initial_state/0` is never called.

### Method
N/A (Function signature)

### Endpoint
N/A (Function signature)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Install PropCheckCommons via Mix

Source: https://hexdocs.pm/propcheck_commons/index.html

Add the dependency to your mix.exs file to include the library in your project.

```elixir
def deps do
  [
    {:propcheck_commons, "~> 0.1"}
  ]
end
```

--------------------------------

### mix propcheck.inspect

Source: https://hexdocs.pm/propcheck/Mix.Tasks.Propcheck.Inspect.html

Documentation for the mix task used to inspect counter examples.

```APIDOC
## mix propcheck.inspect

### Description
Inspects all counter examples generated by PropCheck.

### Usage
Run this task in your terminal within a project directory where PropCheck is configured.
```

--------------------------------

### Example IPv4 Generation

Source: https://hexdocs.pm/propcheck_commons/PropCheckCommons.Network.html

Demonstrates how to use the `ipv4` generator with different configurations in IEx. It shows generating an IPv4 address with a subnet mask of 0 and another with a specific static range and tuple format.

```elixir
iex> use PropCheck iex> alias PropCheckCommons.Network
iex> {:ok, "192.168" <> _} = produce(Network.ipv4(0))
iex> {:ok, {10, 10, 1, num}} = produce(Network.ipv4(24, {10, 10, 1}, :tuple))
iex> num >= 0 and num < 256
:true
```

--------------------------------

### GET /counterexample

Source: https://hexdocs.pm/propcheck/PropCheck.html

Retrieves the last (simplest) counterexample produced by PropCheck during the most recent testing run.

```APIDOC
## GET /counterexample

### Description
Retrieves the last (simplest) counterexample produced by PropCheck during the most recent testing run.

### Method
GET

### Endpoint
/counterexample

### Response
#### Success Response (200)
- **counterexample** (counterexample() | :undefined) - The last counterexample found.
```

--------------------------------

### initial_state() Callback

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.DSL-callback-initial_state.html

The initial_state callback is responsible for computing the starting state of the state machine.

```APIDOC
## initial_state()

### Description
The initial state of the state machine is computed by this callback.

### Method
Callback

### Endpoint
N/A

### Parameters
None

### Request Example
None

### Response
#### Success Response (symbolic_state)
- Returns the initial symbolic state of the state machine.

#### Response Example
None
```

--------------------------------

### Generate Lists with Length Greater Than One

Source: https://hexdocs.pm/propcheck/PropCheck-macro-such_that.html

This example shows how to generate lists of natural numbers that are guaranteed to have more than one element using `such_that`. The `quickcheck` call verifies a property on these lists, and `:start_size` is specified to ensure generation begins with lists large enough to satisfy the constraint.

```elixir
iex> use PropCheck
iex> twofer_list = such_that l <- list(nat()), when: length(l) > 1
iex> quickcheck(
...>   forall [_ | t] <- twofer_list do
...>     Enum.any?(t)
...>   end, [start_size: 2])
true
```

--------------------------------

### commands/2

Source: https://hexdocs.pm/propcheck/PropCheck.FSM-function-commands.html

Generates random command sequences starting at a specific state for the finite state machine.

```APIDOC
## commands(mod, initial_state)

### Description
Similar to commands/1, but generated command sequences always start at a given state. The first command is always {:init, initial_state = {name, data}} to ensure correct state initialization during execution, shrinking, and counterexample checking.

### Parameters
#### Arguments
- **mod** (mod_name) - Required - The name of the callback module containing the FSM specification.
- **initial_state** (fsm_state) - Required - The specific state to start the command sequence from.

### Response
- **PropCheck.type** - A PropEr type representing the generated command sequence starting at the provided state.
```

--------------------------------

### Generate Command Sequences from Specific Initial State

Source: https://hexdocs.pm/propcheck/PropCheck.FSM.html

Similar to commands/1, but generated command sequences always start at a specified state. The first command is always {:init, initial_state} to correctly initialize the state.

```Elixir
@spec commands(mod_name(), fsm_state()) :: PropCheck.type()
```

--------------------------------

### Define Initial Model State

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.DSL.html

Implement the `initial_state/0` function to define the starting state of the model. This function should return the initial value for the model, typically an empty collection or a default configuration.

```elixir
def initial_state(), do: []
```

--------------------------------

### function4 Usage Example

Source: https://hexdocs.pm/propcheck/PropCheck.BasicTypes-function-function4.html

Illustrates the expected usage of function4, showing it can be called with 4 parameters and a specified return type.

```elixir
function4(4, ret_type)
```

--------------------------------

### commands(mod, initial_state)

Source: https://hexdocs.pm/propcheck/PropCheck.FSM.html

Generates random command sequences starting from a specified initial state.

```APIDOC
## commands(mod, initial_state)

### Description
Similar to `commands/1`, but generated command sequences always start at a given state. In this case, the first command is always `{:init, initial_state = {name, data}}` and is used to correctly initialize the state every time the command sequence is run (i.e. during normal execution, while shrinking and when checking a counterexample).

### Method
GET

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (PropCheck.type)
- **PropCheck.type** - A PropEr type that generates command sequences starting from a specific state.

#### Response Example
N/A
```

--------------------------------

### child_spec/1

Source: https://hexdocs.pm/propcheck/PropCheck.OutputAgent-function-child_spec.html

Returns a specification to start the PropCheck.OutputAgent module under a supervisor.

```APIDOC
## child_spec(arg)

### Description
Returns a specification to start this module under a supervisor. See the Supervisor documentation for more details.

### Parameters
- **arg** (any) - Required - The argument passed to the child specification.
```

--------------------------------

### commands/2 Function

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.html

Generates random command sequences starting from a specified initial state.

```APIDOC
## commands/2 Function

### Description
Similar to `commands/1`, but generated command sequences always start at a given state. The first command is always `{:init, initial_state}` to correctly initialize the state. `mod:initial_state/0` is not called in this case.

### Method
`commands(mod, initial_state)`

### Endpoint
N/A (Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
Generates random command sequences starting from a specified initial state.

#### Response Example
None
```

--------------------------------

### parallel_commands/2

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.ModelDSL-function-parallel_commands.html

Generates parallel test cases starting from a specific state.

```APIDOC
## parallel_commands(mod, initial_state)

### Description
Similar to parallel_commands/1, but generated command sequences always start at a given state.

### Parameters
#### Arguments
- **mod** (atom) - Required - The name of the callback module.
- **initial_state** (term) - Required - The state at which the command sequences start.
```

--------------------------------

### parallel_commands/2 Function

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.html

Generates parallel test cases starting from a specified initial state.

```APIDOC
## parallel_commands/2 Function

### Description
Similar to `parallel_commands/1`, but generated command sequences always start at a given state.

### Method
`parallel_commands(mod, initial_state)`

### Endpoint
N/A (Function)

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
Generates parallel test cases starting from a specified initial state.

#### Response Example
None
```

--------------------------------

### Generate Commands with Explicit Initial State

Source: https://hexdocs.pm/propcheck/PropCheck.FSM-function-commands.html

Use this function when you need to specify the starting state for the generated command sequences. The first command will always be `{:init, initial_state}` to ensure proper state initialization.

```Elixir
commands(mod_name(), fsm_state()) :: PropCheck.type()
```

--------------------------------

### Generate Even Natural Numbers with such_that

Source: https://hexdocs.pm/propcheck/PropCheck-macro-such_that.html

This example demonstrates how to use `such_that` to generate only even natural numbers. It then uses `quickcheck` to verify that all generated even numbers satisfy the `rem(n, 2) == 0` condition.

```elixir
iex> use PropCheck
iex> even = such_that n <- nat(), when: rem(n, 2) == 0
iex> quickcheck(
...>   forall n <- even do
...>     rem(n, 2) == 0
...>   end)
true
```

--------------------------------

### commands/2 Function

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.ModelDSL.html

Generates random command sequences starting from a specific initial state. The first command is always {:init, initial_state}, and :initial_state/0 is not called.

```Elixir
commands(mod, initial_state)
```

--------------------------------

### Run PropEr Property with quickcheck/2 and Options

Source: https://hexdocs.pm/propcheck/PropCheck-function-quickcheck.html

Same as `quickcheck/1`, but also accepts a list of options. Use this when custom configurations are needed for property testing.

```elixir
quickcheck(outer_test(), user_opts()) :: result()
```

--------------------------------

### Define a Property to Test a Stateful System

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.ModelDSL.html

This property tests a stateful system by starting it, running a sequence of commands, stopping it, and evaluating the result. Use this to verify the sequential execution of commands.

```elixir
property "run the sequential cache", [:verbose] do
  forall cmds <- commands(__MODULE__) do
    Cache.start_link(@cache_size)
    {_history, _state, result} = run_commands(__MODULE__, cmds)
    Cache.stop()
    (result == :ok)
  end
end
```

--------------------------------

### Disable storing counter examples module-wide

Source: https://hexdocs.pm/propcheck/PropCheck.Properties-macro-property.html

Disables the storage of counter examples for all properties within a module by setting the `@moduletag`.

```elixir
defmodule Test do
  # ...
  @moduletag store_counter_example: false
  #...
end
```

--------------------------------

### Disable storing counter examples for a single property

Source: https://hexdocs.pm/propcheck/PropCheck.Properties-macro-property.html

Disables the storage of counter examples for an individual property using the `@tag` attribute.

```elixir
@tag store_counter_example: false
property "a property" do
  # ...
end
```

--------------------------------

### Define Shrinking with PropCheck.shrink

Source: https://hexdocs.pm/propcheck/PropCheck-macro-shrink.html

Use `shrink/2` to define a custom shrinking strategy. The first argument is the main generator, and the second is a list of alternative, simpler generators. The example demonstrates shrinking positive integers, preferring 0 as a simpler alternative.

```elixir
iex> use PropCheck
iex> quickcheck(
...>   forall n <- shrink(pos_integer(), [0]) do
...>     rem(n, 2) == 0
...>   end)
false
```

--------------------------------

### Disable storing counter examples for a describe block

Source: https://hexdocs.pm/propcheck/PropCheck.Properties-macro-property.html

Disables the storage of counter examples for all properties within a specific `describe` block using the `@describetag`.

```elixir
defmodule Test do
  # ...
  describe "describe block" do
    @describetag store_counter_example: false
    # ...
  end
end
```

--------------------------------

### Retrieve Counterexample with Options

Source: https://hexdocs.pm/propcheck/PropCheck.html

Equivalent to quickcheck/2, retrieves a counterexample and accepts user options.

```elixir
@spec counterexample(outer_test(), user_opts()) :: long_result()
```

--------------------------------

### PropCheck FSM Property Example

Source: https://hexdocs.pm/propcheck/PropCheck.FSM.html

This is an example of a property used to test a finite state machine specification. It requires a cleanup function for test case isolation.

```elixir
property "fsm" do
   forall cmds <- commands(__MODULE__) do
     {_history, _state, result} = run_commands(__MODULE__, cmds)
     cleanup()
     result == :ok
  end
end
```

--------------------------------

### quickcheck/2

Source: https://hexdocs.pm/propcheck/PropCheck-function-quickcheck.html

Runs PropEr on the provided property with custom options.

```APIDOC
## quickcheck(outer_test, user_opts)

### Description
Runs PropEr on the property `outer_test` with a list of user-defined options.

### Parameters
- **outer_test** (outer_test) - Required - The property to be tested.
- **user_opts** (user_opts) - Required - A list of options to configure the test run.

### Response
- **result** (result) - The result of the property check.
```

--------------------------------

### quickcheck/1

Source: https://hexdocs.pm/propcheck/PropCheck-function-quickcheck.html

Runs PropEr on the provided property.

```APIDOC
## quickcheck(outer_test)

### Description
Runs PropEr on the property `outer_test`.

### Parameters
- **outer_test** (outer_test) - Required - The property to be tested.

### Response
- **result** (result) - The result of the property check.
```

--------------------------------

### Configure PropCheck counter-example file

Source: https://hexdocs.pm/propcheck/Mix.Tasks.Propcheck.html

Set the custom filename for storing counter-examples within the project configuration in mix.exs.

```elixir
propcheck: [counter_example: "filename"]
```

--------------------------------

### parallel_commands/2

Source: https://hexdocs.pm/propcheck/PropCheck.StateM-function-parallel_commands.html

Generates parallel test cases starting from a specific provided state.

```APIDOC
## parallel_commands(mod, initial_state)

### Description
Similar to parallel_commands/1, but generated command sequences always start at a given state.

### Parameters
#### Arguments
- **mod** (atom) - Required - The name of the callback module.
- **initial_state** (term) - Required - The specific state from which the command sequences will start.
```

--------------------------------

### Instrument a Module with YieldInstrumenter

Source: https://hexdocs.pm/propcheck/PropCheck.Instrument.html

Use this in ExUnit's `setup_all` macro to instrument a specific module before running tests. This ensures that calls within the module are instrumented with yield points.

```elixir
setup_all do
  Instrument.instrument_module(Cache, YieldInstrumenter)
  :ok # no update of a context
end
```

--------------------------------

### Get command names

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.DSL.html

Extracts mfa-tuples from a list of generated commands for aggregation.

```elixir
@spec command_names(cmds :: [command()]) :: [mfa()]
```

--------------------------------

### Retrieve All Counterexamples

Source: https://hexdocs.pm/propcheck/PropCheck.html

Returns a counterexample for each failing property from the most recent module testing run.

```elixir
@spec counterexamples() :: [{mfa(), counterexample()}] | :undefined
```

--------------------------------

### binary()

Source: https://hexdocs.pm/propcheck/PropCheck.BasicTypes-function-binary.html

Generates all binaries, shrinking towards the empty binary.

```APIDOC
## binary()

### Description
Generates all binaries. Instances shrink towards the empty binary, "".

### Specs
`binary() :: type()`
```

--------------------------------

### PropCheck.sample_shrink Function

Source: https://hexdocs.pm/propcheck/PropCheck-function-sample_shrink.html

Demonstrates how to use the sample_shrink function to generate and shrink random data instances, printing each step of the shrinking process.

```APIDOC
## PropCheck.sample_shrink

### Description
Generates a random instance of Type, of size Size, then shrinks it as far as it goes. The value produced on each step of the shrinking process is printed on the screen.

### Method
N/A (Function Call)

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```elixir
PropCheck.sample_shrink(generator, size \\ 10)
```

### Response
#### Success Response (200)
N/A (Prints to screen during execution)

#### Response Example
N/A (Prints to screen during execution)
```

--------------------------------

### PropCheck.FSM.run_commands/3

Source: https://hexdocs.pm/propcheck/PropCheck.FSM-function-run_commands.html

Similar to `run_commands/2`, but also accepts an environment used for symbolic variable evaluation.

```APIDOC
## run_commands/3

### Description
Similar to `run_commands/2`, but also accepts an environment used for symbolic variable evaluation, exactly as described in `PropCheck.StateM.run_commands/3`.

### Method
N/A (Function Call)

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
# Example usage would depend on context and available functions like mod_name(), command_list(), and :proper_symb.var_values()
# PropCheck.FSM.run_commands(mod_name(), command_list(), :proper_symb.var_values())
```

### Response
#### Success Response (200)
- **history** (any) - The history of executed commands.
- **fsm_state** (any) - The final state of the finite state machine.
- **fsm_result** (any) - The result of the command evaluation.

#### Response Example
```json
{
  "history": [...],
  "fsm_state": {...},
  "fsm_result": ...
}
```
```

--------------------------------

### Execute property tests

Source: https://hexdocs.pm/propcheck/PropCheck.html

Define the signatures for quickcheck to run property tests with or without additional options.

```elixir
@spec quickcheck(outer_test()) :: result()
```

```elixir
@spec quickcheck(outer_test(), user_opts()) :: result()
```

--------------------------------

### Test module properties

Source: https://hexdocs.pm/propcheck/PropCheck.html

Define the signature for the module function which executes all exported functions starting with prop_.

```elixir
@spec module(atom(), user_opts()) :: module_result()
```

--------------------------------

### Recursive Tree Generation with let_shrink

Source: https://hexdocs.pm/propcheck/PropCheck-macro-let_shrink.html

Demonstrates generating a recursive tree structure with efficient shrinking using `let_shrink`. The `tree_gen` function defines how to create a tree, with `let_shrink` used to bind `l` and `r` to smaller versions of the tree for shrinking. The `quickcheck` function then verifies a property on generated trees.

```Elixir
iex> use PropCheck
iex> tree_gen = fn (0, _, _) -> :leaf
...>               (s, g, tree) ->
...>      frequency [
...>       {1, tree.(0, g, tree)},
...>       {9, let_shrink([
...>         l <- tree.(div(s, 2), g, tree),
...>         r <- tree.(div(s, 2), g, tree)
...>         ]) do
...>           {:node, g, l, r}
...>         end
...>        }
...>   ]
...> end
iex> tree = fn(g) -> sized(s, tree_gen.(s, g, tree_gen)) end
iex> quickcheck(
...>   forall t <- tree.(int()) do
...>     t == :leaf or is_tuple(t)
...>   end
...>) 
true
```

--------------------------------

### PropCheck.module: module/2

Source: https://hexdocs.pm/propcheck/PropCheck-function-module.html

Tests all properties exported from a module. It looks for 0-arity functions whose names start with 'prop_'.

```APIDOC
## PropCheck.module: module/2

### Description
Tests all properties (i.e., all 0-arity functions whose name begins with `prop_`) exported from module `mod`.

### Method
N/A (This is a function call, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **module_result()**: The result of the property tests.

#### Response Example
N/A
```

--------------------------------

### Run Commands with Environment

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.html

Similar to `run_commands/2`, but also accepts an environment for symbolic variable evaluation. Keys in the environment can be used as symbolic variables within the command sequence.

```Elixir
run_commands(mod, cmds, env)
```

--------------------------------

### Define custom shrinking

Source: https://hexdocs.pm/propcheck/PropCheck.html

Use shrink to provide alternative, simpler generators to guide the shrinking process for a type.

```elixir
    iex> use PropCheck
    iex> quickcheck(
    ...>   forall n <- shrink(pos_integer(), [0]) do
    ...>     rem(n, 2) == 0
    ...>   end)
    false
```

--------------------------------

### PropCheck.counterexamples()

Source: https://hexdocs.pm/propcheck/PropCheck-function-counterexamples.html

Retrieves counterexamples for each failing property from the most recent module testing run.

```APIDOC
## counterexamples()

### Description
Returns a counterexample for each failing property of the most recent module testing run.

### Method
GET

### Endpoint
/websites/hexdocs_pm_propcheck/counterexamples

### Response
#### Success Response (200)
- **counterexamples** (list | :undefined) - A list of tuples, where each tuple contains an MFA (Module, Function, Arity) and a counterexample, or :undefined if no counterexamples exist.
```

--------------------------------

### Retrieve Last Counterexample

Source: https://hexdocs.pm/propcheck/PropCheck.html

Retrieves the simplest counterexample produced by the most recent testing run.

```elixir
@spec counterexample() :: counterexample() | :undefined
```

--------------------------------

### Generate Atom Type

Source: https://hexdocs.pm/propcheck/PropCheck.BasicTypes.html

Generates any atom. Avoids atoms starting with ':$' to prevent clashes. Shrinks towards the empty atom.

```Elixir
@spec atom() :: type()
```

--------------------------------

### Define a proper type

Source: https://hexdocs.pm/propcheck_commons/PropCheckCommons.Network.Telephony.html

This function defines a type for proper generators. No specific setup is required beyond the `proper_type()` function itself.

```elixir
proper_type() :: :proper_types.type()
```

--------------------------------

### initial_state() Callback

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.ModelDSL-callback-initial_state.html

This callback specifies the symbolic initial state of the state machine. It is evaluated at command execution time to produce the actual initial state. The function is called during normal execution, shrinking, and counterexample checking, so it must be deterministic and self-contained.

```APIDOC
## initial_state()

### Description
Specifies the symbolic initial state of the state machine. This state will be evaluated at command execution time to produce the actual initial state. The function is not only called at command generation time, but also in order to initialize the state every time the command sequence is run (i.e. during normal execution, while shrinking and when checking a counterexample). For this reason, it should be deterministic and self-contained.

### Method
N/A (Callback function)

### Endpoint
N/A (Callback function)

### Parameters
None

### Request Example
None

### Response
#### Success Response
- **symbolic_state** (type) - The symbolic initial state of the state machine.
```

--------------------------------

### Combine classical and targeted generators

Source: https://hexdocs.pm/propcheck/PropCheck.TargetedPBT.html

Example of nesting a targeted property within a classical generator to optimize specific data structures.

```elixir
forall maze <- maze_generator() do
  exists p <- path_generator() do
    pos = Maze.follow_path(maze, maze.entry_pos, p)
    uv = distance(pos, maze.exit_pos)
    minimize(uv)
    pos == maze.exit_pos
  end
end
```

--------------------------------

### Sample values using PropCheck.produce

Source: https://hexdocs.pm/propcheck/PropCheck-function-produce.html

Demonstrates generating values from constants and generators like nat() and list(). The function returns a tuple where the second element is the generated value.

```elixir
iex> use PropCheck
iex> produce(1)
{:ok, 1}
iex> nat() |> produce() |> Kernel.elem(1) |> is_integer()
true
iex> nat() |> list() |> produce() |> Kernel.elem(1) |> is_list()
true
```

--------------------------------

### PropCheck.let_shrink Macro Usage

Source: https://hexdocs.pm/propcheck/PropCheck-macro-let_shrink.html

Demonstrates how to use the let_shrink macro for generating and testing recursive data structures with efficient shrinking.

```APIDOC
## PropCheck.let_shrink

### Description
A combination of a `let` and a `shrink` macro. Instances are generated by applying a randomly generated list of values inside `generator` (just like a `let`, with the added constraint that the variables and types must be provided in a list - alternatively, `list_of_types` may be a list or vector type). When shrinking instances of such a type, the sub-instances that were combined to produce it are first tried in place of the failing instance.

### Method
Macro

### Endpoint
N/A (Macro)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
iex> use PropCheck
iex> tree_gen = fn (0, _, _) -> :leaf
...>               (s, g, tree) ->
...>      frequency [
...>       {1, tree.(0, g, tree)},
...>       {9, let_shrink([
...>         l <- tree.(div(s, 2), g, tree),
...>         r <- tree.(div(s, 2), g, tree)
...>         ]) do
...>           {:node, g, l, r}
...>         end
...>        }
...>   ]
...> end
iex> tree = fn(g) -> sized(s, tree_gen.(s, g, tree_gen)) end
iex> quickcheck(
...>   forall t <- tree.(int()) do
...>     t == :leaf or is_tuple(t)
...>   end
...>) 
true
```

### Response
#### Success Response (200)
N/A (Macro execution within quickcheck)

#### Response Example
N/A
```

--------------------------------

### Run Command Sequence with Symbolic Variable Environment

Source: https://hexdocs.pm/propcheck/PropCheck.FSM.html

Similar to run_commands/2, but also accepts an environment for symbolic variable evaluation. This allows for more control over how symbolic variables are handled during execution.

```Elixir
@spec run_commands(mod_name(), command_list(), :proper_symb.var_values()) ::
  {history(), fsm_state(), fsm_result()}
```

--------------------------------

### Derive Generators within a Module

Source: https://hexdocs.pm/propcheck_derive/index.html

Use `PropCheck.Derive` inside a module to automatically generate PropCheck generators for its `@type` definitions. Ensure `:propcheck_derive` application is started.

```elixir
iex> use PropCheck
iex> Application.ensure_all_started(:propcheck_derive)
iex> defmodule Hello do
...> use PropCheck.Derive
...> @type my_type :: integer()
...> end
iex> {:ok, my_type} = produce(Hello.Generate.my_type())
iex> is_integer(my_type)
true
```

--------------------------------

### Get State After Commands

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.html

Returns the symbolic state after executing a command sequence without actually running the commands. Useful for analyzing potential state changes.

```Elixir
state_after(mod, cmds)
```

--------------------------------

### Generate Parallel Test Cases from Specific State

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.html

Generates parallel test cases that always start from a specified initial state. The first command is `{:init, initial_state}`.

```Elixir
parallel_commands(mod, initial_state)
```

--------------------------------

### Define atom type

Source: https://hexdocs.pm/propcheck/PropCheck.BasicTypes-function-atom.html

Use this type to generate all atoms. Avoid using atoms that start with ':$' as they are used internally by PropEr. Instances shrink towards the empty atom.

```elixir
atom() :: type()
```

--------------------------------

### PropCheck.counterexample()

Source: https://hexdocs.pm/propcheck/PropCheck-function-counterexample.html

Retrieves the last (simplest) counterexample produced by PropCheck during the most recent testing run.

```APIDOC
## GET /websites/hexdocs_pm_propcheck/counterexample

### Description
Retrieves the last (simplest) counterexample produced by PropCheck during the most recent testing run.

### Method
GET

### Endpoint
/websites/hexdocs_pm_propcheck/counterexample

### Parameters
#### Query Parameters
- **outer_test** (any) - Required - The outer test case.
- **user_opts** (list) - Optional - A list of user-defined options.

### Response
#### Success Response (200)
- **result** (long_result) - The simplest counterexample found.
```

--------------------------------

### PropCheck.such_that Macro Usage

Source: https://hexdocs.pm/propcheck/PropCheck-macro-such_that.html

Demonstrates how to use the `such_that` macro to define generators that produce values meeting a given condition. It also shows how to integrate these specialized generators with `quickcheck` and utilize options like `:start_size`.

```APIDOC
## PropCheck.such_that Macro

### Description
This macro produces a specialization of a generator, encoded as a binding of form `x <- type`. It generates members of `type` that satisfy the constraint `condition`.

### Method
Macro

### Endpoint
N/A (Macro)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```elixir
use PropCheck
even = such_that n <- nat(), when: rem(n, 2) == 0
quickcheck(
  forall n <- even do
    rem(n, 2) == 0
  end)
```

### Response
#### Success Response (200)
N/A (Macro execution)

#### Response Example
```elixir
true
```

## PropCheck.such_that with Options

### Description
Illustrates the use of `such_that` with the `:start_size` option, which is crucial when constraints might not be met by smaller generated instances.

### Method
Macro

### Endpoint
N/A (Macro)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```elixir
use PropCheck
twofer_list = such_that l <- list(nat()), when: length(l) > 1
quickcheck(
  forall [_ | t] <- twofer_list do
    Enum.any?(t)
  end, [start_size: 2])
```

### Response
#### Success Response (200)
N/A (Macro execution)

#### Response Example
```elixir
true
```
```

--------------------------------

### Implement Command Execution and Arguments

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.DSL.html

Define the `impl/n` function for command execution and `args/1` for generating command arguments. `impl/n` translates SUT results, and `args/1` specifies argument generators.

```elixir
defcommand :find do
  def impl(key), do: Cache.find(key)
  def args(_state), do: [key()]
end
```

--------------------------------

### Derive Generators for an External Module

Source: https://hexdocs.pm/propcheck_derive/index.html

Derive PropCheck generators for types defined in an external module by specifying the module with `use PropCheck.Derive, module: ModuleName`. Ensure `:propcheck_derive` application is started.

```elixir
iex> use PropCheck
iex> Application.ensure_all_started(:propcheck_derive)
iex> use PropCheck.Derive, module: String
iex> {:ok, string} = produce(String.Generate.t())
iex> is_binary(string)
true
```

--------------------------------

### PropCheck.BasicTypes.atom

Source: https://hexdocs.pm/propcheck/PropCheck.BasicTypes-function-atom.html

The 'atom' type in PropCheck generates all possible atoms. It specifies that internal PropEr atoms starting with ':$' should be avoided to prevent clashes, and that instances shrink towards the empty atom ':""'.

```APIDOC
## atom()

### Description
Represents all atoms in Elixir. Internal PropEr atoms starting with ':$' are excluded. Instances shrink towards the empty atom ':""'.

### Method
N/A (Type definition)

### Endpoint
N/A

### Parameters
N/A

### Request Body
N/A

### Response
#### Success Response (Type Definition)
- **type** (type()) - Represents all atoms.

### Response Example
N/A
```

--------------------------------

### Run commands with explicit module

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.DSL-function-run_commands.html

Executes a list of commands using the specified callback module. This is the recommended approach for running commands.

```elixir
run_commands(atom(), [command()]) :: t()
```

--------------------------------

### run_commands/3

Source: https://hexdocs.pm/propcheck/PropCheck.StateM-function-run_commands.html

Evaluates a symbolic command sequence with an environment for symbolic variable resolution.

```APIDOC
## run_commands(mod, cmds, env)

### Description
Similar to `run_commands/2`, but accepts an environment for symbolic variable evaluation during command execution.

### Parameters
- **mod** (module) - Required - The state machine module.
- **cmds** (list) - Required - The symbolic command sequence.
- **env** (list) - Required - A list of `{key, value}` pairs used to replace symbolic variables `{:var, key}` in the command sequence.
```

--------------------------------

### PropCheck.FSM Behavior Overview

Source: https://hexdocs.pm/propcheck/PropCheck.FSM.html

An overview of the PropCheck.FSM behavior, its relation to PropCheck.StateM, and its core concepts.

```APIDOC
## PropCheck.FSM Behavior

### Description
The finite state machine approach for stateful systems, which is closer to Erlang's `gen_fsm` model. This module defines the `proper_fsm` behaviour, useful for testing systems that can be modeled as finite state machines. That is, a finite collection of named states and transitions between them. `PropCheck.FSM` is closely related to `PropCheck.StateM` and is, in fact, implemented in terms of that. Test cases generated using `PropCheck.FSM` will be on precisely the same form as test cases generated using `PropCheck.StateM`. The difference lies in the way the callback modules are specified. The relation between `PropCheck.StateM` and `PropCheck.FSM` is similar to the one between `gen_server` and `gen_fsm` in OTP libraries.

Due to name conflicts with functions automatically imported from `PropCheck.StateM`, a fully qualified call is needed in order to use the API functions of `PropCheck.FSM`.
```

--------------------------------

### defcommand(name, list)

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.DSL-macro-defcommand.html

Defines a new command for the state machine model, including execution logic and state transition callbacks.

```APIDOC
## defcommand(name, list)

### Description
Defines a new command of the model. This macro is deprecated; please use `PropCheck.StateM.ModelDSL` instead.

### Parameters
- **name** (atom) - Required - The name of the command.
- **list** (keyword list) - Required - A list of local functions defining command behavior:
  - **impl(args)** - Required - Defines how the command is executed.
  - **args(state)** - Optional - Defines how arguments are generated based on the current state (default: []).
  - **pre(state, arg_list)** - Optional - Boolean check if the command is allowed in the current state (default: true).
  - **next(old_state, arg_list, result)** - Optional - Defines the next state of the model (default: old_state).
  - **post(old_state, arg_list, result)** - Optional - Boolean check if the system is in the correct state after the call (default: true).
```

--------------------------------

### Define properties with forall/3

Source: https://hexdocs.pm/propcheck/PropCheck.html

Generates values for properties and supports ExUnit assertions.

```elixir
iex> use PropCheck
iex> quickcheck(
...> forall n <- nat() do
...>   n >= 0
...> end)
true
```

```elixir
iex> use PropCheck
iex> quickcheck(
...> forall [n, l] <- [nat(), list(nat())] do
...>   n * Enum.sum(l) >= 0
...> end
...>)
```

```elixir
iex> use PropCheck
iex> quickcheck(
...> forall [n <- nat(), l <- list(nat())] do
...>   n * Enum.sum(l) >= 0
...> end
...>)
```

```elixir
iex> use PropCheck
iex> quickcheck(
...> forall n <- nat() do
...>   assert n < 0
...> end
...>)
false
```

--------------------------------

### Equivalence of Targeted Properties

Source: https://hexdocs.pm/propcheck/PropCheck.TargetedPBT.html

Demonstrates the logical equivalences between `forall_targeted`, `exists`, and `not_exists` macros, mirroring first-order logic quantors.

```elixir
forall_targeted x <- x_gen(), do: p(x)
   <==> not_exists x <- x_gen(), do: not(p(x))

exists x <- x_gen(), do: p(x)
   <==> forall_targeted x <- x_gen(), do: not(p(x))
        |> fails()

not_exists x <- x_gen(), do: p(x)
   <==> forall_targeted x <- x_gen(), do: not(p(x))
```

--------------------------------

### Define Command Postconditions

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.ModelDSL.html

Implement the `post/3` function to verify that the SUT's state after command execution matches the model's expectations. This function compares the actual call result against the expected outcome based on the model state and arguments.

```elixir
defcommand :find do
  def impl(key), do: Cache.find(key)
  def pre(_state, [_key]), do: true
  def next(old_state, _args, _call_result), do: old_state
  def post(entries, [key], call_result) do
    case List.keyfind(entries, key, 0, false) do
        false       -> call_result == {:error, :not_found}
        {^key, val} -> call_result == {:ok, val}
    end
  end
end
```

--------------------------------

### instrument_app/2

Source: https://hexdocs.pm/propcheck/PropCheck.Instrument.html

Instruments all modules of an entire OTP application.

```APIDOC
## instrument_app(app, instrumenter)

### Description
Instruments all modules of an entire OTP application.

### Parameters
- **app** (atom) - Required - The OTP application name.
- **instrumenter** (module) - Required - The module containing instrumentation logic.

### Response
- **:ok** (atom) - Success response.
```

--------------------------------

### Implement Command Postconditions

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.DSL.html

Define the `post/3` function to verify the SUT's state against the model after a command. It checks the `call_result` against the expected model state, ensuring consistency.

```elixir
defcommand :find do
  def impl(key), do: Cache.find(key)
  def args(_state), do: [key()]
  def pre(_state, [_key]), do: true
  def next(old_state, _args, _call_result), do: old_state
  def post(entries, [key], call_result) do
    case List.keyfind(entries, key, 0, false) do
        false       -> call_result == {:error, :not_found}
        {^key, val} -> call_result == {:ok, val}
    end
  end
end
```

--------------------------------

### PropEr Property for Testing Process Dictionary

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.html

This property uses PropEr's `commands/1` generator to create symbolic command sequences and `run_commands/2` to execute them, ensuring the system behaves as expected. Includes cleanup code to maintain test isolation.

```Elixir
def prop_pdict() do
  forall cmds <- commands(__MODULE__) do
    {_history, _state, result} = run_commands(__MODULE__, cmds)
    cleanup()
    result == ok
  end
end
```

--------------------------------

### compile_module/3

Source: https://hexdocs.pm/propcheck/PropCheck.Instrument-function-compile_module.html

Compiles the abstract code of a module and loads it immediately into the VM.

```APIDOC
## compile_module(mod, filename, code)

### Description
Compiles the abstract code of a module and loads it immediately into the VM.

### Parameters
- **mod** (atom) - Required - The module name to be compiled.
- **filename** (string) - Required - The filename associated with the source code.
- **code** (term) - Required - The abstract code of the module.
```

--------------------------------

### Using `exists` Macro

Source: https://hexdocs.pm/propcheck/PropCheck.TargetedPBT.html

The `exists` macro uses PropEr's targeted PBT to find at least one instance that satisfies a given property. No counterexample is provided if no such instance is found.

```elixir
exists(arg, list)
```

--------------------------------

### Counterexample Management

Source: https://hexdocs.pm/propcheck/PropCheck.html

Functions to retrieve and re-check counterexamples from failed property tests.

```APIDOC
## counterexample()

### Description
Retrieves the last (simplest) counterexample produced by PropCheck during the most recent testing run.

## check(outer_test, cexm, user_opts)

### Description
Re-checks a specific counterexample `cexm` against the property `outer_test` that it previously falsified.

### Parameters
#### Arguments
- **outer_test** (term) - Required - The property to re-check.
- **cexm** (counterexample) - Required - The counterexample to test.
- **user_opts** (list) - Optional - Additional options.
```

--------------------------------

### Define Command Preconditions

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.ModelDSL.html

Implement the `pre/2` function to define the conditions under which a command is allowed to execute, based on the current model state and generated arguments. If omitted, the default implementation always returns true.

```elixir
defcommand :find do
  def impl(key), do: Cache.find(key)
  def pre(_state, [_key]), do: true
end
```

--------------------------------

### PropCheck.StateM.DSL.commands (Deprecated)

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.DSL-function-commands.html

This function is deprecated. Use `PropCheck.StateM.ModelDSL` instead.

```APIDOC
## commands(mod)

### Description
Generates the command list for the given module.

### Method
N/A (Function signature)

### Endpoint
N/A (Function signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **commands** (PropCheck.BasicTypes.type()) - The generated command list.

#### Response Example
None

### Deprecation Note
This function and its module are deprecated. Please use `PropCheck.StateM.ModelDSL` instead.
```

--------------------------------

### commands/1

Source: https://hexdocs.pm/propcheck/PropCheck.StateM-function-commands.html

Generates random command sequences based on an abstract state machine specification provided by a callback module. The initial state is computed by `mod:initial_state/0`.

```APIDOC
## commands/1

### Description
A special PropEr type which generates random command sequences, according to an abstract state machine specification. The function takes as input the name of a callback module, which contains the state machine specification. The initial state is computed by `mod:initial_state/0`.

### Method
N/A (Function signature)

### Endpoint
N/A (Function signature)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### defcommand/2

Source: https://hexdocs.pm/propcheck/PropCheck.StateM.ModelDSL.html

Macro to define a new command for the state machine model.

```APIDOC
## defcommand(name, list)

### Description
Defines a new command of the model, including execution logic and state transitions.

### Parameters
- **name** (atom) - Required - The name of the command.
- **list** (list) - Required - A list of local functions defining the command behavior:
  - **impl(...)**: Required, defines how the command is executed.
  - **pre(state, arg_list)**: Optional, checks if the command is allowed in the current state.
  - **next(old_state, arg_list, result)**: Optional, defines the next state of the model.
  - **post(old_state, arg_list, result)**: Optional, verifies the system state after the call.
```
Tokens:
Raw