Supposition.jl

https://seelengrab.github.io/Supposition.jl/dev/
Admin
Supposition.jl is a property-based testing framework for Julia inspired by Hypothesis, featuring...
Tokens:52,503
Snippets:639
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Generate Multiple Examples with Data Integers

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Example usage of the `example` function to generate multiple integers within a specified range.

```julia
julia> using Supposition, Supposition.Data

julia> is = Data.Integers(0, 10);

julia> example(is, 10)
10-element Vector{Int64}:
  9
  1
  4
  4
  7
  4
  6
 10
  1
  8
```

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

### Directory-Based Example Database

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

An ExampleDB implementation that stores examples as files within a specified directory.

```julia
DirectoryDB <: ExampleDB
```

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

### Generate Example with Data Integers

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Example usage of the `example` function with `Data.Integers` to generate a single integer within a specified range.

```julia
julia> using Supposition, Supposition.Data

julia> example(Data.Integers(0, 10))
7
```

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

### No-Record Example Database

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

An ExampleDB that performs no recording and retrieves no data, effectively disabling example persistence.

```julia
NoRecordDB <: ExambleDB
```

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

### Supposition.example (multiple generations)

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Generates multiple examples for a given `Possibility`. Each example is given a specified number of attempts to generate. The process aborts if any example generation fails. This function is for interactive use and the generated data does not shrink.

```APIDOC
## Supposition.example (multiple generations)

### Description
Generate `n` examples for the given `Possibility`. Each example is given `tries` attempts to generate. If any fail, the entire process is aborted. Usage: This function is for interactive introspection to see what a `Possibility` produces - do not use this to create examples from a `Possibility` in e.g. `@composed`, since the data generated by `example` will not shrink. For this purpose, use `produce!` instead.

### Method
`example`

### Signature
`example(gen::Possibility, n::Integer; tries=100_000)`

### Example
```julia
using Supposition, Supposition.Data

is = Data.Integers(0, 10)
example(is, 10)
```

### Returns
A vector of example values generated by the `Possibility`.
```

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

### Generate Multiple Examples from Possibility

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Generates multiple examples for a given Possibility, with each example having a specified number of tries. This is for interactive use and the generated data does not shrink.

```julia
example(gen::Possibility, n::Integer; tries=100_000)
```

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

### Supposition.example (single)

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Generates a single example for a given Possibility.

```APIDOC
## Supposition.example

### Description
Generate an example for the given `Possibility`.

`example` tries to have `pos` produce an example `tries` times and throws an error if `pos` doesn't produce one in that timeframe. `generation` indicates how "late" in a usual run of `@check` the example might have been generated.

Usage
This function is for interactive introspection to see what a `Possibility` produces - do not use this to create examples from a `Possibility` in e.g. `@composed`, since the data generated by `example` will not shrink.

For this purpose, use `produce!` instead.

### Method
example(pos::Possibility; tries=100_000, generation::Int)

### Request Example
```julia
using Supposition, Supposition.Data

example(Data.Integers(0, 10))
```

### Response Example
```
7
```
```

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

### Supposition.example (multiple)

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Generates multiple examples for a given Possibility.

```APIDOC
## Supposition.example

### Description
Generate `n` examples for the given `Possibility`. Each example is given `tries` attempts to generate. If any fail, the entire process is aborted.

Usage
This function is for interactive introspection to see what a `Possibility` produces - do not use this to create examples from a `Possibility` in e.g. `@composed`, since the data generated by `example` will not shrink.

For this purpose, use `produce!` instead.

### Method
example(gen::Possibility, n::Integer; tries=100_000)

### Request Example
```julia
using Supposition, Supposition.Data

is = Data.Integers(0, 10)

example(is, 10)
```

### Response Example
```julia
10-element Vector{Int64}:
  9
  1
  4
  4
  7
  4
  6
 10
  1
  8
```
```

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

### Supposition.example (single generation)

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Generates a single example for a given `Possibility`. It attempts to produce an example a specified number of times and throws an error if it fails. This function is for interactive use and the generated data does not shrink.

```APIDOC
## Supposition.example (single generation)

### Description
Generate an example for the given `Possibility`. `example` tries to have `pos` produce an example `tries` times and throws an error if `pos` doesn't produce one in that timeframe. `generation` indicates how "late" in a usual run of `@check` the example might have been generated. Usage: This function is for interactive introspection to see what a `Possibility` produces - do not use this to create examples from a `Possibility` in e.g. `@composed`, since the data generated by `example` will not shrink. For this purpose, use `produce!` instead.

### Method
`example`

### Signature
`example(pos::Possibility; tries=100_000, generation::Int)`

### Example
```julia
using Supposition, Supposition.Data

example(Data.Integers(0, 10))
```

### Returns
An example value generated by the `Possibility`.
```

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

### Get Generation Time Mean

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the mean time in seconds for generating an example, including early rejections.

```julia
gentime_mean(::Stats) -> Float64
```

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

