從矩陣到 test case 的轉換規則

每個狀態至少一個 test case

矩陣中的每一行代表畫面的一個狀態。每個狀態產生一個 test case，驗證三件事：

1. 該狀態下的顯示元素是否存在
2. 該狀態下的可用操作是否可觸發
3. 該狀態下的退出路徑是否可到達

以 app_tunnel Terminal 畫面為例，五個狀態產生五個 test case：

 1testWidgets('idle state shows blank and allows cancel', (tester) async {
 2  await tester.pumpWidget(terminalScreen(state: idle));
 3  expect(find.byType(CircularProgressIndicator), findsNothing);
 4  expect(find.byKey(Key('cancel_button')), findsOneWidget);
 5});
 6
 7testWidgets('error state shows message, retry, and back', (tester) async {
 8  await tester.pumpWidget(terminalScreen(state: error));
 9  expect(find.text('連線失敗'), findsOneWidget);
10  expect(find.byKey(Key('retry_button')), findsOneWidget);
11  expect(find.byKey(Key('back_button')), findsOneWidget);
12});

退出路徑是獨立的斷言

退出路徑驗證的是「使用者能否離開當前狀態」。斷言方式是 tap 退出按鈕後驗證導航是否發生：

1testWidgets('error state back button navigates to home', (tester) async {
2  await tester.pumpWidget(terminalScreen(state: error));
3  await tester.tap(find.byKey(Key('back_button')));
4  await tester.pumpAndSettle();
5  expect(find.byType(HomeScreen), findsOneWidget);
6});

矩陣中退出路徑為空的狀態 = 沒有退出路徑的 test case = UX 死胡同。如果在填寫 test case 時發現某個狀態沒有退出路徑可以斷言，這本身就是設計缺口的發現。

覆蓋率的衡量

Widget test 的狀態覆蓋率 = 有 test case 的狀態數 / 矩陣中的總狀態數。100% 代表矩陣中每個狀態都有對應的 test case。

狀態覆蓋率和 line coverage 衡量不同的東西。Line coverage 衡量「程式碼中有多少行被執行過」，狀態覆蓋率衡量「設計中有多少狀態被驗證過」。一個狀態的 test case 可能覆蓋很少的程式碼行（只驗證特定狀態下的 UI），但確認了該狀態的設計意圖被正確實作。

狀態轉換的 test

除了靜態狀態的驗證，狀態之間的轉換也需要 test。矩陣的「進入條件」欄定義了觸發轉換的事件。

1testWidgets('connecting transitions to connected on ws success', (tester) async {
2  await tester.pumpWidget(terminalScreen(state: connecting));
3  // 模擬 WebSocket 連線成功
4  connectionManager.emit(ConnectionState.connected);
5  await tester.pumpAndSettle();
6  expect(find.byType(TerminalView), findsOneWidget);
7});

狀態轉換 test 的數量 = 矩陣中的狀態轉換邊數。五個狀態的畫面可能有 8-12 條轉換邊，每條邊一個 test case。

狀態覆蓋和轉換覆蓋確認畫面的邏輯正確性後，導航路徑 test 進一步驗證 back 按鈕和 route 可達性。矩陣本身的填寫方法和四欄定義見 ux-design 模組一 畫面狀態矩陣。如果需要在視覺層面確認 UI 呈現的一致性，螢幕截圖比對提供 visual regression 的實作方式。

Back 按鈕 test

每個有 back 按鈕的畫面需要一個 test 驗證「按下 back 後導航到哪裡」。Back 按鈕的目標畫面依導航方式而定：

• context.push('/terminal') 進入 → back 回到推入前的畫面（首頁）
• context.go('/terminal') 進入 → back 行為依 router 設定，可能沒有上一頁

 1testWidgets('back from terminal returns to home (pushed)', (tester) async {
 2  await tester.pumpWidget(app());
 3  // 從首頁 push 到 terminal
 4  await tester.tap(find.text('Connect Terminal'));
 5  await tester.pumpAndSettle();
 6  expect(find.byType(TerminalScreen), findsOneWidget);
 7  // 按 back
 8  await tester.tap(find.byKey(Key('back_button')));
 9  await tester.pumpAndSettle();
10  expect(find.byType(HomeScreen), findsOneWidget);
11});

Route 可達性 test

