TODOs

[KtorZ]

Note

If you intend to work on one of the following points:

• use the bulleye icon to create a new issue from a bullet point
• assign yourself to the issue
• keep us posted

Api

Primitives

aiken/fuzz

• fn int_between(min: Int, max: Int) -> Fuzzer<Int> #8
• fn int_at_least(min: Int) -> Fuzzer<Int>
• fn int_at_most(max: Int) -> Fuzzer<Int>
• fn bytearray() -> Fuzzer<ByteArray>
• fn bytearray_between(min: Int, max: Int) -> Fuzzer<ByteArray>
• fn list_at_least(fuzz_elem: Fuzzer<a>, min: Int) -> Fuzzer<List<a>>
• fn list_at_most(fuzz_elem: Fuzzer<a>, max: Int) -> Fuzzer<List<a>>
• fn either(fuzz_left: Fuzzer<a>, fuzz_right: Fuzzer<a>) -> Fuzzer<a>
• fn both(fuzz_left: Fuzzer<a>, fuzz_right: Fuzzer<b>) -> Fuzzer<(a, b)>
• fn map6(fuzz_a: Fuzzer<a>, .., fuzz_f: Fuzzer<f>, f: fn(a, ..., f) -> result) -> Fuzzer<result> #3
• fn map7(fuzz_a: Fuzzer<a>, .., fuzz_g: Fuzzer<f>, f: fn(a, ..., g) -> result) -> Fuzzer<result> #4
• fn map8(fuzz_a: Fuzzer<a>, .., fuzz_h: Fuzzer<f>, f: fn(a, ..., h) -> result) -> Fuzzer<result> #5
• fn map9(fuzz_a: Fuzzer<a>, .., fuzz_i: Fuzzer<f>, f: fn(a, ..., i) -> result) -> Fuzzer<result> #6

Common types

Note

Considering:

type Sample<a> = Fuzzer<List<a>>

aiken/fuzz/dict

• fn dict(fuzz_key: Fuzzer<k>, fuzz_value: Fuzzer<v>) -> Fuzzer<Dict<k, v>>
• fn dict_between(fuzz_key: Fuzzer<k>, fuzz_value: Fuzzer<v>, min: Int, max: Int) -> Fuzzer<Dict<k, v>>
• fn dict_at_least(fuzz_key: Fuzzer<k>, fuzz_value: Fuzzer<v>, min: Int, max: Int) -> Fuzzer<Dict<k, v>>
• fn dict_at_most(fuzz_key: Fuzzer<k>, fuzz_value: Fuzzer<v>, min: Int, max: Int) -> Fuzzer<Dict<k, v>>
• fn dict_from(keys: Sample<k>, fuzz_value: Fuzzer<v>) -> Fuzzer<Dict<k, v>>

aiken/fuzz/math/rational

• fn rational() -> Fuzzer<Rational>
• fn rational_between(min: Rational, max: Rational) -> Fuzzer<Rational>
• fn rational_at_least(min: Rational) -> Fuzzer<Rational>
• fn rational_at_most(max: Rational) -> Fuzzer<Rational>

aiken/fuzz/transaction/value

• fn lovelace() -> Fuzzer<Int> (a bespoke int fuzzer for lovelace quantities)

aiken/fuzz/transaction/certificate

• fn certificate(delegators: Sample<StakeCredential>, pools: Sample<PoolId>) -> Fuzzer<Certificate>

aiken/fuzz/transaction/credential

• fn address(payment_credentials: Sample<PaymentCredential>, delegation_credentials: Sample<DelegationCredential>) -> Fuzzer<Address>

Documentation

• Rework README and provide a high-level overview of the project.
• Add more inline-doc examples to (at least) primitives
• Write a small tutorial to illustrate the capabilities of the library and showcase some patterns.

Experiments

• Experiment with Scott-Encoded Tuples and analyze performances in comparison with Data-tuples.

[waalge]

dict in an age of pairs. I guess we want both/ one a special case of the other?

[adrian052]

I'm going to try implementing the fuzzers from aiken/fuzz/math/rational. Is there a distribution you'd recommend for building these fuzzers from scratch, or can I just compose them with the int() fuzzers?

[KtorZ]

Using the base fuzzer primitives is a good idea, unless you really need to squeeze in more performances but for rational that should be okay.

As a rule of thumb for building fuzzers, make sure to make your most wanted scenarios associated with small values. Because the integrated shrinking strategy will simplify towards 0.

[adrian052]

I have added a new PR #19 with the rational fuzzers implemented.

[KtorZ]

@adrian052 -> back then, when we first discussed the matter with @waalge, we weren't sure where the best place would be for generators that refer to stdlib components. There's an argument for putting them in the fuzz package; but there's also an argument for putting them next to their parent module in the stdlib. And there's also an argument to have a completely new package: stdlib-fuzz with only fuzzers for stdlib types.

Back then, I leaned more towards defining fuzzers like those in #19 in stdlib, primarily because the plan was to use the fuzz library to test parts of stdlib. And to avoid the circular dependency, that would have been necessary. Since then, we did implement dependency module pruning and a "smarter" dependency graph; so cycles can only truly exists at the module level, not package. Which means that it is completely fine to have fuzz modules that depend on stdlib modules, and have stdlib modules depend on fuzz modules. Modules shall just not form of a cycle. Virtually, it's like one big project where all the modules would be.

In addition to that, stdlib has substantially grown, with governance, pairs and bls stuff. And I am afraid that adding a whole new set of fuzz-related modules will simply add noise and make stdlib scarier for new joiners. So, adding them here sounds reasonable.

Sorry for the long rant, I just wanted to bring some context and give clarification before merging your PR, as this is a topic we did discuss several times with @waalge.

[adrian052]

Understood, so with the smarter dependency graph, we now avoid circular package-level dependencies. I believe it would be worthwhile to include a dedicated section about this on the documentation page.