# mozz.property

> A module of mozz_mlake's API.

Property-based testing frontend.

``forall[T]()`` generates typed values and checks a boolean property over
them.  On failure the run stops and raises an error.

``forall_bytes()`` is a simpler variant for raw-byte properties that works
without the ``Fuzzable`` trait.

Example:
    ```mojo
    from mozz import forall, forall_bytes, FuzzableUInt16

    # Property: addition must not overflow past u16 max
    def no_wrap(v: UInt16) raises -> Bool:
        return Int(v) + Int(v) >= Int(v)

    def gen_u16(mut rng: Xoshiro256) -> UInt16:
        return FuzzableUInt16.generate(rng)

    def minimize_u16(v: UInt16) -> List[UInt16]:
        return FuzzableUInt16.minimize(v)

    forall[UInt16](no_wrap, gen_u16, minimize_u16, trials=2000)

    # Raw bytes: decode_one never over-reads
    def safe_decode(data: List[UInt8]) raises -> Bool:
        try:
            var r = WsFrame.decode_one(Span[UInt8, _](data))
            return r.consumed <= len(data)
        except:
            return True

    forall_bytes(safe_decode, max_len=256, trials=10_000)
    ```

## Functions

### `forall`

```mojo
def forall[T: ImplicitlyCopyable & Deinitable](prop: def(T) raises thin -> Bool, gen: def(mut Xoshiro256) thin -> T, minimize_fn: def(T) thin -> List[T], trials: Int = Int(1000), seed: UInt64 = UInt64(0))
```

Test a boolean property over ``trials`` random values of type ``T``.

When a counterexample is found, ``minimize_fn`` is called iteratively to
minimize it before the error is raised.

Parameters:

- `T`: Type of the generated value (must be ``ImplicitlyCopyable``
   and ``Deinitable``; ``ImplicitlyCopyable`` already implies
   ``Movable``).

Args:

- `prop`: The property predicate.  Return ``False`` or raise to
             signal a counterexample.
- `gen`: Generator function -- ``def(mut Xoshiro256) -> T``.
- `minimize_fn`: Minimizer -- ``def(T) -> List[T]``.  Called to minimize
             the counterexample before raising.
- `trials`: Number of random trials (default 1 000).
- `seed`: PRNG seed (0 = derive from stack address).

Raises: Error: If a counterexample is found (after minimization).

### `forall_bytes`

```mojo
def forall_bytes(prop: def(List[UInt8]) raises thin -> Bool, max_len: Int = Int(1024), trials: Int = Int(1000), seed: UInt64 = UInt64(0))
```

Test a boolean property over ``trials`` random byte sequences.

Does not require ``Fuzzable`` — uses uniform random bytes with length
in ``[0, max_len]``.  On failure the failing bytes are hex-encoded in
the error message.

Args:

- `prop`: The property predicate on raw bytes (takes ``List[UInt8]``).
- `max_len`: Maximum byte sequence length (default 1 024).
- `trials`: Number of random trials (default 1 000).
- `seed`: PRNG seed (0 = derive from stack address).

Raises: Error: If a counterexample is found, with the failing bytes
hex-encoded.