Router 定義的每個路由都應該有從 UI 可達的路徑（ux-design 模組一 路由可達性）。Route 可達性 test 驗證「從首頁出發，透過 UI 操作能到達每個路由」。

 1testWidgets('enrollment route is reachable from home', (tester) async {
 2  await tester.pumpWidget(app());
 3  // 找到配對入口按鈕
 4  final enrollButton = find.text('Enroll Device');
 5  expect(enrollButton, findsOneWidget);
 6  // 點擊後到達 enrollment 畫面
 7  await tester.tap(enrollButton);
 8  await tester.pumpAndSettle();
 9  expect(find.byType(EnrollmentScreen), findsOneWidget);
10});

不可達的路由在 test 中表現為「找不到導航到該路由的 UI 元素」。如果 router 定義了 /enrollment 但首頁沒有對應按鈕，find.text('Enroll Device') 會找不到元素 — test 失敗暴露入口缺失。

go vs push 語意的 test

go 和 push 對返回堆疊的影響不同（ux-design 模組五 導航模式）。Test 需要驗證正確的導航方式被使用：

Push 語意：保留返回堆疊

Push 後按系統 back 鍵應該回到推入前的畫面。

 1testWidgets('push preserves back stack', (tester) async {
 2  await tester.pumpWidget(app());
 3  // push to enrollment
 4  await tester.tap(find.text('Enroll Device'));
 5  await tester.pumpAndSettle();
 6  // 系統 back 鍵
 7  final backButton = find.byTooltip('Back');
 8  await tester.tap(backButton);
 9  await tester.pumpAndSettle();
10  // 應該回到首頁
11  expect(find.byType(HomeScreen), findsOneWidget);
12});

Go 語意：替換路由堆疊

Go 後按系統 back 鍵的行為依 router 設定。如果 go 到的路由是根層級，系統 back 鍵可能退出 app 而非回到前一個畫面。

Test 策略：驗證 go 後的路由堆疊狀態。如果設計意圖是「切換工作區，不保留前一個畫面」，斷言系統 back 鍵不回到前一個畫面。

深層連結 test

深層連結（deep link）讓使用者從 app 外部直接進入特定畫面。Deep link test 驗證「直接導航到內部路由時，畫面和導航堆疊是否正確」。

1testWidgets('deep link to /terminal shows terminal', (tester) async {
2  await tester.pumpWidget(app(initialRoute: '/terminal'));
3  expect(find.byType(TerminalScreen), findsOneWidget);
4});

深層連結的特殊性在於使用者跳過了正常的導航流程。從首頁到 terminal 的正常流程可能經過認證 gate，但深層連結直接到 terminal — 認證 gate 是否仍然生效需要額外的 test。

下一步路由

• 狀態覆蓋策略 → Widget test 的狀態覆蓋策略
• Playwright 驗證流程 → Playwright 瀏覽器驗證流程
• 路由可達性的設計原則 → ux-design 模組一 路由可達性

Playwright 和 widget test 的互補

Widget test 在 Flutter test framework 中執行，不需要瀏覽器，驗證的是 widget tree 的結構和狀態。Playwright 在真實瀏覽器中執行，驗證的是渲染後的 DOM 和視覺呈現。

兩者的分工：widget test 驗證「邏輯上正確」（該有的元素存在、該觸發的事件發生），Playwright 驗證「視覺上正確」（元素在正確的位置、顏色和大小符合設計）。

Playwright test 的基本結構

 1import { test, expect } from '@playwright/test';
 2
 3test('terminal screen shows connection status', async ({ page }) => {
 4  await page.goto('http://localhost:8080');
 5  
 6  // 點擊連線按鈕
 7  await page.click('text=Connect Terminal');
 8  
 9  // 等待畫面轉換
10  await page.waitForSelector('[data-testid="terminal-screen"]');
11  
12  // 驗證連線狀態顯示
13  const status = page.locator('[data-testid="connection-status"]');
14  await expect(status).toBeVisible();
15});

三個位置的斷言

Playwright test 中的斷言放在三個位置，各自驗證不同的東西：

假設斷言（test 開頭）：驗證 test 的前置條件。頁面載入成功、初始狀態正確。如果假設斷言失敗，test 的後續結果不可信。

行為斷言（操作之後）：驗證 UI 操作的即時效果。點擊按鈕後 dialog 出現、表單提交後顯示成功訊息。

互動斷言（流程結束）：驗證完整操作流程的最終狀態。多步驟操作完成後畫面回到預期狀態。

Selector 策略

Playwright 用 selector 定位 DOM 元素。Selector 的穩定性決定了 test 的維護成本。

推薦：data-testid

在 HTML 元素上加 data-testid 屬性，Playwright 用 [data-testid="xxx"] 定位。data-testid 不受 CSS class 改名、文字內容變更、DOM 結構調整影響。

1<button data-testid="connect-button">Connect Terminal</button>

