The official library for writing fuzzers (a.k.a generators) for the Aiken Cardano smart-contract language.

It provides many useful primitives for writing and composing arbitrary generators in the context of property-based testing.

Installation

aiken add aiken-lang/fuzz --version v2

Getting started

First, make sure you have the Aiken’s user manual about tests; in particular the section about property-based test.

In many situations, you can use primitives from this library out-of-the-box, composing them inline when necessary. For example, if you need a non-empty list of values, you can simply write:

use aiken/fuzz

test my_prop(xs via fuzz.list_between(fuzz.int(), 1, 10)) {
  // some property
}

You can also write your own more complex fuzzer. Note that writing good fuzzers can be complicated, so here are a few guiding principles you should follow if you want them to be (a) effective and (b) easy to simplify for the test runner:

1. Ensure that smaller values lead to smaller fuzzers. For example, if you’re constructing a compound structure and you draw a value for the size, ensure that smaller values generate smaller structures. This is because the simplification simplifies towards 0.

2. Avoid fuzzers depending on far-away fuzzers. For example, you can write a fuzzer for generating list of values in mainly two ways: you can generate a random length, and then, a number of elements corresponding to that length. Or you can flip a coin, and each time choose to generate another element or to stop. The former is more intuitive, but the latter will produce lists that are easier to simplify.

3. Test your fuzzers! Use label, and ensure that the distribution of cases is what you expect it to be. Ensure that you go through specific scenarios. Writing fuzzers that omit crucial parts of the input domain is, unfortunately, quite easy.