writing-tests

Import describe, test, expect, mock, and spyOn from bun:test, place the file under tests/unit/ matching the source directory, and follow the two-tier mock convention. Run tests with per-file shell loops like bun --smol test <file> --timeout 60000 rather than broad test_runner scopes.

Bun's --smol mode shares the module cache between test files in one process, so mock.module calls leak across files. Diagnose by running the file alone, then paired with its suspected polluting neighbor, and migrate to the _internals DI seam pattern to eliminate the pollution.

Use _internals seams to mock functions within the same module you are testing, and mock.module only for cross-module dependencies like Node built-ins. Note that _internals cannot intercept functions captured by reference at module definition time; test those via observable outcomes instead.

Bun validates the full export set at dynamic-import time, so the mock factory must stub every runtime export of the target module, not just the ones your test calls. List exports with grep and provide minimal stubs such as a generic Zod stub for schemas.

Construct mock keys with path.resolve instead of hardcoded Unix paths, redirect HOME, LOCALAPPDATA, and APPDATA together when isolating environment variables, and skip tests spawning async child processes on Windows using test.skipIf(process.platform === 'win32') to avoid EBUSY errors.

No. The test_runner scope 'all' is gated behind the SWARM_ALLOW_FULL_SUITE=1 environment variable and multi-file convention or graph scopes are rejected by a scope_exceeded guard. Use per-file shell loops matching CI behavior for repo-wide validation.