可接受：文字內容

用 text=Connect Terminal 定位。在按鈕文字穩定的場景下可用，但多語系支援或文案調整時會斷。

避免：CSS selector

用 .btn-primary 或 #main-content > div:nth-child(2) 定位。CSS class 和 DOM 結構的改動頻率高，test 頻繁因無關變更而失敗。

和開發伺服器的整合

Playwright test 需要一個正在運行的 web 應用。整合方式：

手動啟動：開發者先啟動 dev server，再跑 Playwright test。適合本地開發。

自動啟動：Playwright 設定檔中指定 webServer 配置，Playwright 自動啟動 dev server，test 結束後自動停止。適合 CI。

1// playwright.config.ts
2export default defineConfig({
3  webServer: {
4    command: 'npm run dev',
5    port: 8080,
6    reuseExistingServer: !process.env.CI,
7  },
8});

下一步路由

• 視覺比對 → 螢幕截圖比對
• 狀態覆蓋策略 → Widget test 的狀態覆蓋策略
• 導航路徑 test → 導航路徑 test

運作方式

建立 baseline

第一次執行時擷取每個測試畫面的螢幕截圖，儲存為 baseline。Baseline 代表「目前正確的視覺狀態」。

比對差異

後續執行時擷取當前截圖，和 baseline 逐像素比對。差異超過閾值時 test 失敗，產出 diff 圖片標示差異區域。

更新 baseline

視覺變更是刻意的（新設計、改佈局）時，用新截圖覆蓋 baseline。更新 baseline 是明確的決策 — 代表「新的視覺狀態是正確的」。

Playwright 的截圖比對

Playwright 內建 toHaveScreenshot() 方法：

1test('terminal screen matches baseline', async ({ page }) => {
2  await page.goto('http://localhost:8080/terminal');
3  await page.waitForSelector('[data-testid="terminal-screen"]');
4  
5  await expect(page).toHaveScreenshot('terminal-connected.png', {
6    maxDiffPixelRatio: 0.01,  // 允許 1% 像素差異
7  });
8});

首次執行時自動建立 baseline 截圖，後續執行時自動比對。Diff 圖片儲存在 test results 目錄。

Diff 閾值設定

像素比對的閾值影響 test 的敏感度：

過低（0.001）：anti-aliasing 差異、字體渲染微調、次像素定位變化都會觸發失敗。Test 頻繁因無關變化而失敗（flaky）。

過高（0.1）：小型 layout 偏移、顏色微調、邊框消失可能不被偵測。Test 的保護力下降。

建議起點（0.01）：允許 1% 的像素差異。能容忍 anti-aliasing 差異，同時捕捉有意義的視覺變化。根據實際 flaky 頻率調整。

Baseline 管理

版本控制

Baseline 截圖加入 git。每次視覺變更的 PR 包含 baseline 更新，reviewer 從 diff 中看到「視覺變化了什麼」。

Baseline 檔案較大（PNG，數十 KB 到數百 KB）。Git LFS 適合管理這類二進位檔案。

跨平台差異

不同作業系統的字體渲染、anti-aliasing 演算法不同。同一段 HTML 在 macOS 和 Linux 上的截圖會有微小差異。

處理策略：

• 一個平台一套 baseline：macOS 和 Linux 各自維護 baseline。CI 環境固定在一個平台。
• 只在 CI 比對：本地開發不跑截圖比對（平台差異導致 flaky），CI 環境固定平台後比對。

動態內容

畫面中有動態內容（時間戳、隨機 ID、動畫）時，截圖每次都不同。

處理策略：

• 遮蔽動態區域：截圖前用 CSS 隱藏動態元素，或在截圖比對時指定忽略區域。
• 固定動態值：test 中 mock 時間和隨機數，讓畫面內容確定。
• 只截靜態區域：用 element screenshot（locator.screenshot()）而非 full page screenshot，只截不含動態內容的區域。

和其他 test 層的關係

截圖比對是 UI test 的最外層 — 驗證視覺呈現而非邏輯行為。它和 widget test（驗證 widget 結構）、導航 test（驗證路由行為）互補：

widget test 通過但截圖比對失敗 = 邏輯正確但視覺不對（CSS bug）。截圖比對通過但 widget test 失敗 = 視覺沒變但邏輯壞了（功能 bug 還沒影響到視覺）。

下一步路由

• 狀態覆蓋策略 → Widget test 的狀態覆蓋策略
• Playwright 驗證流程 → Playwright 瀏覽器驗證流程
• 畫面狀態矩陣 → ux-design 模組一 畫面狀態矩陣