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.

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:

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.

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:

exp.bench.ts

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 }]
});

It can be run with

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:

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.