Writing Tests

Writing Tests for opencode-swarm

Graph-first evidence contract

Use repo_map test_pack to discover focused tests for the changed source, then read the selected source and tests directly. Graph evidence is advisory only. If freshness is stale or inconclusive, confidence is low, source is missing, the language is unsupported/dynamic, the graph is absent, or the action fails, use direct source and repository test conventions to select coverage.

⚠️ Do NOT use the OpenCode test_runner tool to validate the full repo. It is for targeted agent validation with explicit files: [...] or small targeted scopes. scope: 'all' is gated behind the SWARM_ALLOW_FULL_SUITE=1 env var (intended for opt-in CI mirrors only; there is no allow_full_suite arg). Broad scopes can stall or kill OpenCode before the MAX_SAFE_TEST_FILES = 50 guard in src/tools/test-runner.ts fires. For repo validation, use the shell commands in this file — per-file isolation loops match CI behavior. See AGENTS.md invariant 6 for the full contract.

⛔ STOP — Read Before Running Any Tests

test_runner scope safety — keep every selection bounded:

convention retains one-source-file discovery semantics. For graph and impact, bounded batches of at most 50 normalized source files are permitted; when a call returns scope_exceeded, narrow or split the source selection and never widen it to scope: 'all'. The final normalized unique test resolution is capped at 50 as well. For whole-repository validation, retain the per-test-file shell loop below so each test file runs in its own process; do not replace that isolation with a broad test_runner call.

Truncated output recovery: When bun test output exceeds the bash tool buffer it is saved to a file whose ID (tool_abc123...) cannot be retrieved via retrieve_summary (which only accepts S1, S2 format). Workaround — pipe to a temp file instead:

# PowerShell (Windows)
bun --smol test tests/unit/agents --timeout 60000 | Out-File "$env:TEMP\test_out.txt"; Get-Content "$env:TEMP\test_out.txt" | Select-Object -Last 30

# bash (Linux/macOS)
bun --smol test tests/unit/agents --timeout 60000 2>&1 | tee /tmp/test_out.txt | tail -30

Framework: bun:test Only

All test files MUST import from bun:test:

import { describe, test, expect, beforeEach, afterEach } from 'bun:test';

Bun provides a vitest compatibility layer (vi.mock, vi.fn, vi.spyOn) that works on Linux and macOS. However, vi.mock() has critical isolation bugs in Bun when multiple test directories run in the same process. Prefer bun:test native APIs:

Mock Isolation Rules

CRITICAL: Module-level mocks leak across test files within the same Bun process.

Bun's --smol mode shares the module cache between test files in the same worker process. A mock.module() call in file A replaces the module globally — file B gets the mock instead of the real module. This caused ~959 failures before per-file isolation was added (#330).

Additional critical limitation (Bun v1.3.11): mock.restore() does NOT reliably restore mock.module mocks. Cross-module mocks can persist across test boundaries even after afterEach(mock.restore()) is called. Three layers of defense are required.

Rules

1. Spread the real module when mocking. Only override the specific export you need:

import * as realChildProcess from 'node:child_process';
const mockExecFileSync = mock(() => '');
mock.module('node:child_process', () => ({
  ...realChildProcess,          // preserve all other exports
  execFileSync: mockExecFileSync, // override only what you test
}));

This prevents tests from accidentally nullifying exports that other code depends on. This is mandatory for Node built-ins (node:fs, node:fs/promises, node:child_process, etc.) because other code imports the full module — returning a partial mock without spreading real exports breaks unrelated imports.

2. Use lazy binding in source code. Import the namespace, call methods at invocation time:

// GOOD — mockable via mock.module
import * as child_process from 'node:child_process';
function run() { return child_process.execFileSync('git', ['status']); }

// BAD — binds at module load, mock.module can't intercept
import { execFileSync } from 'node:child_process';

3. Always add afterEach(mock.restore()) for cross-module mocks. Even though it is unreliable in Bun v1.3.11, it provides best-effort cleanup and reduces the window of cross-file contamination. Without it, the mock persists until the process exits:

import { afterEach, mock } from 'bun:test';

afterEach(() => {
  mock.restore();
});

