Writing Tests

Writing and running tests

Test file skeleton

Tests live in /tests/, named <moduleName>.test.ts (e.g. tests/shapeFns.test.ts); api*.test.ts for public-API surface tests. Extend an existing file for the module before creating a new one.

Exact boilerplate (from tests/booleanFns.test.ts):

import { describe, expect, it, beforeAll } from 'vitest';
import { initKernel } from './setup.js';
import { box, fuse, isOk, unwrap, measureVolume } from '@/index.js';

beforeAll(async () => {
  await initKernel();
}, 30000);

Rules:

• Import initKernel from ./setup.js — not initOC. initOC is a backward-compat alias (tests/setup.ts) that force-boots the legacy OpenCascade.js kernel regardless of which vitest project is running. initKernel() (tests/helpers/kernelInit.ts) reads the TEST_KERNEL env var set by the vitest project, so the same test runs correctly under all four kernels. CLAUDE.md's "Writing a test" section still names initOC; prefer initKernel.
• The 30000 is the beforeAll hook timeout (WASM boot can be slow on first run). It is NOT the per-test timeout — that is 90 s (testTimeout: 90000 in vitest.config.ts; CLAUDE.md's "30s timeout" claim is stale).
• Import the public surface from @/index.js. Cross-directory imports use the @/ alias (→ src/), always with .js extensions. Vitest globals are enabled, but files still import describe/it/expect explicitly.
• Reach for internals (@/core/shapeTypes.js, helpers in tests/helpers/) only when the public API cannot express the assertion.

Assertions

• Result handling: assert expect(isOk(result)).toBe(true) first, then unwrap(result) to get the value. Use isErr()/unwrapErr() for error-path tests. unwrap is fine in tests; production code in layers 2–3 uses isOk()/match() — see the result-error-handling skill.
• Floating point: always toBeCloseTo(expected, precision), never exact equality. Convention for unit-scale geometry: toBeCloseTo(2000, 0) (within 0.5 absolute). Round-trip serialization checks use precision 6 (tests/parity/README.md).
• Shape kinds: isSolid(), isFace(), isWire(), isCompound(), isShape3D(), or getShapeKind().
• Geometry validity: assert real measurements — unwrap(measureVolume(shape)), unwrap(measureArea(shape)) — not just "operation returned Ok".
• Cross-kernel numeric checks: expectClose(actual, expected, relTol?, absTol?) and expectKernelsAgree(valA, valB, label) from tests/helpers/kernelDivergences.ts (default relTol 1e-4).

Worked example:

describe('fuse', () => {
  it('fuses two boxes', () => {
    const result = fuse(boxA, boxB);
    expect(isOk(result)).toBe(true);
    const shape = unwrap(result);
    expect(isShape3D(shape)).toBe(true);
    expect(unwrap(measureVolume(shape))).toBeCloseTo(2000, 0);
  });
});

Running tests

Single file — always pass --project:

npx vitest run --project occt-wasm tests/booleanFns.test.ts

A bare npx vitest run tests/x.test.ts fans out to all four kernel projects (manifold, occt, brepkit, occt-wasm) and will fail on kernels the test was never gated for. This corrects the bare-run example in CLAUDE.md.

Runner facts (vitest.config.ts): pool: 'forks' with --max-old-space-size=6144; maxWorkers defaults to 4 because OCCT WASM linear memory grows monotonically per fork and more forks swap-thrash — raise locally with VITEST_MAX_WORKERS=<n>. Pre-commit runs changed-file tests (or the full coverage run with FULL_TESTS=1); pre-push runs no tests. See the quality-gates skill for the full gate stack and ci-triage for CI behavior.

Multi-kernel testing

Four vitest projects are generated from tests/helpers/kernelRegistry.ts: occt, brepkit, occt-wasm (the default and the merge gate), and manifold. Each project sets TEST_KERNEL=<id>; initKernel() and currentKernel (from ./setup.js) read it.

Decision table for a test that misbehaves on some kernel:

Never inline if (isBrepkit) ctx.skip() — the registry is the single source of truth, and docs/kernel-conformance.md is generated from it (npm run conformance:generate). Registry entry format, divergence kinds, capability flags, and the excluded-suite inventory are in references/multi-kernel.md.

Kernel-agnostic behavioral specs (closed-form reference values, fast-check invariants) live in tests/parity/ — read tests/parity/README.md before adding one. Note its gate table predates the occt-wasm default; the required gate is now the occt-wasm project.

Coverage

Root thresholds (vitest.config.ts): statements 85, branches 71, functions 91, lines 88. These are measured floors for the occt-wasm project, not aspirational targets — new code below the floor fails npm run test:full locally. Per-kernel: the occt project has its own thresholds; brepkit, occt-wasm, and manifold projects are 'informational' (thresholds enforced at the root config level for the default kernel). Each kernel's coverage excludes the other kernels' adapter dirs (coverageExcludesFor() in kernelRegistry.ts).

CI nuance: coverage is not a PR gate — the coverage job runs only on push to main with continue-on-error: true (.github/workflows/ci.yml). The enforcement point that bites during development is local npm run test:full (also pre-commit with FULL_TESTS=1). If a function-coverage miss blocks a commit, add tests for the new code rather than lowering thresholds; only re-floor after re-measuring with npm run test:full (and say so in the PR).