ts-testing

It also covers coverage thresholds, deterministic test isolation, and the rule to never mix bun:test and vitest imports in one package, or run bun test when the configured runner is actually Vitest.

Out of scope: framework-specific testing (React components → react-expert's react-testing, Laravel → laravel-testing) and browser E2E suites are not covered.

TypeScript Testing

Pick the right runner, then write tests with a shared Jest-compatible API.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Detect existing runner, config, test layout
2. fuse-ai-pilot:research-expert - Verify latest bun test / Vitest docs via Context7/Exa
3. mcp__context7__query-docs - Check mock, coverage, config APIs

After implementation, run fuse-ai-pilot:sniper for validation.

---

Overview

Both runners share a Jest-like API (describe/it/expect, lifecycle hooks, snapshots, mocks). They differ on speed, coverage maturity, and CI scaling.

Runner	Strength	Weakness
bun test	Fastest cold start, zero-config TS/JSX, built-in; --parallel workers + --shard (1.3.13+)	Single process unless --parallel, experimental coverage, mock limits
Vitest	V8/Istanbul coverage, multi-worker CI scaling, ~Jest parity, browser mode	Needs Vite (peer dep in 5.x) + config, slower cold start

---

Critical Rules

1. One runner per package - Never mix bun:test and vitest imports
2. bun run test, not bun test, when the runner is Vitest - Else Bun runs its own
3. Explicit coverage thresholds - Fail CI below target, don't just report
4. Deterministic tests - Isolate shared state; use --randomize (Bun) to catch order bugs
5. Mock at boundaries - Network/FS/time, never internal implementation detail

---

Decision Guide

Choosing a runner?
├── Greenfield, Bun runtime, fast local TDD → bun test
├── Large suite / heavy CI parallelism → Vitest (multi-worker)
├── Migrating from Jest / need full coverage → Vitest (V8 + Istanbul)
├── Component/DOM in real browser → Vitest browser mode (Playwright)
└── Zero-dependency script or CLI → bun test

→ See references/choosing-runner.md for the full matrix

---

Reference Guide

Concepts

Topic	Reference	Load when
Runner selection	references/choosing-runner.md	Deciding bun test vs Vitest
Bun test runner	references/bun-test.md	Using bun test
Vitest	references/vitest.md	Using Vitest
Shared API	references/common-patterns.md	Writing describe/it/mock/snapshot

Templates

Template	Use Case
references/templates/bun-setup.md	bunfig.toml + first Bun tests
references/templates/vitest-setup.md	vitest.config.ts + coverage + CI

---

Quick Start

Bun

import { test, expect } from "bun:test";

test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

bun test --coverage

→ See references/templates/bun-setup.md

Vitest

import { test, expect } from "vitest";

test("adds 1 + 2", () => {
  expect(1 + 2).toBe(3);
});

npx vitest run --coverage

→ See references/templates/vitest-setup.md

---

Best Practices

DO

• Colocate tests as *.test.ts next to source
• Assert inside every waitFor/async block
• Set per-test timeouts for network-bound tests

DON'T

• Mix both runners in one package
• Rely on test execution order
• Ship experimental Bun coverage as the sole quality gate on huge suites