fusengine/ts-testing

TypeScript Testing

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

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

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 | Single process, experimental coverage, mock limits | | Vitest | V8/Istanbul coverage, multi-worker CI scaling, ~Jest parity, browser mode | Needs Vite + 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