lib0-testing

lib0 Testing Framework

lib0 ships its own test runner (src/testing.js) — there is no Jest / Mocha / Vitest. Tests are plain ESM modules that export functions whose names start with test. A seeded PRNG (lib0/prng) makes every random test reproducible: failures are replayable via --seed N.

Read this whole file before writing a new test module.

File layout

• Test files live next to the source: src/foo.js ↔ src/foo.test.js. Subdirectory modules follow the same rule (src/delta/delta.js ↔ src/delta/delta.test.js).
• Every test module MUST be imported in src/test.js and registered in the object passed to runTests({...}). If you forget, CI will not run it — src/test.js is the only entrypoint that drives the whole suite (and the coverage gate).
• Never hand-write anything into types/ (generated by tsc from JSDoc).
• Don't create a foo.test.ts — the codebase is JS + JSDoc.

Test function shape

A test file exports one or more functions named test<CamelCase>. The runner (src/testing.js:579) picks up any export whose name starts with test or benchmark and calls it with a fresh TestCase.

// src/foo.test.js
import * as t from 'lib0/testing'
import * as prng from 'lib0/prng'
import * as foo from './foo.js'

/**
 * @param {t.TestCase} tc
 */
export const testFooBasic = tc => {
  t.compare(foo.double(21), 42, 'double(21) is 42')
}

/**
 * Async is fine — return a Promise and it gets awaited.
 *
 * @param {t.TestCase} tc
 */
export const testFooAsync = async tc => {
  const result = await foo.loadAsync()
  t.assert(result != null)
}

Rules that matter:

• The function name IS the test identifier. testFooBasic → displayed as foo basic. Rename carefully.
• The first character after test must be uppercase (camelCase). testfoo is treated the same as testFoo by the prefix filter but the name splitting (string.fromCamelCase) will produce an odd-looking label.
• testRepeat* or testRepeating* prefix = fuzz test: the runner re-runs the function with a fresh seed for up to --repetition-time ms (default 50ms). See src/testing.js:131,176. Use this for any property that should hold for random inputs.
• Always type the tc parameter via @param {t.TestCase} tc — without it, tc.prng is any and tsc won't catch misuse.
• If you don't need the test case, call the param _tc to silence the unused lint.

Running tests

npm test                          # full suite under c8, with coverage gate
npm run test:deno                 # same suite under Deno
npm run test-extensive            # --repetition-time 1000 --extensive (longer fuzz)
node ./src/test.js                # raw run, no coverage gate (fast iteration)
node ./src/test.js --filter REGEX # run subset
node ./src/test.js --seed 12345   # reproduce a fuzz failure
npm run debug                     # same suite, in a browser (via bin/0gentesthtml)

npm test gates on coverage (lines 97 / branches 96 / functions 94 / statements 97) — if your new module isn't hit, it'll fail even if all t.asserts pass. Run npm test once before committing.

How --filter actually works

The filter is a regex tested against the rendered line, not the function name. The rendered line is:

[<index>/<total>] <moduleName>: <uncamelized test name>

Where <uncamelized> = string.fromCamelCase(funcName.slice(4), ' '). So testRepeatRandomTextDeltaDiff in module delta renders as:

[219/235] delta: repeat random text delta diff

Consequences:

• --filter testRepeatRandomTextDeltaDiff → matches NOTHING (the camelCase name never appears in the line).
• --filter "repeat random text delta diff" → matches that one test.
• --filter "random.*delta" → matches all tests whose uncamelized name has random then delta.
• --filter "^\[219/" → matches test #219 exactly (this is what the "repeat:" hint printed after each test uses — see below).
• --filter "delta:" → matches every test in the delta module.