### Generate Single Example from Possibility

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Generates a single example for a given Possibility, with a specified number of tries. This is for interactive use and the generated data does not shrink.

```julia
example(pos::Possibility; tries=100_000, generation::Int)
```

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

### Retrieve accepted example count

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

The `acceptions` method retrieves the total number of examples accepted by the property, indicating how often the property returned `true`.

```Julia
acceptions(::Stats) -> Int
```

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

### Generate Large String with PropCheck.jl

Source: https://seelengrab.github.io/Supposition.jl/dev/benchmarks.html

Generates a string of one million characters using PropCheck.jl. This example demonstrates the setup for benchmarking large string generation.

```julia
julia> strgen = PropCheck.str(PropCheck.iconst(1_000_000));

julia> @benchmark root(PropCheck.generate(strgen))
```

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

### generate

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Attempts to generate an example that falsifies the property given to the TestState.

```APIDOC
## generate ts::TestState

### Description
Try to generate an example that falsifies the property given to `ts`.

### Method
`generate`

### Parameters
- **ts** (TestState) - The current test state.
```

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

### Supposition.consider

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Determines if a given set of choices is a conceivable example for a test case.

```APIDOC
## Supposition.consider

### Description
Returns whether the given choices are a conceivable example for the testcase given by `ts`.

### Method
consider(ts::TestState, attempt::Attempt) -> Bool
```

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

### Check Configuration Options

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Use `CheckConfig` to set initial configuration for `@check` invocations, including RNG, maximum examples, recording, verbosity, and broken status.

```julia
using Supposition

# Example usage (assuming CheckConfig is used within @check)
# config = CheckConfig(max_examples=100, verbose=true)
```

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

### Get Rejections Count

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the total number of examples rejected by the property (i.e., how often an input was `reject!`ed).

```julia
rejections(::Stats) -> Int
```

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

### Get Generation Time Variance

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the variance of the time in seconds for generating an example, including early rejections.

```julia
gentime_variance(::Stats) -> Float64
```

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

### Guide Fuzzing with `target!` using Absolute Distance

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/target.html

Uses `target!` to guide fuzzing by scoring inputs based on their negative absolute distance to the random goal. This helps Supposition.jl find the counterexample more efficiently.

```julia
sr = @check rng=Xoshiro(1) function israndgoal(f=Data.Floats{Float64}())
    # negative absolute distance, because we want to _minimize_ the distance
    target!(-abs(rand_goal - f))
    f != rand_goal
end
```

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

### Example Choice Sequence for Integer Generation

Source: https://seelengrab.github.io/Supposition.jl/dev/glossary.html

Illustrates a possible choice sequence recorded when generating an integer within a specified range using Data.Integers. The sequence represents the internal choices made during generation.

```text
UInt[ 0x5 ]
```

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

### Supposition.gentime_mean

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Retrieve the mean time in seconds of generating an example. This counts any attempt at generating an example, including early rejections.

```APIDOC
## Supposition.gentime_mean

### Description
Retrieve the mean time in seconds of generating an example. This counts any attempt at generating an example, including early rejections.

### Method
`gentime_mean(::Stats) -> Float64`
```

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

### Configure Check Invocation

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Initializes configuration for a `@check` invocation, allowing customization of RNG, example limits, recording, verbosity, and more.

```julia
CheckConfig(;options...)
```

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

### Supposition.acceptions

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Retrieve the total number of examples that were accepted by the property, i.e. how often the property returned `true`.

```APIDOC
## Supposition.acceptions

### Description
Retrieve the total number of examples that were accepted by the property, i.e. how often the property returned `true`.

### Method
`acceptions(::Stats) -> Int`
```

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

### reject!

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Rejects the current testcase as invalid, meaning the generated example should not be considered a valid counterexample. Can be called during test case examination or example generation.

```APIDOC
## reject!()

### Description
Reject the current testcase as invalid, meaning the generated example should not be considered as producing a valid counterexample. This can only be called while a testcase is currently being examined or an example for a `Possibility` is being actively generated. It is ok to call this inside of `@composed` or `@check`, as well as any functions called from one of those places.

### Method
`reject!`
```

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

### Julia Implementation for RGB to 8-bit Color

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/events.html

This Julia code implements the same RGB to 8-bit color mapping as the C example. It uses inner helper functions and Julia's syntax for ranges and conditional expressions. Note the explicit type conversions and indexing adjustments.

