Documentation Reference

|(::Possibility{T}, ::Possibility{S}) where {T,S} -> OneOf{Union{T,S}}

Combine two Possibility into one, sampling uniformly from either.

If either of the two arguments is a OneOf, the resulting object acts as if all original non-OneOf had be given to OneOf instead. That is, e.g. OneOf(a, b) | c will act like OneOf(a,b,c).

See also OneOf.

filter(f, pos::Possibility)

Filter the output of produce! on pos by applying the predicate f.

map(f, pos::Possibility)
map(f, pos::Vararg{Possibility})

Apply f to the result of calling produce! on pos (lazy mapping).

Equivalent to calling Map(pos, f), or MultiMap(pos, f) for the Vararg case (where pos is the tuple of Possibility). In the Vararg case, f is expected to take as many arguments as Possibility are passed to map.

See also Map.

bind(f, pos::Possibility)

Maps the output of produce! on pos through f, and calls produce! on the result again. f is expected to take a value and return a Possibility.

Equivalent to calling Bind(pos, f).

See also Bind.

postype(::P) where P <: Possibility

Gives the type of objects this Possibility object will generate.

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

Gives the type of objects this Possibility type will generate.

produce!(tc::TestCase, pos::Possibility{T}) -> T

Produces a value from the given Possibility, recording the required choices in the TestCase tc.

This needs to be implemented for custom Possibility objects, passing the given tc to any inner requirements directly.

See also Supposition.produce!

recursive(f, pos::Possibility; max_layers=5)

Recursively expand pos into deeper nested Possibility by repeatedly passing pos itself to f. f returns a new Possibility, which is then passed into f again until the maximum depth is achieved.

Equivalent to calling Recursive(pos, f).

See also Recursive.

AsciiCharacters() <: Possibility{Char}

A Possibility of producing arbitrary Char instances that are isascii. More efficient than filtering Characters.

julia> using Supposition

julia> ascii = Data.AsciiCharacters()

julia> example(ascii, 5)
5-element Vector{Char}:
 '8': ASCII/Unicode U+0038 (category Nd: Number, decimal digit)
 'i': ASCII/Unicode U+0069 (category Ll: Letter, lowercase)
 'R': ASCII/Unicode U+0052 (category Lu: Letter, uppercase)
 '\f': ASCII/Unicode U+000C (category Cc: Other, control)
 '>': ASCII/Unicode U+003E (category Sm: Symbol, math)

Bind(source::Possibility, f)

Binds f to source, i.e., on produce!(::Bind, ::TestCase) this calls produce! on source, the result of which is passed to f, the output of which will be used as input to produce! again.

In other words, f takes a value produce!d by source and gives back a Possibility that is then immediately produce!d from.

Equivalent to bind(f, source).

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

A Possibility for generating all possible bitintegers with fixed size.

Booleans() <: Possibility{Bool}

A Possibility for sampling boolean values.

julia> using Supposition

julia> bools = Data.Booleans()

julia> example(bools, 4)
4-element Vector{Bool}:
 0
 1
 0
 1

Characters(;valid::Bool = false) <: Possibility{Char}

A Possibility of producing arbitrary well-formed Char instances.

Keyword arguments:

• valid: Whether the produced Char must be valid, i.e. not malformed and not have Unicode category Invalid.

julia> using Supposition

julia> chars = Data.Characters()

julia> example(chars, 5)
5-element Vector{Char}:
 '⠺': Unicode U+283A (category So: Symbol, other)
 '𰳍': Unicode U+30CCD (category Lo: Letter, other)
 '\U6ec9c': Unicode U+6EC9C (category Cn: Other, not assigned)
 '\U1a05c5': Unicode U+1A05C5 (category In: Invalid, too high)
 '𓂫': Unicode U+130AB (category Lo: Letter, other)

Dicts(keys::Possibility, values::Possibility; min_size=0, max_size=10_000)

A Possibility for generating Dict objects. The keys are drawn from keys, while the values are drawn from values. min_size/max_size control the number of objects placed into the resulting Dict, respectively.

julia> dicts = Data.Dicts(Data.Integers{UInt8}(), Data.Integers{Int8}(); max_size=3);

julia> example(dicts)
Dict{UInt8, Int8} with 2 entries:
  0x54 => -29
  0x1f => -28

Floats(;nans=true, infs=true) <: Possibility{Union{Float64,Float32,Float16}}

A catch-all for generating instances of all three IEEE floating point types.

