# Bun Test

> Use when creating, modifying, debugging, or running Bun tests with bun:test, including package-local test commands, async tests, mocks, spies, snapshots, and Effect.runPromise test boundaries.

- Skill: `theseus-run/bun-test` (Agent Skill)
- Install (CLI): `npx skillmds@latest add theseus-run/bun-test`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theseus-run/bun-test/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: theseus-run (https://skillmd.com/u/theseus-run)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/theseus-run/bun-test

---


# Bun Test

Use this skill for tests run by `bun test`.

## Repo Facts

- Root test command: `bun run test` -> `bun test`.
- `packages/theseus-tools` has `bun test src/`.
- `packages/jsx-md` and `packages/jsx-md-beautiful-mermaid` use package-local `bun test`.
- Tests live beside source or under `src/__tests__/`.

## Imports

```typescript
import { describe, expect, test, beforeEach, afterEach, mock, spyOn } from "bun:test";
```

Use only the APIs needed by the test. Keep setup close to the tests unless it is reused across files.

## Test Shape

- Test behavior through public exports where practical.
- Use narrow tests for boundary behavior: schema failures, typed failures, serialization, stream completion, and runtime lifecycle.
- For Effect code, run effects at the test boundary with `Effect.runPromise`.
- Assert typed failures by `_tag` and fields, not by brittle stringified output.
- For streams, assert both emitted values and completion behavior.
- For background fibers, assert interruption, shutdown, or result handoff.

## Mocks And Spies

- Use `mock` for small injected functions.
- Use `spyOn` when observing object methods.
- Restore mocks in `afterEach` when they can leak state.
- Prefer dependency injection or test layers over module mocking for Effect services.

## Commands

- Whole repo: `bun run test`.
- Specific file: `bun test path/to/file.test.ts`.
- Package scope: run the package script if present.
- Name filter: `bun test -t "pattern"`.
- Watch mode is for local iteration, not final verification.

## Anti-Patterns

- Do not leave `test.only` or focus filters in committed tests.
- Do not use sleeps to paper over async lifecycle bugs.
- Do not assert implementation details when public behavior is available.
- Do not update snapshots unless the output change is intentional and reviewed.