```julia
function termcolor8bit(r::UInt8, g::UInt8, b::UInt8)
    # Magic numbers? Lots.
    cdistsq(r1, g1, b1) = (r1 - r)^2 + (g1 - g)^2 + (b1 - b)^2
    to6cube(value) = (value - 35) ÷ 40
    from6cube(r6, g6, b6) = 16 + 6^2 * r6 + 6^1 * g6 + 6^0 * b6
    sixcube = (0, 95:40:255...)
    r6cube, g6cube, b6cube = to6cube(r), to6cube(g), to6cube(b)
    rnear, gnear, bnear = sixcube[r6cube+1], sixcube[g6cube+1], sixcube[b6cube+1]
    colorcode = if r == rnear && g == gnear && b == bnear
        from6cube(r6cube, g6cube, b6cube)
    else
        grey_avg = Int(r + g + b) ÷ 3
        grey_index = if grey_avg > 238 23 else (grey_avg - 3) ÷ 10 end
        grey = 8 + 10 * grey_index
        if cdistsq(grey, grey, grey) <= cdistsq(rnear, gnear, bnear)
            16 + 6^3 + grey_index
        else
            from6cube(r6cube, g6cube, b6cube)
        end
    end
    UInt8(colorcode)
end
```

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

### rejections

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the total number of examples rejected by the property (i.e., how often an input was `reject!`ed).

```APIDOC
## rejections ::Stats -> Int

### Description
Retrieve the total number of examples that were rejected by the property, i.e. how often an input was `reject!`ed.

### Method
`rejections`

### Returns
- **Int** - The total number of rejections.
```

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

### Generate Test Case

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Attempts to generate an example that falsifies the property given to ts.

```julia
generate(ts::TestState)
```

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

### Supposition.rejections

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Retrieve the total number of examples that were rejected by the property, i.e. how often an input was `reject!`ed.

```APIDOC
## Supposition.rejections

### Description
Retrieve the total number of examples that were rejected by the property, i.e. how often an input was `reject!`ed.

### Method
`rejections(::Stats) -> Int`
```

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

### Consider Choices in TestState

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Checks if the given choices are a conceivable example for the testcase. This method is part of the `Supposition` API.

```julia
consider(ts::TestState, attempt::Attempt) -> Bool
```

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

### gentime_mean

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the mean time in seconds of generating an example. This counts all attempts, including early rejections.

```APIDOC
## gentime_mean ::Stats -> Float64

### Description
Retrieve the mean time in seconds of generating an example. This counts any attempt at generating an example, including early rejections.

### Method
`gentime_mean`

### Returns
- **Float64** - The mean generation time in seconds.
```

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

### Supposition.CheckConfig

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

A struct to hold configuration options for the `@check` macro, including settings for random number generation, maximum examples, recording, verbosity, and timeouts.

```APIDOC
## CheckConfig(; options...)

### Description
A struct holding the initial configuration for an invocation of `@check`.

### Method
`CheckConfig` constructor

### Parameters
#### Keyword Arguments
- **rng** (Random.AbstractRNG) - The initial RNG object. Defaults to a copyable `Random.AbstractRNG`.
- **max_examples** (Int) - The maximum number of examples allowed. `-1` means infinite. Defaults to `10_000`.
- **record** (Bool) - Whether the result should be recorded. Defaults to `true`.
- **verbose** (Bool) - Whether printing should be verbose. Defaults to `false`.
- **broken** (Bool) - Whether the invocation is expected to fail. Defaults to `false`.
- **db** (ExampleDB) - An `ExampleDB` for recording failure cases. Defaults to `default_directory_db()`.
- **buffer_size** (Int) - The default maximum buffer size. Defaults to `100_000`.
- **timeout** (Dates.TimeType or Nothing) - The maximum amount of time `@check` attempts new examples for. Defaults to `nothing`.

### Request Example
```julia
config = CheckConfig(max_examples=100, timeout=Second(10))
```

### Response
#### Success Response (200)
- **CheckConfig** - An instance of the CheckConfig struct.
```

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

### Supposition.reject!

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Rejects the current testcase as invalid, meaning the generated example should not be considered as producing a valid counterexample.

```APIDOC
## Supposition.reject!

### Description
Reject the current testcase as invalid, meaning the generated example should not be considered as producing a valid counterexample.

### Method
`reject!()`
```

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

### CheckConfig

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Configuration options for the `@check` macro, controlling aspects like random number generation, example limits, and verbosity.

```APIDOC
## Type: CheckConfig

### Description
A struct holding the initial configuration for an invocation of `@check`.

### Parameters
- `rng`: The initial RNG object given to `@check`. Defaults to a copyable `Random.AbstractRNG`.
- `max_examples`: The maximum number of examples allowed to be drawn with this config. `-1` means infinite drawing (careful!). Defaults to `10000`.
- `record`: Whether the result should be recorded in the parent testset, if there is one. Defaults to `true`.
- `verbose`: Whether the printing should be verbose, i.e. print even if it's a `Pass`. Also shows statistics if enabled. Defaults to `false`.
- `broken`: Whether the invocation is expected to fail. Defaults to `false`.

### Example
```julia
# Example usage would involve passing this to @check, e.g.:
# @check my_function(x) --config CheckConfig(max_examples=100, verbose=true)
```
```

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

### Supposition.assume! Method (precondition)

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

If this precondition is not met, abort the test and mark the currently running testcase as invalid. This can only be called while a testcase is currently being examined or an example for a `Possibility` is being actively generated.