Floats{T <: Union{Float16,Float32,Float64}}(;infs=true, nans=true, minimum=-T(Inf), maximum=+T(Inf)) <: Possibility{T}

A Possibility for sampling floating point values.

The keyword infs controls whether infinities can be generated. nans controls whether any NaN (signaling & quiet) will be generated.

julia> using Supposition

julia> floats = Data.Floats{Float16}()

julia> example(floats, 5)
5-element Vector{Float16}:
  -8.3e-6
   1.459e4
   3.277
 NaN
  -0.0001688

Integers(minimum::T, maximum::T) <: Possibility{T <: Integer}
Integers{T}() <: Possibility{T <: Integer}

A Possibility representing drawing integers from [minimum, maximum]. The second constructors draws from the entirety of T.

Produced values are of type T.

julia> using Supposition

julia> is = Data.Integers{Int}()

julia> example(is, 5)
5-element Vector{Int64}:
 -5854403925308846160
  4430062772779972974
    -9995351034504801
  2894734754389242339
 -6640496903289665416

Just(value::T) <: Possibility{T}

A Possibility that always produces value.

julia> using Supposition

julia> three = Data.Just(3)

julia> example(three, 3)
3-element Vector{Int64}:
 3
 3
 3

Map(source::Possibility, f) <: Possibility

A Possibility representing mapping values from source through f.

Equivalent to calling map(f, source).

The pre-calculated return type of Map is a best effort and may be wider than necessary.

julia> using Supposition

julia> makeeven(x) = (x ÷ 2) * 2

julia> pos = map(makeeven, Data.Integers{Int8}())

julia> all(iseven, example(pos, 10_000))
true

Matrices(elements::Possibility{T}; min_rows=0, max_rows=100, min_cols=0, max_cols=100) <: Possibility{Matrix{T}}

A Possibility for creating Matrix{T} objects mat with min_rows <= size(mat, 1) <= max_rows and min_cols <= size(mat, 2) <= max_cols.

All of min_*/max_* must be positive numbers, with min_* being <= than the respective max_*.

julia> using Supposition

julia> mats = Data.Matrices(Data.Integers{UInt8}(); min_cols=1, max_cols=5, min_rows=2, max_rows=7);

julia> example(mats)
5×3 Matrix{UInt8}:
 0x29  0x2c  0x20
 0x2a  0xb4  0xf2
 0x97  0x5b  0x24
 0x2e  0xfa  0x06
 0xd4  0x45  0x4e

OneOf(pos::Possibility...) <: Possibility

A Possibility able to generate any of the examples one of the given Possibility can produce. The given Possibility are sampled from uniformly.

At least one Possibility needs to be given to OneOf.

postype(::OneOf) is inferred as a best effort, and may be wider than necessary.

OneOf can also be constructed through use of a | b on Possibility. Constructed in this way, if either a or b is already a OneOf, the resulting OneOf acts as if it had been given the original Possibility objects in the first place. That is, OneOf(a, b) | c acts like OneOf(a, b, c).

See also WeightedNumbers and WeightedSample.

julia> of = Data.OneOf(Data.Integers{Int8}(), Data.Integers{UInt8}());

julia> Data.postype(of)
Union{Int8, UInt8}

julia> ex = map(of) do i
           (i, typeof(i))
       end;

julia> example(ex)
(-83, Int8)

julia> example(ex)
(0x9f, UInt8)

Pairs(first::Possibility{T}, second::Possibility{S}) where {T,S} <: Possibility{Pair{T,S}}

A Possibility for producing a => b pairs. a is produced by first, b is produced by second.

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

julia> example(p, 4)
4-element Vector{Pair{UInt8, Float64}}:
 0x41 => 4.1183566661848205e-230
 0x48 => -2.2653631095108555e-119
 0x2a => -6.564396855333643e224
 0xec => 1.9330751262581671e-53

Recursive(base::Possibility, extend; max_layers::Int=5) <: Possibility{T}

A Possibility for generating recursive data structures. base is the basecase of the recursion. extend is a function returning a new Possibility when given a Possibility, called to recursively expand a tree starting from base. The returned Possibility is fed back into extend again, expanding the recursion by one layer.

max_layers designates the maximum layers Recursive should keep track of. This must be at least 1, so that at least the base case can always be generated. Note that this implies extend will be used at most max_layers-1 times, since the base case of the recursion will not be wrapped.

Equivalent to calling recursive(extend, base).

Examples

julia> base = Data.Integers{UInt8}()