Exception — Windows EBUSY: Test files that spawn async child processes (e.g. pre-check-batch tests) must NOT call mock.restore() on Windows. Child process handles can hold directory locks, and mock.restore() triggers cleanup that causes EBUSY errors. These files must use describe.skipIf(process.platform === 'win32') or test.skipIf(process.platform === 'win32') for affected tests.

Intentionally skipped on Windows (async child process handles cause EBUSY):

• tests/unit/tools/pre-check-batch-sast-preexisting.test.ts
• tests/unit/tools/pre-check-batch.adversarial.test.ts
• tests/unit/tools/pre-check-batch-cwd.test.ts
• tests/unit/tools/pre-check-batch-cwd.adversarial.test.ts
• tests/unit/tools/pre-check-batch-contextdir-adversarial.test.ts
• tests/unit/tools/pre-check-batch-secretscan-evidence.test.ts
• tests/unit/tools/pre-check-batch.test.ts

4. Never create circular mock imports. This pattern deadlocks Bun:

// BROKEN — imports from the module it's about to mock
import { realFn } from '../../src/module.js';
vi.mock('../../src/module.js', () => ({
  realFn: (...args) => realFn(...args),  // circular!
  otherFn: vi.fn(),
}));

Instead, inline the function logic or extract the real functions into a separate utility module.

5. Prefer constructor/parameter injection over module mocking. The swarm's hook factories (createScopeGuardHook, createDelegationLedgerHook, etc.) accept injected dependencies — test them by passing mock callbacks, not by replacing modules.

6. Mock validateDirectory when testing with Windows temp paths. The path-security.ts validator rejects Windows absolute paths (C:\...). If your test uses os.tmpdir() and passes that path to a function that calls validateDirectory, mock it:

mock.module('../../../src/utils/path-security', () => ({
  validateDirectory: () => {},
  validateSwarmPath: (p: string) => p,
}));

Diagnosing Test Isolation Failures

When test files pass individually but fail when run together, follow this protocol:

1. Isolate: Run the failing file alone: bun test <file>.test.ts --timeout 30000
2. Pair: Run it WITH its suspected polluting neighbor: bun test <fileA>.test.ts <fileB>.test.ts
3. Classify:
   • Both pass alone → fail together → mock pollution from neighbor
   • Fails alone → test logic bug (not isolation issue)
   • Passes alone + passes together but fails in full suite → third-file pollution (use binary search across directory)
4. For mock pollution, check the neighbor for these patterns:
   • vi.mock() or mock.module() inside beforeEach() (not at top level)
   • delete require.cache[...] combined with re-import pattern
   • These indicate hoist-time closure capture — see below
5. Specific symptom — closure capture failure: vi.mock() captures closures at hoist time (before beforeEach runs). Reassigning mockFn.mockImplementation(newFn) in the test body does NOT update the hoisted closure — the mock still calls the original function.
   • Symptom: expect(mockFn).toHaveBeenCalledTimes(N) fails with an unexpected count
   • Symptom: expect(mockFn).not.toHaveBeenCalled() fails because the real function was called
6. Fix path: Migrate the affected test file to the _internals DI seam pattern documented above (opencode-swarm repository contributors also have a dedicated mock-to-internals-migration skill that walks the recipe in depth). This eliminates both the vi.mock() call and the closure capture surface area. Exception — reference-captured functions: if the source code passes a function as a direct argument or captures it in a closure at module scope (e.g., transactFile(path, readKnowledge, ...)), the reference bypasses _internals entirely — mutating _internals.readKnowledge changes only the object property, not the module-scope binding the source already holds. Migrating to _internals does not help. In that case, test via observable outcomes (e.g., run concurrent callers and assert on final persisted state).

Two-Tier Mock Convention

The codebase uses a two-tier strategy for mock isolation, plus a zero-mock testing pattern:

Tier 0: _test_exports Pure Function Testing (Zero Mocks)

When a module contains internal utility functions (formatters, normalizers, transformers) that don't need external dependencies, export them via a _test_exports object for direct unit testing. This avoids mock.module entirely and produces tests that are deterministic, fast, and immune to Bun's cross-file mock leakage:

// In source file (src/tools/formatter.ts)
function formatEntry(entry: SomeType): string {
  // internal implementation — may use optional chaining, defaults, etc.
  return entry.score?.toFixed(2) ?? 'N/A';
}

// Public API (tool handler, command handler, etc.)
export function handleQuery(ctx: Context) {
  const entries = readData(ctx);
  return entries.map(formatEntry);
}

// Export seam for testing — only used by test files
export const _test_exports = { formatEntry };

// In test file (tests/unit/tools/formatter.test.ts)
import { _test_exports } from '../../../src/tools/formatter';

const { formatEntry } = _test_exports;

describe('formatEntry', () => {
  test('handles missing score', () => {
    expect(formatEntry({ score: undefined })).toBe('N/A');
  });
  test('formats numeric score', () => {
    expect(formatEntry({ score: 0.85 })).toBe('0.85');
  });
});

When to use Tier 0 vs Tier 1:

• Tier 0 (_test_exports): The function is a pure utility (formatter, normalizer, transformer) that doesn't call external modules. No mocking needed — test it directly.
• Tier 1 (_internals): You need to mock a function within the same module to test the caller in isolation. The function has side effects or calls external APIs.
• Tier 2 (mock.module): You need to mock a dependency from another module (Node built-ins, other application modules).

Benefits of Tier 0:

• Zero mock pollution — no mock.module calls, no mock.restore() needed
• Works in batch test runs without per-file isolation
• Type-safe (the exported object carries the real TypeScript types)
• No filesystem dependencies (no tmpDir, no chdir, no existsSync)
• Deterministic on all platforms and CI environments

Tier 1: _internals DI Seams (Within-Module)

For mocking functions within the same module, source files export an _internals object that wraps key functions. Tests can replace individual functions without using mock.module:

// In source file (src/services/my-service.ts)
export const _internals = {
  helperFn: () => { /* real implementation */ }
};

export function mainFn() {
  return _internals.helperFn();
}

// In test file
import { _internals, mainFn } from '../../../src/services/my-service';

test('mainFn uses mocked helper', () => {
  const original = _internals.helperFn;
  _internals.helperFn = mock(() => 'mocked');
  // ... test ...
  _internals.helperFn = original; // restore
});

Benefits:

• No process-global mock pollution
• Type-safe
• Fast (no module re-parsing)
• Works in batch test runs without isolation

Critical limitation — reference-captured functions: _internals interception requires the source code to read _internals.fn at the call site. When a function is instead passed as a direct argument or captured in a closure at module definition time, replacing _internals.fn has no effect — the mock is silently ignored and the real function runs.

// Source: readKnowledge is captured at definition time, NOT via _internals
export async function transactKnowledge(filePath: string, mutate: Fn) {
  return transactFile(filePath, readKnowledge, ...);  // direct ref, captured at definition time
}
export const _internals = { readKnowledge };  // mutating this does NOT affect the closure above

// Test — mock is silently ignored; real readKnowledge still runs
const orig = _internals.readKnowledge;
_internals.readKnowledge = mock(() => []);  // only mutates the object property
await transactKnowledge(path, mutate);      // still calls the real readKnowledge
_internals.readKnowledge = orig;

When _internals interception cannot work, verify observable outcomes instead: run concurrent callers and assert on final persisted state. See tests/unit/hooks/knowledge-application.test.ts ("two concurrent bumpCountersBatch calls") for the pattern.

Tier 2: mock.module (Cross-Module)

When mocking dependencies from other modules (especially Node built-ins), use mock.module with proper cleanup:

import * as realFs from 'node:fs/promises';

mock.module('node:fs/promises', () => ({
  ...realFs,  // MUST spread real exports
  readFile: mock(() => Promise.resolve('mocked')),
}));

afterEach(() => mock.restore());

Critical rules for cross-module mocks:

1. Always spread real exports for Node built-ins — other code depends on exports you don't mock
2. Always add afterEach(mock.restore()) — provides best-effort cleanup
3. Run in per-file isolation — CI runs each file in its own process (for f in *.test.ts; do bun --smol test "$f"; done)

Choosing Between Tiers

Mock Coverage Documentation