```APIDOC
## assume!(precondition::Bool)

### Description
If this precondition is not met, abort the test and mark the currently running testcase as invalid.

### Callability
This can only be called while a testcase is currently being examined or an example for a `Possibility` is being actively generated. It is ok to call this inside of `@composed` or `@check`, as well as any functions called from one of those places.
```

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

### Generate Recursive JSON-like Objects

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/recursive.html

Constructs a recursive Possibility for JSON-like data up to a specified maximum depth and generates an example. Ensure `basecase` and `jsonwrap` are defined.

```julia
json = Data.Recursive(basecase, jsonwrap; max_layers=3)
example(json)
```

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

### Supposition.Data.produce! Method

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Produces a value from the given `Possibility`, recording the required choices in the currently active `TestCase`. This can only be called while a testcase is currently being examined or an example for a `Possibility` is being actively generated.

```APIDOC
## produce!(p::Possibility{T}) -> T

### Description
Produces a value from the given `Possibility`, recording the required choices in the currently active `TestCase`.

### Callability
This can only be called while a testcase is currently being examined or an example for a `Possibility` is being actively generated. It is ok to call this inside of `@composed` or `@check`, as well as any functions called from one of those places.
```

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

### ExampleDB

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Abstract type representing a database of previous counterexamples. Users must implement methods for record management and retrieval.

```APIDOC
## Type: `ExampleDB`

### Description
An abstract type representing a database of previous counterexamples.

### Required Methods
* `records(::ExampleDB)`: Returns an iterable of all currently recorded counterexamples.
* `record!(::ExampleDB, key, value)`: Record the counterexample `value` under the key `key`.
* `retrieve(::ExampleDB, key)::Option`: Retrieve the previously recorded counterexample stored under `key`. Return `nothing` if no counterexample was stored under that key.
```

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

### Supposition.gentime_variance

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Retrieve the variance of the time in seconds of generating an example. This counts any attempt at generating an example, including early rejections.

```APIDOC
## Supposition.gentime_variance

### Description
Retrieve the variance of the time in seconds of generating an example. This counts any attempt at generating an example, including early rejections.

### Method
`gentime_variance(::Stats) -> Float64`
```

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

### Counterexample for Broken Pop!

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/stateful.html

Illustrates a minimal counterexample found by Supposition.jl for the `test_pop_in_sorted_order` function, highlighting the incorrect sorting of popped elements due to the faulty `pop!` implementation.

```julia
Found counterexample
  Context: test_pop_in_sorted_order

  Arguments:
      ls::Vector{UInt8} = UInt8[0x00, 0x01, 0x00]
```

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

### Implement Heap Operations (isempty, push!, pop!)

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/stateful.html

Provides implementations for `isempty`, `push!`, and `pop!` for the Heap struct. Note that the initial `pop!` implementation does not rebalance the heap, potentially leading to invalid states.

```julia
Base.isempty(heap::Heap) = isempty(heap.data)

function Base.push!(heap::Heap{T}, value::T) where T
    data = heap.data
    push!(data, value)
    index = lastindex(data)
    while index > firstindex(data)
        parent = index >> 1
        if data[parent] > data[index]
            data[parent], data[index] = data[index], data[parent]
            index = parent
        else
            break
        end
    end
    heap
end

Base.pop!(heap::Heap) = popfirst!(heap.data)
```

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

### Supposition.Timeout Type

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Indicates that a test timed out before any examples could be executed.

```julia
Timeout
```

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

### ExampleDB Type Definition

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

An abstract type representing a database of previous counterexamples. Implementers must define `records`, `record!`, and `retrieve`.

```julia
ExampleDB
```

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

### Compare Oracle and Ported Implementation

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/events.html

Compares the output of the `tmux_8bit_oracle` function with a local implementation `termcolor8bit` for specific RGB values.

```julia
tmux_8bit_oracle(0x4, 0x2, 0x3)
```

```julia
termcolor8bit(0x4, 0x2, 0x3)
```

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

### Get Runtime Variance

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the variance of the runtime in seconds of the property under test.

```julia
runtime_variance(::Stats) -> Float64
```

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

### Supposition.counterexample

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the counterexample found during execution, if any.

```APIDOC
## Supposition.counterexample

### Description
Return the counterexample found during execution as a `Some`, if any exists. Otherwise, `nothing` is returned.

The counterexample itself is a tuple of the objects passed as arguments to the property. For example, a property `f(::Float64)` would have a counterexample of type `Tuple{Float64}`.

### Method
counterexample(::SuppositionReport) -> Option
```

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

### Get Runtime Mean

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the mean runtime in seconds of the property under test.

```julia
runtime_mean(::Stats) -> Float64
```

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

### Define Stateful Heap Test with Precondition

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/stateful.html

Sets up a stateful test function `test_heap` using Supposition.jl. It incorporates generated push and pop operations and includes a precondition to handle empty heap scenarios gracefully.

```julia
@check function test_heap(ops = gen_ops)
```

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

### Retrieve counterexample from SuppositionReport

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