julia> wrap(pos) = Data.Vectors(pos; min_size=2, max_size=3)

julia> rec = Data.recursive(wrap, base; max_layers=3);

julia> Data.postype(rec) # the result is formatted here for legibility
Union{UInt8,
      Vector{UInt8},
      Vector{Union{UInt8, Vector{UInt8}}}
}

julia> example(rec)
0x31

julia> example(rec)
2-element Vector{Union{UInt8, Vector{UInt8}}}:
     UInt8[0xa9, 0xb4]
 0x9b

julia> example(rec)
2-element Vector{UInt8}:
 0xbd
 0x25

SampledFrom(collection) <: Possibility{eltype(collection)}

A Possibility for sampling uniformly from collection.

collection, as well as its eachindex, is assumed to be indexable.

julia> using Supposition

julia> sampler = Data.SampledFrom([1, 1, 1, 2])

julia> example(sampler, 4)
4-element Vector{Int64}:
 1
 1
 2
 1

Satisfying(source::Possibility, pred) <: Possibility

A Possibility representing values from source fulfilling pred.

Equivalent to calling filter(f, source).

julia> using Supposition

julia> pos = filter(iseven, Data.Integers{Int8}())

julia> all(iseven, example(pos, 10_000))
true

SquareMatrices(elements::Possibility{T}; min_size=0, max_size=1_000) <: Possibility{Matrix{T}}

A Possibility for creating Matrix{T} objects mat with min_size <= size(mat, 1) <= max_size and size(mat, 1) == size(mat, 2).

Both min_size and max_size must be positive numbers, with min_size <= max_size.

julia> using Supposition

julia> mats = Data.SquareMatrices(Data.Integers{UInt8}(); min_size=3, max_size=10);

julia> example(mats)
4×4 Matrix{UInt8}:
 0x36  0x7f  0x84  0x57
 0x11  0xfa  0x61  0x12
 0xb2  0x47  0xbf  0x66
 0x74  0xe3  0xf1  0x3a

Text(alphabet::Possibility{Char}; min_len=0, max_len=10_000) <: Possibility{String}

A Possibility for producing Strings containing Chars of a given alphabet.

julia> using Supposition

julia> text = Data.Text(Data.AsciiCharacters(); max_len=15)

julia> example(text, 5)
5-element Vector{String}:
 "U\x127lxf"
 "hm\x172SJ-("
 "h`\x03\0\x01[[il"
 "\x0ep4"
 "9+Hk3 ii\x1eT"

UnicodeCharacters(;valid::Bool = false, malformed = true) <: Possibility{Char}

A Possibility of producing arbitrary Char instances.

Keyword arguments:

• malformed: Whether produced Char are allowed to be malformed. This only has an effect when valid=false.
• valid: Whether the produced Char must be valid, i.e. not malformed and not have Unicode category Invalid.

julia> using Supposition

julia> chars = Data.UnicodeCharacters()

julia> example(chars, 5)
5-element Vector{Char}:
 '\xd2\x5a\x96\x07': Malformed UTF-8 (category Ma: Malformed, bad data)
 '\x44\x45\xc5\x64': Malformed UTF-8 (category Ma: Malformed, bad data)
 '\x04': Unicode U+0004 (category Cc: Other, control)
 '\x2b\xe0\x6a\x89': Malformed UTF-8 (category Ma: Malformed, bad data)
 '\xf5\x9b\x63\x05': Malformed UTF-8 (category Ma: Malformed, bad data)

Vectors(elements::Possibility{T}; min_size=0, max_size=10_000) <: Possibility{Vector{T}}

A Possibility representing drawing vectors with length l in min_size <= l <= max_size, holding elements of type T.

min_size and max_size must be positive numbers, with min_size <= max_size.

julia> using Supposition

julia> vs = Data.Vectors(Data.Floats{Float16}(); max_size=5)

julia> example(vs, 3)
3-element Vector{Vector{Float16}}:
 [9.64e-5, 9.03e3, 0.04172, -0.0003352]
 [9.793e-5, -2.893, 62.62, 0.0001961]
 [-0.007023, NaN, 3.805, 0.1943]

WeightedNumbers(weights::Vector{Float64}) <: Possibility{Int}

Sample the numbers from 1:length(weights), each with a weight of weights[i].

The weights may be any number > 0.0.

See also OneOf.

julia> using Supposition

julia> bn = Data.WeightedNumbers([1.0, 1.0, 3.0]);

