# gizlang:test

assertions, generated inputs and shrinking, for test functions (`function testName(): void`, run by `giz test FILE`) and for programs.

An assertion that does not hold faults (R004) inside itself, so the fault trace carries what failed with its values and where it was called: `equal line 1 (actual = 4, expected = 5) <- testAdd (main.giz:12)`. The test fails with that trace and a replay test reproducing the call, and the other tests still run. Nothing is collected or formatted on success.

```gizlang
import * as Test from "gizlang:test";
```

## Functions

### `equal`

```gizlang
function equal<T>(actual: T, expected: T): void
```

actual is expected (===: numbers, bools, strings, bytes, and records,
unions and Vecs by content; a record shows its fields in the trace).

### `differ`

```gizlang
function differ<T>(actual: T, unexpected: T): void
```

actual is not unexpected.

### `check`

```gizlang
function check(condition: bool): void
```

condition holds; the trace shows the calling line.

Effects: fail.

### `maxError`

```gizlang
function maxError(actual: Vec<f32>, expected: Vec<f32>): f64
```

The largest |actual[i] - expected[i]| of a numeric result and its reference, which have the same length.

Effects: fail.

### `relativeError`

```gizlang
function relativeError(actual: Vec<f32>, expected: Vec<f32>): f64
```

maxError over the largest |expected[i]|.

Effects: fail.

### `includes`

```gizlang
function includes(text: string, part: string): void
```

text contains part.

Effects: fail.

### `equalLines`

```gizlang
function equalLines(actual: string, expected: string): void
```

Two texts are equal; on a difference the trace shows the first differing
line and column, and both lines from just before it (a trace keeps 32
bytes of a string), not two whole texts.

Effects: fail.

### `equalItems`

```gizlang
function equalItems<T>(actual: Vec<T>, expected: Vec<T>): void
```

Two Vecs are equal item by item; on a difference the trace shows the
first differing index and both items, or both lengths.

### `forAll`

```gizlang
function forAll<T>(seed: u64, runs: i64, generate: (seed: u64, size: i64) => T, smaller: (value: T) => Vec<T>, holds: (value: T) => bool, failing: (value: T) => void): void
```

A property over generated inputs: `holds` is tried on `runs` values from
`generate`, given each run's own seed (from `seed`, so the same seed gives
the same inputs; build a `newRandom(seed)` from it) and a size growing from
0 to 100. The first value it rejects is shrunk by `smaller` (values simpler
than one; none for the simplest) to a minimal counterexample, which
`failing` receives: its assertion faults with that value in the trace.

### `shrunk`

```gizlang
function shrunk<T>(value: T, smaller: (value: T) => Vec<T>, holds: (value: T) => bool): T
```

The smallest form of VALUE that still fails HOLDS: it tries the candidates of SMALLER until none fails.

### `smallerI64`

```gizlang
function smallerI64(n: i64): Vec<i64>
```

Simpler i64s than n, toward 0: 0, n/2, n-1 (or n+1 below 0).

Effects: fail.

### `smallerVec`

```gizlang
function smallerVec<T>(v: Vec<T>, item: (value: T) => Vec<T>): Vec<Vec<T>>
```

Simpler Vecs than v: without its second half, without each item, and
with each item simpler (by `item`).