The `counterexample` method returns the counterexample found during the execution of a `SuppositionReport` as a `Some` value. If no counterexample is found, it returns `nothing`. The counterexample is a tuple of the arguments passed to the property.

```julia
counterexample(::SuppositionReport) -> Option
```

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

### Get Possibility Type with Supposition.Data.postype

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Returns the type of objects that a Possibility object will generate.

```julia
postype(::P) where P <: Possibility
```

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

### Initialize Integer Generator

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/basic.html

Sets up a generator for unsigned integers using Supposition.jl's Data module. This generator will be used as input for testing properties.

```julia
using Supposition, Supposition.Data

intgen = Data.Integers{UInt}()
```

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

### Create TestCase from Choices

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Creates a `TestCase` for a given set of known choices. Allows specifying a random number generator.

```julia
for_choices(prefix; rng=Random.default_rng())
```

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

### Get Improvements Count

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the total number of improvements made due to calls to `target!`.

```julia
improvements(::Stats) -> Int
```

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

### Compose a new generator

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Demonstrates composing a new generator by combining an existing function with specific arguments.

```Julia
my_func(str, number) = number * "? " * str
ask_number = @composed my_func(text, num)
```

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

### Get Possibility Type from Type with Supposition.Data.postype

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Returns the type of objects that a Possibility type will generate.

```julia
postype(::Type{P<:Possibility})
```

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

### Get Type of Possibility Output

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Returns the type of objects that a Possibility object or type will generate.

```julia
postype(::P) where P <: Possibility
postype(::Type{P<:Possibility})
```

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

### PropCheck.jl: Naive even number filtering

Source: https://seelengrab.github.io/Supposition.jl/dev/benchmarks.html

Demonstrates a naive approach to filtering even numbers with PropCheck.jl, which can lead to very long sampling times and high memory usage.

```julia
julia> evengen = PropCheck.vector(PropCheck.iconst(1_000_000), PropCheck.filter(iseven, PropCheck.itype(Int)));

julia> @benchmark root(PropCheck.generate(evengen))
BenchmarkTools.Trial: 1 sample with 1 evaluation.
 Single result which took 37.428 s (24.58% GC) to evaluate,
 with a memory estimate of 50.67 GiB, over 220777721 allocations.

```

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

### gentime_variance

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the variance of the time in seconds of generating an example. This counts all attempts, including early rejections.

```APIDOC
## gentime_variance ::Stats -> Float64

### Description
Retrieve the variance of the time in seconds of generating an example. This counts any attempt at generating an example, including early rejections.

### Method
`gentime_variance`

### Returns
- **Float64** - The variance of the generation time in seconds.
```

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

### target!

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Updates the currently running testcase to track the given score as its target. The score must be convertible to a Float64. This score can only be set once.

```APIDOC
## target!(score)

### Description
Update the currently running testcase to track the given score as its target. `score` must be `convert`ible to a `Float64`. This score can only be set once! Repeated calls will be ignored.

### Method
`target!`

### Parameters
- **score** - The target score to set (convertible to Float64).
```

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

### PropCheck.jl: Filtered even numbers with mapping

Source: https://seelengrab.github.io/Supposition.jl/dev/benchmarks.html

Benchmarks filtering even numbers after mapping with PropCheck.jl, showing a significant improvement over the naive approach but still considerable resource usage.

```julia
julia> evengen = PropCheck.vector(PropCheck.iconst(1_000_000), PropCheck.filter(iseven, PropCheck.map(x -> 2x, PropCheck.itype(Int))));

julia> @benchmark root(PropCheck.generate(evengen))
BenchmarkTools.Trial: 1 sample with 1 evaluation.
 Single result which took 8.756 s (21.85% GC) to evaluate,
 with a memory estimate of 9.63 GiB, over 45284301 allocations.

```

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

### Supposition.assemble Method

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Assembles `sign`, `expo` and `frac` arguments into the floating point number of type `T` it represents. `sizeof(T)` must match `sizeof(I)`.

```APIDOC
## assemble(::T, sign::I, expo::I, frac::I) where {I, T <: Union{Float16, Float32, Float64}} -> T

### Description
Assembles `sign`, `expo` and `frac` arguments into the floating point number of type `T` it represents. `sizeof(T)` must match `sizeof(I)`.
```

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

### Supposition.jl String Generation and Check

Source: https://seelengrab.github.io/Supposition.jl/dev/benchmarks.html

This snippet illustrates generating a large string with Supposition.jl and checking a property. It includes the execution time and the identification of a counterexample.

```julia
julia> strgen = Data.Text(Data.Characters(); min_len=1000, max_len=1000);

julia> @time @check db=false isempty(strgen)
  0.687378 seconds (647.30 k allocations: 596.830 MiB, 4.61% gc time, 7.56% compilation time: 8% of which was recompilation)
Found counterexample
  Context: isempty

  Arguments:
      arg_1::String = "\0\0\0\0\0\0\0\0\0...
```

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