When a test fixture mocks fewer than 100% of a target function's branches, the test MUST document, in a comment, which paths/branches are untested and the rationale for not covering them. Partial-coverage mock decisions must be explicit and reviewable instead of silent.

Why this matters

A narrow mock can produce hollow coverage: the test passes because the mocked path returns a favorable result, but downstream branches that the real code would exercise remain untested. When the unmocked branches later fail, the failure is misdiagnosed as an unrelated regression because the test appeared to cover the caller.

Motivating case: tests/unit/turbo/lean/runtime-conformance.test.ts:457 mocks only readCriticEvidence → APPROVED, leaving downstream gates (retrospective evidence, drift-verifier, completion-verify) unmocked. The assertion expect(parsed.status).not.toBe('blocked') passed, but coverage was hollow. A later failure was initially misdiagnosed as an unrelated minification regression because the test gave false confidence that the caller's gate sequence was exercised.

Required comment format

For any mock that does not cover all branches of the target function, add a comment near the mock declaration listing:

1. Which branches/paths are untested.
2. Why they are not covered in this test (e.g., "covered by runtime-conformance.complete.test.ts", "requires live critic evidence store", "tested at integration level in tests/integration/...").

// Example — partial mock with documented coverage gap
mock.module('../../../src/turbo/lean/runtime-conformance', () => ({
  ...realModule,
  // readCriticEvidence mocked to APPROVED only.
  // Untested branches: RETRY, REJECT, and the downstream gates
  // (retrospective evidence, drift-verifier, completion-verify) that
  // depend on non-APPROVED critic verdicts. Rationale: those paths
  // are covered by tests/unit/turbo/lean/runtime-conformance.complete.test.ts.
  readCriticEvidence: mock(() => 'APPROVED'),
}));

This requirement applies to all three mock tiers (_test_exports, _internals, mock.module) whenever the mock narrows the exercised branch set.

mock.module() Export Completeness

When using mock.module() (or vi.mock()) with Bun's test runner, the mock factory MUST provide stubs for ALL named exports of the target module — not just the ones your test calls. Bun validates the export set at dynamic-import time and throws SyntaxError: Export named 'X' not found if any export is missing.

Why this matters

Transitive imports may reference exports your test never calls directly. For example, if your test mocks config/schema.js and only uses stripKnownSwarmPrefix, but a transitive dependency imports PluginConfigSchema from the same module, the mock MUST include PluginConfigSchema as a stub — even though your test never calls it.

When the source module gains new exports (e.g., a PR adds 50 new Zod schemas to config/schema.ts), ALL existing mock.module() calls targeting that module must be updated — even if the new exports are irrelevant to your test.

How to verify completeness

Before finalizing a test that uses mock.module():

1. List all runtime exports of the target module (type-only exports are erased at compile time and need no stub):

   grep -E "^export (const|function|async function|class) " src/path/to/module.ts

   Note: Do NOT include type or interface exports — Bun erases these at compile time and they need no runtime stub.
2. Ensure every export name has an entry in your mock.module() factory.
3. Stubs can be minimal:
   • Functions: () => null or async () => {}
   • Zod schemas: use a comprehensive stub that supports common methods:

     const zodStub = {
       parse: (v: unknown) => v,
       safeParse: (v: unknown) => ({ success: true as const, data: v }),
       parseAsync: async (v: unknown) => v,
     };

   • Constants: appropriate zero values ('', 0, null, [], {})

Verification pattern

// ✅ CORRECT — all exports provided, test uses only the first one
mock.module('../../../src/config/schema.js', () => ({
  // The one export your test actually uses
  stripKnownSwarmPrefix: mockStripFn,
  // Stubs for transitive import resolution (never called in test)
  PluginConfigSchema: zodStub,
  ScoringConfigSchema: zodStub,
  isKnownCanonicalRole: () => false,
  // ... all other runtime exports as stubs
}));

// ❌ WRONG — missing exports cause SyntaxError at module-load time
mock.module('../../../src/config/schema.js', () => ({
  stripKnownSwarmPrefix: mockStripFn,
  // Missing: PluginConfigSchema, ScoringConfigSchema, etc.
  // → "SyntaxError: Export named 'PluginConfigSchema' not found"
}));

