> For the complete documentation index, see [llms.txt](https://docs.kimlikdao.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kimlikdao.org/testing-and-benching.md).

# Testing & benching

### Tests

Use `kdts test` to compile matching test files and then run them with Bun's test runner, which has a jest-like interface. See <https://bun.com/docs/test> for Bun's test API.

```sh
kdts test # --fast param available in all variants
kdts test crypto
kdts test path/some.test.ts
```

With no target, kdts test discovers `**/*.test.{js,ts}`. If the target is a directory, it runs matching test files under that directory.

Because the files are compiled first, `kdts test` is the right command when you want to validate kdts-specific transforms or the same compiled path you ship.

If you only want to run a test directly under Bun, without kdts compilation, use:

```shellscript
bun test path/some.test.ts
```

This is useful for quick iteration, but it does not validate kdts's compiled output.

### Benchmarks

Use `kdts bench` to compile matching benchmark files and then run the compiled output.

```shellscript
kdts bench # --fast param avilable in all variants
kdts bench util/hex
kdts bench exp.bench.ts
```

With no target, `kdts bench` discovers `**/*.bech.{js,ts}`.

For benchmarks, kdts also provides a correctness-checked harness:

{% code title="exp.bench.ts" %}

```typescript
import { bench } from "@kimlikdao/kdts/bench";
import { exp, exp2 } from "@kimlikdao/lib/crypto/modular";

const Q = 0xDAD19B08F618992D3A5367F0E730B97C6DD113B6A2A493C9EDB0B68DBB1AEC020FB2A64C9644397AB016ABA5B40FA22655060824D9F308984D6734E2439BA08Fn;

bench("512-bit exp(2, x, M) vs exp2(x, M)", {
  "exp": (x: bigint) => exp(2n, x, Q),
  "exp2": (x: bigint) => exp2(x, Q),
}, {
  repeat: 1000,
  dataset: [{ input: Q - 1n, output: 1n }]
});
```

{% endcode %}

It can be run with

```shellscript
kdts bench exp.bench.ts
```

It prints an output like:

```
512-bit exp(2, x, M) vs exp2(x, M)
  exp2  95.95 ms       (fastest)
  exp   99.31 ms    3.5% slower
```

The benchmark harness has the following signature:

```typescript
const bench = <I, O>(
  description: string,
  fns: Record<string, (input: I) => O>,
  options: { repeat: number, dataset: { input: I, output: O }[] },
): void;
```

In particular, the `bench()` harness takes a description, a record of functions to benchmark (each with the same signature), a repeat count and a dataset of input-output pairs.

Each candidate is run repeat times for every dataset item. Its result is checked against the expected output, and candidate order is shuffled per dataset item to reduce order bias.

Useful options: `--fast`, `--filter`, `--buildConcurrency`, and `--runConcurrency`. Run `kdts --help` for the full CLI reference.