### Get Shrinks Count

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the total number of times a counterexample was successfully shrunk to a smaller one.

```julia
shrinks(::Stats) -> Int
```

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

### Define and Call a Function with Named Arguments and Type Annotations

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Define a function 'build_sentence' that accepts a string 'a' and a float 'num', returning an interpolated string. This demonstrates named arguments, type annotations, and string interpolation. Call the function with specific values.

```Julia
sentence = @composed build_sentence(a = text, num = Data.Floats{Float16}()) -> "The $a is $num!"
build_sentence("foo", 0.5) # returns "The foo is 0.5!"
```

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

### Supposition.@check

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

The main way to declare and run a property-based test. It accepts options and a function to test.

```APIDOC
## Supposition.@check

### Description
The main way to declare & run a property based test. Called like so:
```julia
using Supposition, Supposition.Data

Supposition.@check [options...] function foo(a = Data.Text(Data.Characters(); max_len=10))
          length(a) > 8
       end
```

### Supported Options
Passed as `key=value`:
  * `rng::Random.AbstractRNG`: Pass an RNG to use. Defaults to a copyable `Random.AbstractRNG`.
  * `max_examples::Int`: The maximum number of generated examples that are passed to the property.
  * `broken::Bool`: Mark a property that should pass but doesn't as broken, so that failures are not counted.
  * `record::Bool`: Whether the result of the invocation should be recorded with any parent testsets.
  * `db`: Either a Boolean (`true` uses a fallback database, `false` stops recording examples) or an `ExampleDB`.
  * `timeout`: The maximum amount of time `@check` attempts new examples for. Expects a `Dates.TimeType`, can be disabled by setting to `nothing`.
  * `config`: A `CheckConfig` object that will be used as a default for all previous options. Options that are passed explicitly to `@check` will override whatever is provided through `config`.

### Arguments
The arguments to the given function are expected to be `Possibilities`. The names they are bound to are the names the generated object will have in the test. These arguments will be shown should the property fail!

### Reusing existing properties
If you already have a predicate defined, you can also use the calling syntax in `@check`. Here, the generator is passed purely positionally to the given function; no argument name is necessary.
```julia
using Supposition, Supposition.Data

isuint8(x) = x isa UInt8

intgen = Data.Integers{UInt8}()

Supposition.@check isuint8(intgen)
```

### Passing a custom RNG
It is possible to optionally give a custom RNG object that will be used for random data generation. If none is given, `Xoshiro(rand(Random.RandomDevice(), UInt))` is used instead.
```julia
using Supposition, Supposition.Data, Random

# use a custom Xoshiro instance
Supposition.@check rng=Xoshiro(1234) function foo(a = Data.Text(Data.Characters(); max_len=10))
          length(a) > 8
       end
```

**Hardware RNG**
Be aware that you _cannot_ pass a hardware RNG to `@check` directly. If you want to randomize based on hardware entropy, seed a copyable RNG like `Xoshiro` from your hardware RNG and pass that to `@check` instead. The RNG needs to be copyable for reproducibility.

### Additional Syntax
In addition to passing a whole `function` like above, the following syntax are also supported:
```julia
text = Data.Text(Data.AsciiCharacters(); max_len=10)

# If no name is needed, use an anonymous function
@check (a = text) -> a*a
@check (a = text,) -> "foo: "*a
@check (a = text, num = Data.Integers(0,10)) -> a^num

# ..or give the anonymous function a name too - works with all three of the above
@check build_sentence(a = text, num = Data.Floats{Float16}()) -> "The $a is $num!"
build_sentence("foo", 0.5) # returns "The foo is 0.5!"
```

### Replayability
While you can pass an anonymous function to `@check`, be aware that doing so may hinder replayability of found test cases when surrounding invocations of `@check` are moved. Only named functions are resistant to this.
```

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

### Increase Fuzzing Attempts

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/target.html

Increases the maximum number of examples Supposition.jl will attempt to feed to the `israndgoal` function to 1,000,000.

```julia
@check max_examples=1_000_000 rng=Xoshiro(1) israndgoal(Data.Floats{Float64}())
```

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

### Sampling from String using WeightedSample

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

To sample from a String, collect it into a Vector{Char} first because Strings use variable-length UTF-8 encoding and are not arbitrarily indexable in constant time.

```julia
bs = Data.WeightedSample(collect("foobarbaz"), [3.0, 1.0, 1.0, 3.0, 1.0, 1.0, 3.0, 1.0, 1.0]);

example(bs, 10)
```

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

### Supposition.jl Integer Generation and Check

Source: https://seelengrab.github.io/Supposition.jl/dev/benchmarks.html

This snippet shows how to generate a large vector of integers with Supposition.jl and check a property. It measures the execution time and reports a counterexample found.

