# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kimlikdao.org/testing-and-benching.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.