suaveplan/openspec/archive/2026-04-27-testing-runner-subpath/proposal.md

Add @suaveplan/testing/runner central runner subpath

Package: @suaveplan/testing Status: PROPOSED Type: feature

Why

~95 packages currently import describe, it, expect, vi, and expectTypeOf directly from vitest, which means the monorepo cannot swap, wrap, or instrument the test runner without touching ~983 files. @suaveplan/testing-dom/runner already provides this indirection for DOM packages, but DOM/React-specific dependencies make it unsuitable as the universal runner barrel. This change ports the same pattern into the universal @suaveplan/testing package so every non-DOM package can import the runner from one stable place.

What changes

• ADDED: @suaveplan/testing/runner subpath export (vitest by default, bun:test under the bun package.json condition)
• ADDED: src/runner/index.ts, src/runner/vitest.ts, src/runner/bun-test.ts, src/runner/mocks.ts exporting describe, it, test, expect, expectTypeOf, vi, beforeAll, beforeEach, afterAll, afterEach, fn<TArgs, TReturn>, spy, stub, mock, fakeClock, restoreMocks, restoreTimers, plus types RunnerMock, SpyHandle
• ADDED: expectTypeOf shim for the bun-test path (Proxy-backed no-op chain — type assertions are erased at compile time)
• ADDED: @types/bun devDependency, tsconfig.lib.json types extended with bun, and matching vite multi-entry build wiring
• ADDED: runner/mocks.test.ts and runner/runner.spec-conformance.test.ts

Out of scope

• Migrating ~983 vitest imports to the new subpath — handled in a follow-up codemod commit (genesis branch, same PR)
• DRY-linking @suaveplan/testing-dom/runner to this subpath — rule 8 forbids testing-dom from depending on @suaveplan/testing, so the two surfaces stay duplicated by design

Verification approach

• src/runner/mocks.test.ts — unit coverage for fn/spy/stub/ fakeClock/restoreMocks/restoreTimers
• src/runner/runner.spec-conformance.test.ts — type-level pins via expectTypeOf for RunnerMock<TArgs, TReturn> and SpyHandle
• 5-gate triple (bun run check, turbo lint typecheck test, turbo test:coverage 100/100/100/100, openspec-conformance, turbo build) green for @suaveplan/testing

Migration impact

Additive only. No existing exports change. Consumers continue to import the package barrel for utilities; the new ./runner subpath is the sole addition.