```julia
julia> intgen = Data.Vectors(Data.Integers{Int}(); min_size=1000, max_size=1000);

julia> @time @check db=false isempty(intgen)
  0.429625 seconds (567.42 k allocations: 657.697 MiB, 8.21% gc time, 1.27% compilation time: 5% of which was recompilation)
Found counterexample
  Context: isempty

  Arguments:
      arg_1::Vector{Int64} = [-9223372036854775808, -9223372036854775808, ...
```

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

### Get Invocations Count

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Retrieves the total number of times the property was invoked with an input. This may be less than `attempts` if inputs are rejected before invocation.

```julia
invocations(::Stats) -> Int
```

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

### Supposition.assume! Method (TestCase)

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Reject this `TestCase` if `precondition` is `false`.

```APIDOC
## assume!(::TestCase, precondition::Bool)

### Description
Reject this `TestCase` if `precondition` is `false`.
```

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

### Reject current testcase

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Reject the current testcase as invalid, meaning the generated example should not be considered a valid counterexample. Usable within @composed or @check.

```julia
reject!()
```

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

### Supposition.jl Map Generation and Check

Source: https://seelengrab.github.io/Supposition.jl/dev/benchmarks.html

This snippet shows the generation of a large vector of mapped integers using Supposition.jl and checking a property. It details the performance metrics and the found counterexample.

```julia
julia> mapgen = Data.Vectors(map(x -> 2x, Data.Integers{Int}()); min_size=1000, max_size=1000);

julia> @time @check db=false isempty(mapgen)
  0.427833 seconds (587.02 k allocations: 658.673 MiB, 7.52% gc time, 3.96% compilation time: 2% of which was recompilation)
Found counterexample
  Context: isempty

  Arguments:
      arg_1::Vector{Int64} = [0, 0, 0, 0, ...
```

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

### Define a Predicate Function in Julia

Source: https://seelengrab.github.io/Supposition.jl/dev/intro.html

This function defines a predicate that returns a boolean based on input conditions. It serves as an example for demonstrating PBT principles.

```julia
function foo(a::Int, b::Int)
    a < 5 && return false
    b < 5 && return false
    return true
end
```

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

### Sampling from a Collection

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Creates a Possibility that samples uniformly from a given collection. Handles potential issues with mutable data and provides guidance for sampling from Strings.

```APIDOC
## `Supposition.Data.SampledFrom`

### Description
A `Possibility` for sampling uniformly from `collection`. `collection`, as well as its `eachindex`, is assumed to be indexable.

**Mutable Data**: The source objects from the collection given to this `SampledFrom` is not copied when `produce!` is called. Be careful with mutable data!

**Sampling from `String`**: To sample from a `String`, you can `collect` the string first to get a `Vector{Char}`. This is necessary because `String`s use the variable-length UTF-8 encoding, which isn't arbitrarily indexable in constant time.

### Parameters
- `collection`: The collection to sample from. Must be indexable.

### Examples
```julia
using Supposition

sampler = Data.SampledFrom([1, 1, 1, 2])
println(example(sampler, 4))
```
```

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

### Get statistics from SuppositionReport

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

The `statistics` function queries a `SuppositionReport` object to retrieve collected statistics about the test execution. This is useful for analyzing test results.

```julia
statistics(::SuppositionReport) -> Stats
```

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

### Check if Generation Should Continue

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Determines if `ts` should continue generating new test cases. Returns `true` if the property is not trivial, there is room for more examples, and the timeout has not been reached.

```julia
should_keep_generating(ts::TestState)
```

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

### Defining Heap Operations for Testing

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/stateful.html

Defines a sequence of operations to be performed on a heap for testing purposes. This includes pushing elements and popping them, simulating real-world usage.

```julia
ops = Union{Tuple{typeof(pop!), Nothing}, Tuple{typeof(push!), UInt64}}[
    (push!, 0x0000000000000001),
    (push!, 0x0000000000000000),
    (push!, 0x0000000000000000),
    (pop!, nothing),
    (pop!, nothing)
]
```

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

### Generate Operation Sequences for Testing

Source: https://seelengrab.github.io/Supposition.jl/dev/Examples/stateful.html

Generates a vector of possible operations (fill, empty, pour) to be used as input for property testing. This sets up the possible actions within the stateful system.

```Julia
using Supposition

raw_ops = (fill_small, fill_large, empty_small, empty_large, pour_small_into_large, pour_large_into_small)
gen_ops = Data.Vectors(Data.SampledFrom(raw_ops))
example(gen_ops)
```

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

### Supposition.test_function

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Tests a function provided within a TestState against a specific TestCase. It returns a tuple indicating if the TestCase is interesting and if it's an improvement over the previously recorded best example.

```APIDOC
## test_function(ts::TestState, tc::TestCase)

### Description
Test the function given to `ts` on the test case `tc`. Returns a `NTuple{Bool, 2}` indicating whether `tc` is interesting and whether it is "better" than the previously best recorded example in `ts`.

### Method
`test_function`

### Parameters
#### Path Parameters
- **ts** (TestState) - Description not available
- **tc** (TestCase) - Description not available

### Request Example
```julia
Supposition.test_function(my_test_state, my_test_case)
```

### Response
#### Success Response (200)
- **NTuple{Bool, 2}** - A tuple of two booleans indicating if the test case is interesting and better than the previous best.
```

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