julia> example(Data.Vectors(bn; min_size=3, max_size=15), 5)
5-element Vector{Vector{Int64}}:
 [3, 2, 3, 3, 2, 3, 3]
 [1, 1, 1, 2, 1, 3, 1, 3]
 [2, 3, 3, 3, 3, 3, 3, 1, 1, 3, 3, 3]
 [3, 3, 2, 3, 3]
 [1, 3, 3, 3, 2, 2]

WeightedSample{T}(colllection, weights::Vector{Float64}) <: Possibility{T}

Draw an element from the indexable collection, biasing the drawing process by assigning each index i of col the weight at weights[i].

length of col and weights must be equal and eachindex(col) must be indexable.

See also OneOf.

julia> bs = Data.WeightedSample(["foo", "bar", "baz"], [3.0, 1.0, 1.0]);

julia> example(bs, 10)
10-element Vector{String}:
 "foo"
 "foo"
 "bar"
 "baz"
 "baz"
 "foo"
 "bar"
 "foo"
 "foo"
 "bar"

@check [key=val]... function...

The main way to declare & run a property based test. Called like so:

julia> using Supposition, Supposition.Data

julia> 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.

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!

Extended help

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

julia> isuint8(x) = x isa UInt8

julia> intgen = Data.Integers{UInt8}()

julia> 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
julia> 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:

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!"

@composed

A way to compose multiple Possibility into one, by applying a function.

The return type is inferred as a best-effort!

Used like so:

julia> using Supposition, Supposition.Data

julia> text = Data.Text(Data.AsciiCharacters(); max_len=10)

julia> gen = Supposition.@composed function foo(a = text, num=Data.Integers(0, 10))
              lpad(num, 2) * ": " * a
       end

julia> example(gen)
" 8:  giR2YL\rl"

In addition to passing a whole function like above, the following syntax are also supported:

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

# ..or give the anonymous function a name too - works with all three of the above
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!"

# or compose a new generator out of an existing function
my_func(str, number) = number * "? " * str
ask_number = @composed my_func(text, num)

@event!(expr)

Macro-version of event!.

Uses the stringified version of expr as the label, and returns the value of expr.

See also event!.

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

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

acceptions(::Stats) -> Int

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

add_attempt(::Stats) -> Stats

Record an attempts at generating an input for the property under test to the statistics.

Returns a new Stats object.

add_call_duration(::Stats, dur::Float64) -> Stats

Record the duration of one execution of the property under test to the statistics. This records online statistics of mean & variance.

Returns a new Stats object.

add_gen_duration(::Stats, dur::Float64) -> Stats

Record the duration of generating one input to the statistics. This records online statistics of mean & variance.

Returns a new Stats object.

add_improvement(::Stats) -> Stats

Record an improvement due to targeting.

Returns a new Stats object.

add_invalidation(::Stats) -> Stats

Record an invalidation of the property under test to the statistics. I.e., a counterexample was found.

Returns a new Stats object.

add_invocation(::Stats) -> Stats

Record an invocation of the property under test to the statistics.

Returns a new Stats object.

add_overrun(::Stats) -> Stats

Record an overrun encountered while trying to add a choice to the statistics. I.e., we've hit the upper limit of the number of choices we're allowed to make.

Returns a new Stats object.

add_shrink(::Stats) -> Stats

Record a shrinking action of a choice sequence to the statistics.

Returns a new Stats object.

add_total_duration(::Stats, dur::Float64) -> Stats

Record the overall duration of one @check to the statistics.

Returns a new Stats object.

add_validation(::Stats) -> Stats

Record a successful invocation of the property under test to the statistics. I.e., the property under test returned true.

Returns a new Stats object.

adjust(ts::TestState, attempt)

Adjust ts by testing for the choices given by attempt.

Returns whether attempt was by some measure better than the previously best attempt.

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

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

assume!(precondition::Bool)

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

assume!(::TestCase, precondition::Bool)

Reject this TestCase if precondition is false.

attempts(::Stats) -> Int

Retrieve the total number of attempts that were made to generate a potential input to the property.

choice!(tc::TestCase, n)

Force a number of choices to occur, taking from the existing prefix first. If the prefix is exhausted, draw from [zero(n), n] instead.

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

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

counterexample(::SuppositionReport) -> Option

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

err_choices

Return the choices that led to the recorded error, if any. If none, return Nothing.

err_less(e1::E, e2::E) where E

A comparison function for exceptions, used when encountering an error in a property. Returns true if e1 is considered to be "easier" or "simpler" than e2. Only definable when both e1 and e2 have the same type.

