Bun mock module isolation

Skill kjuhwa/skills-hub/skills/testing/bun-mock-module-isolation

Split per-package Bun tests into multiple `bun test` invocations to avoid irreversible `mock.module()` cache pollution.From its SKILL.md

Install

npx -y skills add kjuhwa/skills-hub --skill bun-mock-module-isolation

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.3 KB, 732 tokens by cl100k_base, as published. Nobody here has run it

Bun `mock.module()` Test Batching for Cross-File Isolation

When to use

You are on Bun and have multiple test files that each call mock.module(path, ...) for the same module path with different implementations.
You see ~dozens of unexplained failures only when tests are run together, but they pass individually.
You cannot migrate off Bun's mock API but need reliable CI runs.

Bun's mock.module() permanently rewrites the module in the process-wide cache. mock.restore() does not undo it (oven-sh/bun#7823). The only reliable isolation is a fresh process per conflicting group.

Steps

Identify conflict groups. Grep your test files for mock.module('<path>'. Any path that appears in two or more files with different return shapes is a conflict group.
Assign each conflict group its own bun test invocation inside the package's test script. Keep non-conflicting files grouped together for speed.
Keep the root bun test-from-repo-root command off-limits. Document it in CLAUDE.md / CONTRIBUTING.md — root-level bun test discovers everything and reintroduces pollution.
Prefer spyOn() for intra-package mocking. spy.mockRestore() does work; use it whenever the target is imported by another file in the same package.
When adding a new test file that calls mock.module(), check whether the same path is mocked elsewhere and, if so, add the new file to its own bun test invocation in package.json.

Example package.json shape (shortened):

{
  "scripts": {
    "test": "bun test src/a.test.ts && bun test src/b.test.ts && bun test src/group-c/"
  }
}

Archon's @archon/core splits into 7 batches, @archon/workflows into 5, @archon/adapters into 3, @archon/isolation into 3.

Counter / Caveats

Each extra invocation adds ~JVM-like Bun startup cost; don't split gratuitously. Group non-conflicting files together.
spyOn is not a substitute when the target is in a different package imported via workspace resolution — in practice mock.module() is the only Bun tool that rewires transitive imports.
Root-level bun test is still useful for quick single-file checks; the batching rule is about CI and bun run test.

Evidence

Archon root CLAUDE.md (lines 131-133) codifies the "Do NOT run bun test from the repo root" rule and explains why: discovering all files in one process causes ~135 mock pollution failures.
packages/core/package.json scripts.test chains ~8 &&-separated bun test invocations, grouping files that conflict on shared mocks.
Archon issue reference in the CLAUDE.md comment: Bun oven-sh/bun#7823.
Commit SHA: d89bc767d291f52687beea91c9fcf155459be0d9.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most test skills give in 732 tokens

Counted across 964 of the 1,571 authors here whose files we hold, read 2026-08-07

Close the browser when donein 55 of 964, across 12 files
Wait for network idle statein 51 of 964, across 6 files
Launch Chromium in headless modein 49 of 964, across 6 files
Use descriptive selectors for elementsin 49 of 964, across 6 files
Run provided scripts with help flag firstin 49 of 964, across 6 files
Add appropriate explicit waitsin 48 of 964, across 5 files
Use bundled scripts as black boxesin 46 of 964, across 3 files
Do not read script source codein 46 of 964, across 3 files
Use sync playwright for scriptsin 46 of 964, across 3 files
Inspect dom before executing actionsin 46 of 964, across 3 files
Run the full test suitein 37 of 964
Write the failing test firstin 29 of 964, across 23 files

Said here and by no other author read

group tests by mock.module conflict groups
assign each conflict group its own bun test invocation
keep non-conflicting test files grouped together
use spyOn for intra-package mocking
check for mock path conflicts in new test files
add new conflicting test files to separate invocations

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.