### PropCheck.jl: Generate Vector of 1,000,000 Integers

Source: https://seelengrab.github.io/Supposition.jl/dev/benchmarks.html

Generates a Vector{Int} with 1,000,000 elements using PropCheck.jl. Requires importing BenchmarkTools and PropCheck. Benchmark is run using @benchmark.

```julia
using BenchmarkTools

using PropCheck

intgen = PropCheck.vector(PropCheck.iconst(1_000_000), itype(Int));

@benchmark root(PropCheck.generate(intgen))
```

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

### should_keep_generating

Source: https://seelengrab.github.io/Supposition.jl/dev/api.html

Determines if the TestState should continue generating new test cases. Returns true if the property is not trivial, a result is not yet available, there is room for more examples, and the timeout has not been reached.

```APIDOC
## should_keep_generating ts::TestState

### Description
Whether `ts` should keep generating new test cases, or whether `ts` is finished. `true` returned here means that the given property is not trivial, there is no result yet we have room for more examples, and we haven't hit the specified timeout yet.

### Method
`should_keep_generating`

### Parameters
- **ts** (TestState) - The test state to check.
```

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

### Generate Pairs from Two Possibilities

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Generates `Pair{T,S}` objects where the first element is produced by `first` `Possibility` and the second by `second` `Possibility`. Example uses `UInt8` and `Float64`.

```julia
using Supposition

p = Data.Pairs(Data.Integers{UInt8}(), Data.Floats{Float64}());

example(p, 4)
```

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

### Supposition.Data.BitIntegers

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

Generates all possible bitintegers with fixed sizes.

```APIDOC
## Supposition.Data.BitIntegers

### Description
A `Possibility` for generating all possible bitintegers with fixed size.

### Type
```julia
BitIntegers() <: Possibility{Union{Int128, Int16, Int32, Int64, Int8, UInt128, UInt16, UInt32, UInt64, UInt8}}
```
```

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

### Supposition.@check Macro

Source: https://seelengrab.github.io/Supposition.jl/dev/interfaces.html

The `@check` macro is the main entry point for declaring and running property-based tests. It orchestrates example generation and reports results to the testing framework.

```APIDOC
## `Supposition.@check` — Macro

### Description
The main way to declare & run a property based test. Called like so:
```julia
using Supposition, Supposition.Data

Supposition.@check [options...] function foo(a = Data.Text(Data.Characters(); max_len=10))
          length(a) > 8
       end
```

### Method
Macro

### Parameters
#### Options (key=value)
- `rng::Random.AbstractRNG`: Pass an RNG to use. Defaults to a copyable `Random.AbstractRNG`.
- `max_examples::Int`: The maximum number of generated examples that are passed to the property.
- `broken::Bool`: Mark a property that should pass but doesn't as broken, so that failures are not counted.
- `record::Bool`: Whether the result of the invocation should be recorded with any parent testsets.
- `db`: Either a Boolean (`true` uses a fallback database, `false` stops recording examples) or an `ExampleDB`.
- `timeout`: The maximum amount of time `@check` attempts new examples for. Expects a `Dates.TimeType`, can be disabled by setting to `nothing`.
- `config`: A `CheckConfig` object that will be used as a default for all previous options. Options that are passed explicitly to `@check` will override whatever is provided through `config`.

### Arguments
The arguments to the given function are expected to be `Possibilities`. The names they are bound to are the names the generated object will have in the test. These arguments will be shown should the property fail!

### Request Example
```julia
using Supposition, Supposition.Data

Supposition.@check [options...] function foo(a = Data.Text(Data.Characters(); max_len=10))
          length(a) > 8
       end
```

### Reusing existing properties
If you already have a predicate defined, you can also use the calling syntax in `@check`. Here, the generator is passed purely positionally to the given function; no argument name is necessary.
```julia
using Supposition, Supposition.Data

isuint8(x) = x isa UInt8

intgen = Data.Integers{UInt8}()

Supposition.@check isuint8(intgen)
```

### Passing a custom RNG
It is possible to optionally give a custom RNG object that will be used for random data generation. If none is given, `Xoshiro(rand(Random.RandomDevice(), UInt))` is used instead.
```julia
using Supposition, Supposition.Data, Random

# use a custom Xoshiro instance
Supposition.@check rng=Xoshiro(1234) function foo(a = Data.Text(Data.Characters(); max_len=10))
          length(a) > 8
       end
```

### Additional Syntax
In addition to passing a whole `function` like above, the following syntax are also supported:
```julia
text = Data.Text(Data.AsciiCharacters(); max_len=10)

# If no name is needed, use an anonymous function
@check (a = text) -> a*a
@check (a = text,) -> "foo: "*a
@check (a = text, num = Data.Integers(0,10)) -> a^num
```
```
Tokens:
Raw