Widget-Test on Tarragon

Widget test 的狀態覆蓋策略

Fri, 19 Jun 2026 00:00:00 +0000

Widget test 的狀態覆蓋策略是用畫面狀態矩陣（ux-design 模組一）作為 test case 的來源。矩陣的每一行（一個狀態）對應至少一個 test case，矩陣的每一欄（顯示 / 可用操作 / 退出路徑）對應該 test case 中的斷言。

從矩陣到 test case 的轉換規則

每個狀態至少一個 test case

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

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

以 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 的實作方式。

導航路徑 test

Fri, 19 Jun 2026 00:00:00 +0000

導航路徑 test 驗證的是使用者在畫面之間的移動是否符合設計 — 每個畫面的 back 按鈕是否導向正確的上層畫面、每個 router 定義的路由是否從 UI 可達、go 和 push 的語意是否產生正確的返回堆疊。

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 模組一路由可達性

模組四：自動化 UI 驗證

Fri, 19 Jun 2026 00:00:00 +0000

回答「畫面上的東西是否如設計工作」。狀態矩陣直接轉成 test case。

待寫章節

Widget test 的狀態覆蓋策略（從狀態矩陣推導 test case）
導航路徑 test（back 按鈕、route 可達性）
Playwright 瀏覽器驗證流程
螢幕截圖比對（visual regression）

跨分類引用

← ux-design 模組一畫面狀態機：狀態矩陣是 test case 的 SOT
← ux-design 模組五導航模式：go vs push 語意影響 test 斷言

Widget-Test on Tarragon

Widget test 的狀態覆蓋策略

從矩陣到 test case 的轉換規則

每個狀態至少一個 test case

退出路徑是獨立的斷言

覆蓋率的衡量

狀態轉換的 test

導航路徑 test

Back 按鈕 test

Route 可達性 test

go vs push 語意的 test

Push 語意：保留返回堆疊

Go 語意：替換路由堆疊

深層連結 test

下一步路由

模組四：自動化 UI 驗證

待寫章節

跨分類引用

`go` vs `push` 語意的 test