frontend-testing

Frontend Testing Guide

相關 skill 分工：

• 五型經典定義（Dummy/Stub/Fake/Spy/Mock）→ test-doubles
• Server 測試 pattern（DB / socket.io server-side）→ vitest-testing (server)
• TDD 流程 → tdd-guidelines
• Socket + pipeline test harness → fake-summoner-client
• Hook / Context 慣例 → react-hooks
• Storybook play function / 視覺回歸 → storybook-component
• 共通慣例（RTL query、userEvent）→ testing-best-practices

Core Principles

這六條依序優先，後條在前條同時成立時才考慮。

1. Testing Library first; no unit/integration split

使用者視角撰寫測試，render 有意義的最小 tree；只有一種檔名 *.test.ts / *.test.tsx，不再有 *.integration.test.* 或其他變體。

• ✅ 用 render() + testing-library query，不用 shallow render
• ✅ 斷言使用者可觀察到的結果（DOM、callback、store 狀態），不斷言實作細節
• ❌ 不在 vitest.config.ts 區分 unit / integration glob

2. Fake first — when the real external dependency is hard to use in tests

當測試對象依賴「外部系統」（網路、Socket.IO、瀏覽器 API、時間、CLI）且真實依賴不易在測試中使用時，Fake 是首選替代品。對「內部 module」的觀察仍用 Spy；完全替換整個內部 module（vi.mock）是最後手段。

決策流程見 Test Double Decision Flow。

3. Fake Component for subcomponent isolation

隔離子元件（不想連動其 deps）時，MUST 撰寫 Fake<Name> React 元件共用原 prop 型別，勝過 vi.mock('./X', () => ({ X: () => null }))。

// ❌ BAD — 失去型別檢查，重構脆弱
vi.mock('./ComposeToolbar', () => ({ ComposeToolbar: () => null }));

// ✅ GOOD — Fake Component 契約對齊
// src/test/fake-compose-toolbar.tsx
import type { ComposeToolbarProps } from '../components/ComposeToolbar';

export function FakeComposeToolbar(props: ComposeToolbarProps) {
  return <div data-testid="fake-toolbar" data-mode={props.mode} />;
}

// test
vi.mock('./ComposeToolbar', () => ({ ComposeToolbar: FakeComposeToolbar }));
// 或 test helper 透過 props 注入

好處：

• 維持 prop 型別檢查（重構 real component 時，fake 編譯錯誤提醒更新）
• 可 data-testid 斷言 parent 傳進去的 prop
• 明確可見「這是測試替身」

4. Tests live at the smallest meaningful render root

用 testing-library 時，測試 render 的是對使用者有意義的最小單位，不是對原始碼檔案一檔對一檔。

情境	要不要建專屬 .test？
純 util / store / hook	✅ 建（.test.ts / renderHook）
有自身邏輯 / state / 複雜渲染的元件（如 EffortSwitch）	✅ 建
簡單 presentational primitive（Badge / IconButton / PaletteEmpty）	❌ 不建；透過 consumer 測試覆蓋
Context / Provider	✅ 建（測 provider 本身），但簡單 state passthrough 可由 consumer 覆蓋