What IS and IS NOT test theater

Adding stubs for ESM resolution is NOT test theater — it's a Bun runtime requirement. The distinction:

The stubs exist solely to satisfy the module loader. Test assertions must verify behavior through the real-mocked functions (the ones your test actually calls), not through the stubs.

Files Intentionally Using File-Scoped Mocks

Some test files use top-level mock.module that must persist across all tests in the file. These files use mockReset()/mockClear() in beforeEach instead of mock.restore() in afterEach:

• src/__tests__/preflight-phase.test.ts — mocks plan/manager and preflight-service

Cross-Platform Test Patterns

Tests run on all three CI platforms (ubuntu, macos, windows). Path and filesystem behavior differs between them. Follow these patterns to prevent platform-specific failures:

Mock keys with filesystem paths

Never hardcode Unix-format paths as mock keys. On Windows, path.resolve('/dir', 'file') produces drive-letter-prefixed paths like D:\dir\file, not /dir/file. A mock that checks for /dir/file will silently never match, causing the test to behave differently on Windows.

Use path.resolve() to construct mock keys the same way the source code does:

// ❌ WRONG — fails on Windows (mock expects '/safe/dir/linked.ts',
//    but path.resolve('/safe/dir', 'linked.ts') = 'D:\safe\dir\linked.ts')
mockRealpathSync.mockImplementation((inputPath: string) => {
  if (inputPath === '/safe/dir') return '/safe/dir';
  if (inputPath === '/safe/dir/linked.ts') return '/outside/linked.ts';
  return inputPath;
});

// ✅ CORRECT — path.resolve produces matching keys on all platforms
const mockDir = path.resolve('/safe/dir');
const linkedResolved = path.resolve(mockDir, 'linked.ts');
const outsideResolved = path.resolve('/outside/linked.ts');

// mockRealpathSync is a mock() function (bun:test) — see mocking patterns above
mockRealpathSync.mockImplementation((inputPath: string) => {
  if (inputPath === mockDir) return mockDir;
  if (inputPath === linkedResolved) return outsideResolved;
  return inputPath;
});

Symlink behavior differences

• On Windows, fs.symlinkSync for directories creates junctions by default, which resolve differently than POSIX symlinks. Junction creation may require administrator elevation on older Node.js versions.
• fs.realpathSync on a broken symlink throws ENOENT on POSIX but may throw EINVAL on Windows, depending on symlink type.
• Use test.skipIf(process.platform === 'win32') for tests that directly manipulate filesystem symlinks, unless the test's purpose is explicitly to verify cross-platform symlink behavior.

Temporary directory patterns

• Use os.tmpdir() + path.join() for temp paths. Never hardcode /tmp or C:\.
• Wrap mkdtempSync in realpathSync if the result is chdir'd on macOS (temp dirs are often symlinked to /private/var/...).
• Clean up temp dirs in afterEach or afterAll with a bounded helper that verifies the resolved cleanup target is a child of os.tmpdir() before calling recursive rm. Reuse tests/helpers/safe-test-dir.ts when possible. Do not call recursive rm on a computed path unless the helper has rejected empty strings, os.tmpdir() itself, and paths outside the temp root.

Platform-specific environment variable redirection

When tests redirect process.env.HOME to isolate path-resolver-dependent code (functions like resolveHiveKnowledgePath, resolveSwarmKnowledgePath, or any function that reads os.homedir() / platform env vars), they MUST redirect ALL platform-specific env vars, not just HOME. A partial redirect silently falls back to the real user profile on some platforms, causing tests to read/write actual user data instead of the isolated temp directory.

Per-platform requirements:

• Linux: redirect HOME, XDG_CONFIG_HOME, and XDG_DATA_HOME.
• macOS: redirect HOME (macOS resolves ~/Library/Application Support from the home directory).
• Windows: redirect HOME, LOCALAPPDATA, AND APPDATA. Windows path resolvers read LOCALAPPDATA and APPDATA, neither of which is derived from HOME. Redirecting only HOME silently fails on Windows, causing tests to touch the real %LOCALAPPDATA% and %APPDATA% trees.