When telling a user how to re-run a failing test, give them the uncamelized form or the [N/ index.

Output format — how to read it

Each test prints a collapsible group followed by a one-line verdict:

[183/235] delta: delta basic api
Success: delta basic api in 328.08μs
repeat: npm run test -- --filter "\[183/"

For testRepeat* tests the verdict includes stats:

[219/235] delta: repeat random text delta diff
Success: repeat random text delta diff - 197 repetitions in 51.54ms (best: 87.57μs, worst: 9.21ms, median: 157.57μs, average: 261.6μs)
repeat: npm run test -- --filter "\[219/" --seed 4067301200

Failures look like:

[42/235] foo: something specific
  X one equals two
Failure: something specific in 512μs
repeat: npm run test -- --filter "\[42/" --seed 1234567890

Final line is always one of:

All tests successful! in 1.76s

or

> 3 tests failed

Grep patterns for efficient output filtering

When scanning a long test log, these stable patterns let you jump to what matters:

Typical debug loop: pipe the run into grep -E '^(Failure:| X |> )' to see only failing tests + their reason, then grab the --seed N --filter "\[K/" line under the failure to reproduce deterministically.

Assertions

From src/testing.js:

t.compare is almost always what you want for deep structures. Reach for compareStrings only when the visual diff matters.

Logging & instrumentation

Output inside a test is auto-collapsed when no --filter is set (so a clean full run stays readable) and auto-expanded when a filter is set (so focused debugging shows everything). See src/testing.js:151.

Fuzz / property-based testing

The testRepeat prefix

Prefix a test with testRepeat (or testRepeating) and the runner loops it for --repetition-time ms, resetting the seed each iteration:

/**
 * @param {t.TestCase} tc
 */
export const testRepeatVarUintRoundtrip = tc => {
  const n = prng.uint32(tc.prng, 0, (1 << 28) - 1)
  const enc = encoding.createEncoder()
  encoding.writeVarUint(enc, n)
  const dec = decoding.createDecoder(encoding.toUint8Array(enc))
  t.compare(decoding.readVarUint(dec), n, `roundtrip ${n}`)
}

Behavior:

• Default: 50ms of iterations (often hundreds/thousands).
• npm run test-extensive bumps repetition time to 1000ms.
• Each iteration gets a fresh seed; the first failing iteration's seed is printed in the repeat: hint so you can re-run it exactly.
• Inside the test, every random decision must come from tc.prng. Math.random() makes the failure unreproducible.

tc.prng and reproducibility

TestCase.prng is lazily created from tc.seed. tc.seed is either the CLI --seed N (if provided) or a fresh random.uint32() per iteration. So:

• node src/test.js --filter "my fuzz" --seed 42 → deterministic single run.
• Plain node src/test.js → random seeds; each Failure: line prints the seed used.

lib0/prng cheat-sheet

import * as prng from 'lib0/prng'

// Scalars
prng.bool(gen)                       // boolean
prng.int32(gen, min, max)            // signed 32-bit int [min, max]
prng.uint32(gen, min, max)           // unsigned 32-bit int [min, max]
prng.int53(gen, min, max)            // signed 53-bit int (full JS safe range)
prng.uint53(gen, min, max)           // unsigned 53-bit int
prng.real53(gen)                     // float in [0, 1)

// Strings
prng.char(gen)                       // one ASCII char 32–126
prng.letter(gen)                     // one letter a–z
prng.word(gen, minLen = 0, max = 20) // random word of letters
prng.utf16Rune(gen)                  // NOTE: name is misleading — returns one BMP char (code 0–256); see src/prng.js:140
prng.utf16String(gen, maxLen = 20)   // string of utf16Runes

// Collections & selection
prng.uint8Array(gen, len)            // random bytes
prng.oneOf(gen, array)               // uniformly pick one element

Composing complex random inputs

Wrap domain-specific generators as plain functions that take a PRNG:

/**
 * @param {prng.PRNG} gen
 */
const genUser = gen => ({
  id: prng.uint32(gen, 0, 1 << 20),
  name: prng.word(gen, 3, 12),
  active: prng.bool(gen),
  tags: Array.from({ length: prng.int32(gen, 0, 5) }, () => prng.word(gen))
})

/**
 * @param {t.TestCase} tc
 */
export const testRepeatUserSerialization = tc => {
  const u = genUser(tc.prng)
  t.compare(parse(serialize(u)), u)
}

Weighted / branching choices

prng.oneOf picks uniformly — for weighted choices, use prng.int32 plus a cutoff. For branching behavior in fuzz tests, a common pattern (from src/delta/delta.test.js) is an array of thunks selected by prng.oneOf:

prng.oneOf(gen, [
  () => doThingA(),
  () => doThingB(),
  () => doThingC()
])()

Generating random values from a schema

lib0/schema defines schemas (s.$number, s.$string, s.$object({...}), s.$union(...), s.$array(...), s.$record(k,v), s.$literal(...), etc.) and ships a matching random generator:

import * as s from 'lib0/schema'

/**
 * @type {<S>(gen: prng.PRNG, schema: S, fallback?) => s.ReadSchemaUnwrapped<S>}
 */
s.random

This recursively walks the schema and produces a conforming value (src/schema.js:1161-1243): numbers come from a salted set including -1, 0, 1, <random int53>, strings from prng.word, booleans, unions pick one branch, objects fill each key (optionals drop ~50%), arrays get 0–42 elements, records get 0–3 entries, literals pick one of their values. For types the generator doesn't natively support, pass a fallback(gen, schema) that returns a value.

import * as prng from 'lib0/prng'
import * as s from 'lib0/schema'

const $user = s.$object({
  id: s.$number,
  name: s.$string,
  tags: s.$array(s.$string),
  role: s.$union(s.$literal('admin'), s.$literal('member'))
})

/**
 * @param {t.TestCase} tc
 */
export const testRepeatUserSchema = tc => {
  const u = s.random(tc.prng, $user)
  t.assert($user.check(u))          // should always be true by construction
  t.assert(typeof u.name === 'string')
}

This is the pattern used heavily throughout src/delta/delta.test.js — e.g. delta.random(tc.prng, $d, opts) produces random DeltaBuilder instances that match a schema, which are then exercised through diff / rebase / apply invariants. For domain types with their own random generator (like Delta), prefer the domain-specific one over s.random because it understands cross-field constraints (e.g. delta.random can take a source option so generated changes are compatible with a given base state).

--extensive mode

t.extensive (src/testing.js:63) is true when --extensive is passed. Use it to gate expensive additional checks:

export const testRepeatSomething = tc => {
  // ... fast invariant check always runs ...
  if (t.extensive) {
    // expensive cross-check that would slow normal CI
  }
}

npm run test-extensive turns this on and also bumps --repetition-time to 1000.

Registering a new test module

When you add src/foo.test.js:

1. Add an import at the top of src/test.js:

   import * as foo from './foo.test.js'
   

2. Add foo to the object passed to runTests({...}).
3. Run node src/test.js --filter "^\[.*\] foo:" to confirm your tests appear and pass.
4. Run npm test once to confirm the coverage gate is still met.

Forgetting step 1 or 2 is the most common reason "my test passes locally but never ran in CI."

Checklist for writing a test file

1. Create src/<module>.test.js (or src/<dir>/<module>.test.js) next to the source.
2. import * as t from 'lib0/testing'. Add import * as prng from 'lib0/prng' if randomness is involved, import * as s from 'lib0/schema' for schema-based random values.
3. Export test<Name> (or testRepeat<Name> for fuzz) functions, each typed @param {t.TestCase} tc.
4. Use tc.prng — never Math.random() — so failures are replayable with --seed.
5. Prefer t.compare for structural equality; t.assert for booleans; t.compareStrings for long strings.
6. Register the module in src/test.js (import + entry in runTests({...})).
7. node src/test.js --filter "<module>:" → all green.
8. npm test → coverage gate still passes.