This is optional to implement, but may be beneficial for shrinking counterexamples leading to an error with rich metadata, in which case err_less will be used to compare errors of the same type from different counterexamples. In particular, this function will likely be helpful for errors with metadata that is far removed from the input that caused the error itself, but would nevertheless be helpful when investigating the failure.

event!(obj)
event!(label::AbstractString, obj)

Record obj as an event in the current testcase that occured while running your property. If no label is given, a default one will be chosen.

See also @event!.

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

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.

julia> using Supposition, Supposition.Data

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

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

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

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

find_user_error_frame(err, trace)

Try to heuristically guess where an error was actually coming from.

For example, ErrorException is (generally) thrown from the error function, which would always report the same location if we'd naively take the first frame of the trace. This tries to be a bit smarter (but still fairly conservative) and return something other than the first frame for a small number of known error-throwing functions.

find_user_stack_depth

Return a heuristic guess for how many functions deep in user code an error was thrown. Falls back to the full length of the stacktrace.

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

Create a TestCase for a given set of known choices.

forced_choice(tc::TestCase, n::UInt64)

Insert a definite choice in the choice sequence.

Note that all integrity checks happen here!

generate(ts::TestState)

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

gentime_mean(::Stats) -> Float64

Retrieve the mean time in seconds of generating an example.

This counts any attempt at generating an example, including early rejections.

gentime_variance(::Stats) -> Float64

Retrieve the variance of the time in seconds of generating an example.

This counts any attempt at generating an example, including early rejections.

improvements(::Stats) -> Int

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

invocations(::Stats) -> Int

Retrieve the total number of times the property was invoked with and input.

This number may be less than attempts, since some inputs may be rejected before the property is invoked.

overruns(::Stats) -> Int

Retrieve the total number of times generating an input required more choices than were available from the currently used choice sequence.

This can happen if you attempt to generate more data than the maximum buffer size configured, or when shrinking the choice sequence leads to too few choices available.

reject!()

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

reject(::TestCase)

Mark this test case as invalid.

rejections(::Stats) -> Int

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

run(ts::TestState)

Run the checking algorithm on ts, generating values until we should stop, targeting the score we want to target on and finally shrinking the result.

runtime_mean(::Stats) -> Float64

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

runtime_variance(::Stats) -> Float64

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

should_keep_generating(ts::TestState)

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.

shrink_redistribute(ts::TestState, attempt::Attempt, k::UInt)

Try to shrink attempt by redistributing value between two elements length k apart.

shrink_reduce(::TestState, attempt::Attempt)

Try to shrink attempt by making the elements smaller.

shrink_remove(ts::TestState, attempt::Attempt, k::UInt)

Try to shrink attempt by removing k elements at a time

shrink_sort(::TestState, attempt::Attempt, k::UInt)

Try to shrink attempt by sorting k contiguous elements at a time.

shrink_swap(::TestState, attempt::Attempt, k::UInt)

Try to shrink attempt by swapping two elements length k apart.

shrink_zeros(::TestSTate, attempt::Attempt, k::UInt)

Try to shrink attempt by setting k elements at a time to zero.

shrinks(::Stats) -> Int

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

statistics(::SuppositionReport) -> Stats

Returns the statistics collected about this SuppositionReport.

target!(score)

Update the currently running testcase to track the given score as its target.

score must be convertible to a Float64.

target!(tc::TestCase, score::Float64)

Update tc to use score as the score this TestCase achieves during optimization.

target!(ts::TestState)

If ts has a target to go towards set, this will try to climb towards that target by adjusting the choice sequence until ts shouldn't generate anymore.

If ts is currently tracking an error it encountered, it will try to minimize the stacktrace there instead.

tear(x::T) where T <: Union{Float16, Float32, Float64} -> Tuple{I, I, I}

Returns the sign, exponent and fractional parts of a floating point number. The returned tuple consists of three unsigned integer types I of the same bitwidth as T.

test_function(ts::TestState, tc::TestCase)

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.

total_time(::Stats) -> Float64

Retrieve the total time taken for this fuzzing process.

weighted(tc::TestCase, p::Float64)

Return true with probability p, false otherwise.

windows(array, a, b)

Split array into three windows, with split points at a and b. The split points belong to the middle window.

CheckConfig(;options...)

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

Options:

• 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 10_000.
• 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.
• db: An ExampleDB for recording failure cases for later replaying. Defaults to default_directory_db().
• buffer_size: The default maximum buffer size to use for a test case. Defaults to 100_000.
• timeout: The maximum amount of time @check attempts new examples for. Expects a Dates.TimeType, can be disabled by setting to nothing. Defaults to nothing.

Composed{S,T} <: Possibility{T}

A Possibility composed from multiple different Possibility through @composed. A tiny bit more fancy/convenient compared to map if multiple Possibility are required to be mapped over at the same time.

Should not be instantiated manually; keep the object returned by @composed around instead.

DirectoryDB <: ExampleDB

An ExampleDB that records examples as files in a directory.

Error

A result indicating that an error was encountered while generating or shrinking.

Fail

A result indicating that a counterexample was found.

NoRecordDB <: ExambleDB

An ExampleDB that doesn't record anything, and won't retrieve anything.

Pass

A result indicating that no counterexample was found.

Result

An abstract type representing the ultimate result a TestState ended up at.

Stats

A collection of various statistics of the execution of one @check.

• attempts: Total number of attempts to generate an input
• acceptions: Number of times an input was accepted as valid
• rejections: Number of times an input was reject!ed
• overruns: Number of times an Overrun occurred during generation
• invocations: Total number of invocations of the property under test
• mean_gentime: Mean time for generating an input
• squared_dist_gentime: Aggregated squared distance from the mean gentime
• mean_runtime: Mean execution time of the property
• squared_dist_runtime: Aggregated squared distance from the mean runtime
• shrinks: Number of times a counterexample was shrunk successfully
• total_time: The total (wall-clock) time used.
• improvements: Number of times an improvement was made with target!

SuppositionReport <: AbstractTestSet

An AbstractTestSet, for recording the final result of @check in the context of @testset

TestCase

A struct representing a single (ongoing) test case.

• prefix: A fixed set of choices that must be made first.
• rng: The RNG this testcase ultimately uses to draw from. This is used to seed the task-local RNG object before generating begins.
• generation: The "generation" this TestCase was made in. Can be used for determining how far along in the generation process we are (higher is further).
• max_generation: The maximum "generation" this TestCase could have been made in. Does not necessarily exist.
• max_size: The maximum number of choices this TestCase is allowed to make.
• choices: The binary choices made so far.
• targeting_score: The score this TestCase attempts to maximize.
• generation_start: A timestamp from the moment before generation of the input started.
• call_start: A timestamp from the moment before the input was passed to the property under test.

TestState

• config: The configuration this TestState is running with
• is_interesting: The user given property to investigate
• rng: The currently used RNG
• stats: A collection of statistics about this TestState
• result: The choice sequence leading to a non-throwing counterexample
• best_scoring: The best scoring result that was encountered during targeting
• target_err: The error this test has previously encountered and the smallest choice sequence leading to it
• error_cache: A cache of errors encountered during shrinking that were not of the same type as the first found one, or are from a different location
• test_is_trivial: Whether is_interesting is trivial, i.e. led to no choices being required
• previous_example: The previously recorded attempt (if any).
• start_time: The point in time when this execution started. nothing means execution has not yet started.
• deadline: The point in time (if any) after which no new examples will be generated.

Timeout

A result indicating that no examples whatsoever were attempted, due to reaching the timeout before a single example concluded.

UnsetDB

An ExampleDB that is only used by the default CheckConfig, to mark as "no config has been set". If this is the database given in a config to @check and no other explicit database has been given, @check will choose the default_directory_db() instead.

Cannot be used during testing.

CURRENT_TESTCASE

A ScopedValue containing the currently active test case. Intended for use in user-facing functions like target! or assume! that need access to the current testcase, but shouldn't require it as an argument to make the API more user friendly.

Not intended for user-side access, thus considered internal and not supported under semver.

DEFAULT_CONFIG

A ScopedValue holding the CheckConfig that will be used by default & as a fallback.

Currently uses these values:

• rng: Random.Xoshiro(rand(Random.RandomDevice(), UInt))
• max_examples: 10_000
• record: true
• verbose: false
• broken: false
• db: UnsetDB()
• buffer_size: 100_000

@check will use a new instance of Random.Xoshiro by itself.

MESSAGE_BASED_ERROR

A Union of some some in Base that are known to contain only the field :msg.

If you're using one of these errors and require specialized shrinking on them, define a custom exception type and throw that instead of overriding err_less. The definition of err_less for these types is written for the most generality, not perfect accuracy.

Option{T}

A utility alias for Union{Some{T}, Nothing}.