⚠️ Bun caches os.homedir() on first call. If a module calls os.homedir() before the test sets process.env.HOME, the cached value persists for the lifetime of the process and later env changes are silently ignored. Set process.env.HOME (and other redirected vars) before importing any module that calls os.homedir(). The source code documents this at src/hooks/knowledge-store.ts: "Bun caches os.homedir(), so changing $HOME after first call is ignored."

Use per-variable save/restore rather than saving and replacing the entire process.env object — the latter discards process-level env state and can interfere with other test infrastructure:

import { beforeEach, afterEach } from 'bun:test';
import os from 'node:os';
import path from 'node:path';

const saved = {
  HOME: process.env.HOME,
  LOCALAPPDATA: process.env.LOCALAPPDATA,
  APPDATA: process.env.APPDATA,
  XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
  XDG_DATA_HOME: process.env.XDG_DATA_HOME,
};

beforeEach(() => {
  const isolatedDir = path.join(os.tmpdir(), 'test-home');
  process.env.HOME = isolatedDir;
  process.env.LOCALAPPDATA = isolatedDir;
  process.env.APPDATA = isolatedDir;
  process.env.XDG_CONFIG_HOME = isolatedDir;
  process.env.XDG_DATA_HOME = isolatedDir;
});

afterEach(() => {
  for (const [key, value] of Object.entries(saved)) {
    if (value === undefined) delete process.env[key];
    else process.env[key] = value;
  }
});

For cross-file isolation (tests that must survive across multiple files in the same process, e.g. batch steps), use beforeAll / afterAll with the same per-var save/restore pattern. Never mutate process.env without restoring it in a matching teardown hook.

Preferred approach: Use createIsolatedTestEnv() from tests/helpers/isolated-test-env.ts. It handles XDG_CONFIG_HOME, APPDATA, LOCALAPPDATA, and HOME with correct per-variable save/restore and returns a cleanup function that removes the temp directory. Use this helper unless your test has specific requirements it doesn't cover.

Line ending normalization

Git on Windows converts LF to CRLF by default. Tests that compare file contents byte-by-byte against expected strings must normalize line endings:

const actual = readFileSync(path, 'utf-8').replace(/\r\n/g, '\n');

CI Pipeline Structure

The CI runs on three platforms (ubuntu, macos, windows). Tests are split into 6 logical steps within each platform's job. (CI distributes files across shards via round-robin — see TESTING.md's CI Pipeline Steps table for the authoritative directory lists.)

Step 1a: hooks (mock.module files — 15 files) — per-file isolation (dedicated step)
Step 1b: hooks (remaining groups)               — per-file loop per group
Step 2:  cli                                     — batch
Step 3:  commands, config                        — batch
Step 4:  tools                                   — per-file loop
Step 5:  services, build, quality, sast, sbom, scripts — per-file loop
Step 6:  adversarial, agents, background, context, diff, evidence, git, helpers,
         knowledge, lang, output, parallel, plan, session, skills, types, utils — per-file loop

Per-file isolation (steps 1a, 1b, 4-6): each .test.ts file runs in its own bun --smol process to prevent mock.module() cache poisoning (#330). Steps 2-3 run files in batch because they have fewer mock conflicts. CI partitions the gated test set into 6 shards round-robin per platform (no hardcoded file lists), with a per-file retry budget (two retries / three attempts before a failure is treated as real) and quarantine filters (scripts/ci/quarantined-tests.txt, plus -macos/-windows overrides) that drop known pre-existing failures.

When writing a test, know which step your file will run in. In batch steps, do not assume isolation from other files in the same step.

Job timeout: 40 minutes. A hanging shard will kill the entire platform's test run; CI invokes the shared scripts/ci/repository-validation.ts authority, which caps each isolated file at 120 s and allows 180 s for process-tree cleanup. The historical run-test-with-timeout.ts helper is not the CI execution path.

File Placement

Convention

Naming

• Base test: <module>.test.ts
• Adversarial variant: <module>.adversarial.test.ts

Only create an adversarial variant if it tests distinct attack vectors not covered by the base test. Do not duplicate base test assertions with different inputs — that's redundancy, not security coverage.