bun-test-patterns
/bun-test-patterns
Opisuje aktualne wytyczne dla test runnera Bun: wykrywanie testów, izolacja, równoległość, sharding, zmienione testy, mocki, timery, snapshoty, pokrycie, DOM Testing Library i sprzątanie po testach integracyjnych.
- Autor
- shepherdjerred ↗
- Repozytorium
- monorepo ↗
- Licencja
- GPL-3.0
- Ostatnia zmiana repozytorium
- 25.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 5
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.
GPL-3.0, otwarta.
Co robi i kiedy
Opisuje aktualne wytyczne dla test runnera Bun: wykrywanie testów, izolacja, równoległość, sharding, zmienione testy, mocki, timery, snapshoty, pokrycie, DOM Testing Library i sprzątanie po testach integracyjnych.
Oryginalny opis (EN)
Current Bun test runner guidance for discovery, isolation, parallelism, sharding, changed tests, mocks, timers, snapshots, coverage, DOM Testing Library, and integration teardown. Use when writing, reviewing, or configuring tests run by `bun test`.
Jak działa
- Current baseline
- Execution dimensions
- Discovery and exact paths
- Selection and flake diagnosis
- Configuration
- Lifecycle and cleanup
- Assertions
- Mocks
- Type tests
- Timers and dates
Podgląd SKILL.md
---
name: bun-test-patterns
description: Current Bun test runner guidance for discovery, isolation, parallelism, sharding, changed tests, mocks, timers, snapshots, coverage, DOM Testing Library, and integration teardown. Use when writing, reviewing, or configuring tests run by `bun test`.
---
# Bun Test Patterns
Test one coherent behavior with strong assertions, make shared state explicit, and choose concurrency, isolation, or parallel workers deliberately. A passing runtime test does not replace TypeScript type-checking.
## Current baseline
Verified against Bun 1.3.14 on 2026-08-03:
```bash
bun --version
bun test --help
```
Bun 1.3.13 added file isolation, worker-process parallelism, deterministic sharding, and Git-aware changed-test selection. Bun 1.3.14 fixed isolation/parallel crashes and a `--changed` false negative involving tsconfig path aliases. Use 1.3.14 or newer for those features.
Read [references/releases.md](references/releases.md) for the 64-page research ledger and first-party documentation contradictions. Read [references/runner-and-configuration.md](references/runner-and-configuration.md) for discovery, execution, retries, reporters, coverage, lifecycle, snapshots, and timers. Read [references/mocks-and-types.md](references/mocks-and-types.md) for mock lifecycle, module boundaries, and `expectTypeOf`. Read [references/dom-and-integrations.md](references/dom-and-integrations.md) for Happy DOM, Testing Library, Prisma, servers, and resource teardown.
## Execution dimensions
| Mode | Scope | Boundary |
| --- | --- | --- |
| Default | Files and tests sequential in one process | Global/module state can cross file boundaries |
| `--concurrent` / `test.concurrent` | Async tests overlap within files | Default maximum concurrency is 20; concurrent tests cannot use `onTestFinished` |
| `--isolate` | Fresh global per file in one process | Drains microtasks and cleans sockets, timers, and subprocesses between files |
| `--parallel=N` | Files run in worker processes | Implies isolation; choose N from CI resources |
| `--shard=M/N` | Deterministic path-sorted round-robin partition | One-based shard index; every shard must run |
Isolation changes cross-file leak risk, but it does not excuse missing cleanup inside a test.
## Discovery and exact paths
Current canonical discovery includes `test`, `spec`, and test-directory conventions across JavaScript, JSX, TypeScript, TSX, MJS, CJS, MTS, and CTS.
Positional arguments are substring filters. Prefix an exact relative path:
```bash
bun test ./src/math.test.ts
```
Do not call a positional value a glob. Use documented config/CLI ignore patterns for path selection.
## Selection and flake diagnosis
```bash
bun test --changed
bun test --changed=origin/main
bun test --randomize --seed 12345
bun test --rerun-each 20
bun test --retry 1
bun test --bail=1
```
`--changed` includes staged, unstaged, and untracked Git changes or compares against a supplied ref. With watch mode, selection is rebuilt each restart.
Retries can mask flakes. Keep zero as the normal gate; use a narrow retry only with captured reporting and remediation. Reproduce randomized failures with the printed seed.
`test.only()` restricts the run only when `bun test --only` is used. Do not leave focused tests as an implicit gate.
## Configuration
Current coverage threshold shape is plural and fractional:
```toml
[test]
coverage = true
coverageThreshold = { lines = 0.80, functions = 0.80, statements = 0.80 }
```
`branch` is not a documented threshold field. `timeout` is a CLI or per-test value, not a documented `[test]` key.
Other current settings include root and path ignores, `concurrentTestGlob`, randomization and seed, retry/rerun, coverage reporters, test-file exclusion, and coverage path ignores.
## Lifecycle and cleanup
Use async hooks when cleanup returns a promise. `onTestFinished` runs after `afterEach` but is unavailable in concurrent tests.
Restore timers, spies, environment, servers, clients, databases, and temporary files in the narrowest owner. The default runner shares process state between files.
Required CI configuration must fail fast. Do not use `skipIf(!process.env.DATABASE_URL)` to silently remove a suite CI is expected to run. `process.env.CI` is a string; compare explicit values rather than treating `"false"` as false.
## Assertions
Use as many strong assertions as prove one behavior. Avoid weak truthiness when an exact value, status, state transition, or side effect is available.
Supported Bun-specific matchers include `toBePositive`, `toContainAllKeys`, `toInclude`, and singular `toSatisfy`. These claimed matchers do not exist: `toIncludeAllMembers`, `toIncludeAnyMembers`, and `toSatisfyAll`.
For arrays:
```typescript
expect(received).toEqual(expect.arrayContaining(expected));
expect(received).toHaveLength(expected.length);
expect(received.some(predicate)).toBe(true);
expect(received.every(predicate)).toBe(true);
```
## Mocks
Mock semantics differ:
- `clearAllMocks`: call history only.
- `resetAllMocks`: call history and implementations.
- `restoreAllMocks` / `mock.restore`: restore spies/functions.
- None of these undo `mock.module` overrides.
Define mock signatures that match calls:
```typescript
const calculate = mock((first: string, second: string) => 42);
expect(calculate("a", "b")).toBe(42);
```
Prefer dependency injection or a complete module mock registered before the first import. Importing the real module to spread a partial mock already executes its side effects.
## Type tests
`expectTypeOf` is a runtime no-op. `bun test` can pass when an intended type relation is wrong. Put type assertions in a file included by the project checker and run:
```bash
bunx tsc --noEmit
```
In this monorepo, use the package's focused typecheck task.
## Timers and dates
Use `jest.useFakeTimers`, timer advancement/run/clear/count helpers, and `setSystemTime` for deterministic time. Always restore real timers and time in cleanup, especially in shared-process mode.
## Snapshots
An empty call lets Bun insert an inline snapshot:
```typescript
expect(result).toMatchInlineSnapshot();
```
Use property matchers for nondeterministic IDs/timestamps. Keep snapshots focused and review updates. Never update snapshots automatically merely because CI failed.
## DOM interaction
Prefer the dedicated Bun Testing Library setup with explicit `expect.extend(matchers)` and type declaration merging. Use `user-event` for realistic async interactions:
```typescript
const user = userEvent.setup();
await user.click(button);
```
Use `fireEvent` only for low-level events user-event cannot model.
## Integration safety
- Validate a dedicated ephemeral database identity before destructive cleanup. Do not run unrestricted `deleteMany()` against an environment-selected database.
- Prefer transactions or unique per-test records.
- Await `server.stop()`. Use forced stop only when tests must close active traffic immediately.
- Close Prisma, SQL, Redis, HTTP, file, worker, and timer resources in their owner.
- Do not skip required integration tests because an artifact or credential is missing; build/provision the prerequisite or fail with a clear error.
## Review checklist
- Verify Bun 1.3.14+ and current CLI help.
- Use exact `./path` selection and current discovery extensions.
- Distinguish concurrent tests, file isolation, parallel workers, and sharding.
- Keep retry zero normally and capture randomization seeds.
- Use the current fractional coverage schema.
- Restore timers/spies and understand that module mocks persist.
- Type mock signatures correctly and register module mocks before import.
- Run an actual TypeScript checker for type tests.
- Prefer user-event and explicit jest-dom setup.
- Protect databases and await async server/client teardown.
Pliki w paczce (5)
- SKILL.md 8 KB
- references/dom-and-integrations.md 2 KB
- references/mocks-and-types.md 2 KB
- references/releases.md 5 KB
- references/runner-and-configuration.md 3 KB
Wersje
W bazie nie ma innych skilli o nazwie bun-test-patterns.
Migawka bazy z 13.11.2026 · wersja paczki c6923e038645 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100bun-testing
Pomaga pisać testy we wbudowanym test runnerze Bun: organizacja testów, asercje, mocki i testy snapshotowe. - 96testing-bun
Podpowiada, jak pisać i zmieniać testy w projekcie Bun. - 100bun-jest-migration
Prowadzi migrację z Jest na test runner Bun: zgodność importów, mocki i konfiguracja. - 100ts-testing
Pomaga pisać i konfigurować testy TypeScript oraz wybierać między bun test a Vitest. - 100bun-test-coverage
Mierzy pokrycie testami w Bun przez flagę --coverage: raporty lcov, progi i integracja z CI. - 100bun
Pomaga korzystać z Bun jako uniwersalnego środowiska JavaScript i TypeScript, menedżera pakietów, bundlera i test runnera: serwery HTTP, pakiety, testy i migracja z Node.js.