# Flutter E2E 測試怎麼做得更完整：Patrol、marionette、e2e 的分工，AI 該放在哪裡

> 同一個 app、同樣四條流程實測：哪些交給腳本把關，哪些交給 AI agent 幫忙

- Author: Yii Chen (https://yiichenhi.com/about/)
- Published: 2026-11-13
- Language: zh-Hant
- Canonical: https://yiichenhi.com/writing/flutter-e2e-patrol-marionette-e2e/

---
寫 Flutter E2E 測試一段時間後，大家應該都會碰到幾個問題：官方的 integration_test 點不到系統權限彈窗，UI 改一個 key 腳本就整排紅掉，而這一年 AI agent 測試工具越來越多，看起來什麼都能自動化，卻又不確定能不能放心交給它擋 merge。所以我一直在想，要讓 Flutter 的測試更完整，哪些部分應該交給腳本，AI 又該放在哪裡才真正有用。

上一篇[〈你的 widget tree 已經是一份選項清單〉](https://yiichenhi.substack.com/p/widget-tree-jev-flutter)跟大家分享了用 Jev 這個只會挑選項的便宜模型，讓 AI agent 跑 Flutter E2E 測試的結果。這次我把範圍拉大，用同一個 demo app、同樣四條流程，在 iOS 模擬器上實測三個工具：Patrol、marionette 和 e2e。判定方式跟上一篇一樣，直接讀取 app 裡實際存了什麼，這篇文章想跟大家分享結果和最後的分工。

## 先來認識這次的工具

文章裡會一直提到幾個工具，我們先花一點時間認識它們，以及為什麼這次會選它們：

- [**Patrol**](https://patrol.leancode.co/) → 波蘭團隊 LeanCode 開發的 Flutter E2E 框架。Flutter 官方的 integration_test 碰不到系統權限彈窗，Patrol 在原生端多接了 UIAutomator / XCUITest，測試一樣用 Dart 寫，卻可以按下彈窗上的「允許」，也能直接檢查 app 裡的資料，所以這次由它負責把關
- [**marionette**](https://github.com/leancodepl/marionette_mcp) → 同樣是 LeanCode 的開源工具，讓 Claude Code 這類 coding agent 連上執行中的 Flutter app，看得到畫面上的 widget，也可以自己點擊、自己打字。很適合開發中快速驗證，上一篇就是靠它把 widget tree 交給 Jev
- [**e2e**](https://e2e.com/) → TesterArmy 開發的 TypeScript 測試框架，測試裡可以混用固定的 locator 和 AI agent 的步驟，agent 跑通一次就會錄下來，之後不呼叫模型直接重播，畫面變了才交還給 agent。它從 app 外面操作，所以可以測真正要上架的正式包
- [**Jev**](https://typesafe.ai/blog/introducing-system-one-models-and-jev) → TypeSafe 推出的小模型，只會從給定的選項裡挑一個，不會自己產生文字，所以又快又便宜，要打字的地方則另外搭配一個 LLM

### 為什麼是這三個

Flutter 的 E2E 方案其實不少，我一開始整理了七個，下面這張表放了最常被拿來比較的五個。大家可以發現每個工具都有做不到的事，所以我沒有打算只挑一個，而是看誰能補上誰的缺口：

![每個工具都有做不到的事，所以才需要分工：Patrol 看得到 Key、能按系統彈窗、適合擋 merge，但 Key 改名就要修腳本；marionette 看得到 Key、改名後靠 AI 還能跑，但碰不到系統彈窗，也不適合擋 merge；e2e 從外面操作，能測正式包，也支援 iPhone 實機，但看不到 Key；Maestro 適合擋 merge、不用模型費用，但不支援 iPhone 實機；Flutter 官方的 integration_test 碰不到系統彈窗，UI 改名腳本就壞](https://img.yiichenhi.com/9a3fcb2aec7bd45e/1400.webp)

表格裡沒有選進來的兩個，也跟大家說明一下原因：

- Flutter 官方的 integration_test → Patrol 就是建立在它之上，它能做的事 Patrol 幾乎都能做，還多了系統彈窗，所以我直接使用 Patrol
- [Maestro](https://github.com/mobile-dev-inc/maestro) → 我之前也用過，用 YAML 寫流程，會自動等待畫面載入，改完測試檔還會自己重跑，不需要重新編譯，用起來非常順手。它跟 e2e 一樣從 app 外面操作，而且結果穩定、不用模型費用，那為什麼這次選 e2e 呢？關鍵在 iPhone 實機。Flutter 的 release 模式不能跑在 iOS 模擬器上，要測真正上架的正式包就一定要用實機，而 Maestro 目前還[不支援 iOS 實機](https://github.com/mobile-dev-inc/maestro/issues/686)。如果大家的專案只需要驗證 Android 的正式包，Maestro 很可能比 e2e 更適合，這次我沒有實測它，所以後面的數字不包含 Maestro

另外還有 Google 的 [artemis](https://github.com/google/artemis)，以及不靠框架、直接讓 LLM 操作手機的做法。artemis 目前只支援 Android，這兩種做法跑完也不會留下可以重複執行、放進 PR 審查的測試檔，所以這次沒有放進來。

## 先跟大家分享結果

整理下來是這樣：

- Patrol → 4/4，測試本身每支 5 到 7 秒，整輪算下來每支約 26 秒，測試裡可以直接檢查 app 的資料
- e2e 加 LLM → 改版動到的退貨流程，兩輪裡有一輪自己跑完，但每支要 50 到 70 秒，還出現一次假通過
- e2e 加 Jev → 第一輪 36 支測試全部停在第一步，因為 Flutter 的文字欄位在 iOS 上被讀成 `Other`，Jev 沒有可以打字的選項。11 月用新版 e2e 重跑，文字欄位已經修好，但 Jev 還是卡在沒有名字的訂單列；我在 app 裡把可以點的列表項目標成按鈕之後，退貨流程連續三次都自己跑完
- marionette 加 Jev → 同一台模擬器重跑上一篇的六個任務各三次，18/18，每次約 8 秒
- Patrol 改版後紅燈 → 讓 Jev 透過 marionette 重跑一次，找到 3 個改名後的 key，人看過、套用後 6 秒轉綠

最後的分工是腳本把關、AI 在旁邊幫忙：Patrol 負責擋 merge 和上架，marionette 讓 AI agent 在開發中自己驗證、在 Patrol 壞掉時提出修法，e2e 負責探索和正式包的冒煙測試。另外最讓我意外的是，同一個 AI 模型在同一台模擬器上，從 Dart 層讀取是 18/18，換到 OS 層第一輪卻一步都走不動，但同樣在 OS 層，會自己決定打字的 LLM 是 10/12。後來模型沒換，只是 app 多回報了按鈕的角色，Jev 就跑完了退貨流程。所以選工具時要先看它掛在 app 的哪一層，像 Jev 這種只會從選項裡挑的模型，能不能幫上忙就是由這一層、以及 app 回報給這一層的資訊決定的。

## 先看三個工具掛在哪一層

Flutter 跟原生 app 很不一樣的地方，是畫面上每個像素都由 Flutter 自己畫，iOS 和 Android 系統看不到 widget，只看得到 Flutter 額外回報給它的 **Semantics** 節點，也就是給無障礙功能使用的那一份資訊。所以 Flutter 的 E2E 工具大致可以分成兩種：

- 掛在 Dart 行程裡 → integration_test、Patrol、marionette，看得到 widget 的型別和 Key，也可以直接讀 app 的狀態，但碰不到 Flutter 畫布以外的東西，例如系統的權限彈窗
- 掛在 OS 的無障礙層 → Maestro、e2e，看得到系統彈窗，但只能從 Semantics 節點認識 Flutter 的畫面，看不到 Key

Patrol 比較特別，兩邊都有。它的測試程式跑在 app 行程裡，原生的 runner 再透過 localhost 跟它溝通，所以同一支測試可以先用 Key 點 Flutter 的按鈕，接著去按系統權限彈窗上的「允許」。

下面這張圖一列是一層，把每一層看得到的東西、從這層讀取的工具，以及同一個 AI 模型在這層的結果放在一起：

![工具從哪一層讀取 app，決定 AI 拿得到哪些選項：e2e 讀 OS 無障礙層，只看得到 Flutter 回報的 Semantics 和系統彈窗，加 Jev 第一輪 0/36，app 補上按鈕角色後 3/12；marionette 讀 Dart 行程，看得到 widget 型別、Key 和 store，加 Jev 18/18；Patrol 兩層都有，是腳本，4/4](https://img.yiichenhi.com/7fe6767133a5a0d0/1400.webp)

上一篇的 Jev 是透過 marionette 接上去的，它拿到的選項是 `FilledButton key=signin_button` 這種從 widget tree 整理出來的資訊。這次 e2e 是從 OS 層看同一個 app，後面會看到這個差別比我預期的大很多。

## 實驗怎麼做

用的是上一篇同一個 demo app Boxtide，一共十三個畫面，一樣跑四條流程：退貨、加入購物車、聯絡客服、新增地址。這次全部在 iPhone 17e 模擬器（iOS 26.5）上執行，Patrol 用 4.10，e2e 用 0.19.0。e2e 加 Jev 那一組在 11 月用 e2e 0.23.0 重跑過一次，環境不同，後面會另外說明。

沒看過上一篇的朋友，可以先看一下 Boxtide 長什麼樣子。四條流程都從登入開始，登入之後各自要去的畫面是這四個：

![Boxtide 的四個畫面：訂單頁（退貨從這裡點開訂單 #5207）、Shop（Pocket speaker 在畫面外）、Support（Contact us 在 FAQ 下面的畫面外）、新增地址的表單](https://img.yiichenhi.com/edc5af599589f3bc/1400.webp)

判定方式也沿用上一篇，不看測試框架或 agent 回報的結果，直接讀 app 的 store。Patrol 的測試本身就跑在 app 裡，可以直接檢查；e2e 是從外面操作 app，所以每支測試結束時，我另外透過 Dart 的 VM service 讀一次 app 的狀態記錄下來，事後再跟 e2e 的判斷對照。

UI 改版的部分也是用上一篇的開關，輸入一個數字（seed），app 會產生一組固定的改動，把一部分 widget key 改名、換掉幾個按鈕文案。差別在於這兩個框架都會自己啟動 app，沒有機會在啟動之後再打開開關，所以這次改成在 build 時用 `--dart-define=CHAOS_SEED=4` 編進去：

```dart
// 自己啟動 app 的工具（e2e、Patrol）沒辦法在第一個畫面之前呼叫 extension，
// 所以改動也可以在 build 時編進去
const seed = int.fromEnvironment('CHAOS_SEED');
if (seed != 0) Store.instance.setChaos(seed);
```

## Patrol：最快，也最直接

Patrol 的測試寫起來跟 Flutter 的 widget test 很像，用 `$(#nav_orders)` 這樣的寫法依照 Key 找到元件。下面是退貨流程，最後一行直接檢查 store 裡訂單的狀態，不需要從畫面去猜：

```dart
patrolTest('return-flow', ($) async {
  await _signIn($);
  await $(#nav_orders).tap();
  await $(#order_5207).tap();
  await $(#start_return_button).tap();
  await $(#return_next_button).tap();
  await $(#return_next_button).tap();
  await $(#return_confirm).tap();
  await $(#return_next_button).tap();
  // 測試跑在 app 裡，直接問 store 這張訂單是不是進入退貨了
  expect(Store.instance.orderById('5207').status, OrderStatus.returning);
});
```

對照畫面來看，腳本裡每一行點的，就是下面框起來的元件：

![退貨流程六個畫面：訂單頁點 Orders 分頁和訂單 5207、訂單詳情點 Start a return、退貨三步各按 Continue、最後勾選確認後送出，出現 Return started](https://img.yiichenhi.com/835b589387ef155e/1400.webp)

正常版四條流程全部通過，測試本身每支 5 到 7 秒。整輪含 build 是 2 分 52 秒，build 佔 51 秒，跑測試的 103 秒裡，測試本身加起來只有 22 秒，其他是啟動和收尾，所以實際上每支大約要 26 秒。第一次跑其實是 3/4，加入購物車那條失敗了，因為商品在畫面外，要先用 `scrollTo()` 捲過去才點得到。這跟上一篇提到的一樣，腳本快的前提是腳本本身是正確的。

改版後（seed 4）是 3/4，退貨流程一開始就找不到 `nav_orders`。另外三條會通過，是因為 demo app 只會改到退貨流程用的 key，其他流程的 key 不會被改名，所以這不代表有三條腳本撐過了改版。上一篇手寫腳本 0/12 那一組，失敗的也都是退貨流程。

導入成本主要在 iOS。除了加 dev dependency，還要新增一個 `RunnerUITests` target、加兩個 build phase、在 Podfile 裡加巢狀 target，再關掉平行執行和 script sandbox。我照官方範例把這些寫成一支 `xcodeproj` 腳本（`demo_app/ios/add_patrol_target.rb`），全程沒有開 Xcode。如果專案已經有很多 target 或自訂的 build 設定，這部分建議預留一些時間。

## e2e 加 LLM：改版後有機會自己跑完，但慢，也會假通過

e2e 的測試用 TypeScript 撰寫，我把每條流程寫成一句話的目標交給 agent，後面接一個 agent 沒辦法自己說服的檢查：

```ts
test('support-flow', async ({ app, agent, screen }) => {
  await app.open();
  await agent.act('Sign in with email {email} and password {password}', { params: signIn });
  // Flutter 的分頁在 iOS 上叫做 "Orders\nTab 2 of 5"，所以用 pattern
  await expect(screen.getByRole('button', /^Orders/)).toBeVisible();
  await agent.act('Contact support about order {order} with the message {message}', {
    params: { order: '5213', message: 'My parcel has not moved in four days.' },
  });
  // 從外面只能檢查畫面上看得到的東西
  await expect(screen.getByText('Message sent').first()).toBeVisible();
});
```

agent 使用 `gemini-3.1-flash-lite`，跟上一篇負責寫字的是同一個模型。我把 Patrol 的兩輪也放進來對照，時間和成本都換算成每支測試，每個點代表一支測試，實心是 app 真的完成，紅色是假通過：

![Patrol 正常版 4/4，每支 26 秒；改版後退貨流程紅燈。e2e 加 LLM 正常版 10/12，每支 62–68 秒，假通過 1 次；改版後不用快取 6/8；兩種重播在改版後都只有一半](https://img.yiichenhi.com/26cae78777a22d43/1400.webp)

先看好的部分。agent 看的是當下的畫面，UI 改了名字它一樣找得到。這次改版除了登入按鈕的文字，真正動到的只有退貨流程。登入按鈕從「Sign in」變成「Log in」，改版後的 16 支測試都照樣登入成功；退貨流程不用快取的兩輪裡，有一輪自己跑完了，同一條 Patrol 是直接紅燈，這是手寫腳本做不到的。不過只有兩輪，另一輪沒有跑完，用錄製重播的兩輪也都失敗，所以我會把它看成有機會撐過改版，還不到可以依賴的程度。

接著是要注意的部分，我分成三點來說明。

第一是速度。每支 62 到 68 秒，用同樣整輪除以支數的算法，Patrol 是每支約 26 秒，大約差了 2.5 倍；只看測試本身的話，Patrol 是 5 到 7 秒，差距會再拉大。重播的設計本來是要解決這個問題，實際上模型呼叫從 48 次降到 17 到 23 次，時間卻只從 62–68 秒降到 49–50 秒。我看了每一步的紀錄，任務本身的部分全部重播成功，失敗的都是登入：重播往 Flutter 的密碼欄位打字時，XCTest 回報失敗、runner 的 session 失效，只好交還給 agent 重新做一次。改版後的兩種重播都是 2/4，比直接讓 agent 跑還差，這部分的原因我還沒有拆開分析。

第二是假通過。有一次客服單確實送出了，但訂單欄位是空的，測試卻判定通過，因為它只檢查了「Message sent」這個標題。e2e 從外面看 app，能檢查的只有畫面上的文字，欄位裡實際存了什麼它看不到。如果我沒有另外讀 store，這一次就會被當成成功。同一條流程在 Patrol 裡是直接檢查 store 裡有沒有訂單 5213 的客服單，這種情況會直接紅燈。

第三是畫面定位。之前讀 e2e 原始碼時，我推論 Flutter 的畫面標題它讀不到，因為它只認 iOS 的 UINavigationBar，Flutter 的 AppBar 不是。實測確認了這一點，所有步驟記錄的畫面位置都只有 bundle id `dev.yii.boxtide`。不過重播主要靠控制項比對，任務的部分照樣重播成功，影響比我預期小。

## e2e 加 Jev：同一個模型，要等 app 補上資訊才走得動

e2e 有一個 decision executor，可以把 Jev 接成負責做決定的模型，再搭配一個 LLM 負責寫字，概念跟上一篇「讓 Jev 挑，讓 LLM 寫」很像，設定也只有幾行：

```ts
jev: {
  executor: decisionExecutor({
    model: typeSafeAi.decisionModel('jev-latest'),
    textModel: lite, // 同一個 flash-lite，只負責寫字
  }),
},
```

### 第一輪：36 支測試全部停在第一步

我原本最期待這一組，結果 9 輪、36 支測試全部在第一步停下，錯誤訊息都是 `The decision model cannot make progress`。

追下去之後發現問題不在 Jev。decision executor 會依照元件的角色決定可以做哪些操作，文字框可以打字、按鈕可以點擊，但 Flutter 的文字欄位在 iOS 上，XCTest 看到的類型一律是 `Other`。為了確認不是我的寫法問題，我另外寫了一個小 app 對照六種寫法：沒有包 Semantics、加上 `Semantics(identifier:)`、再加 `container`、再加 `textField: true`，以及密碼欄位有包和沒包，結果六種全部都是 `Other`，底層是 Flutter 的 `TextInputSemanticsObject`。`Other` 上面不提供打字，所以 Jev 連登入都做不到。

接著我試了幾種繞法：

- 用 locator 的 `fill` 可以填入 Email，但密碼欄位第一次填會讓 XCTest 的 runner session 失效，第二次才成功
- 改用 `pressSequentially` 會直接被拒絕，理由是它只能用在可編輯的欄位上
- 最後把登入寫死成 locator，只讓 Jev 負責不需要打字的退貨和購物車流程，它點對了 Orders 分頁，卻停在訂單列表

停在訂單列表的原因也是同一件事。每一張訂單在無障礙樹裡是一個沒有名字的 `other`，只帶著 `testid="order_5213"`，訂單的文字在旁邊另一個節點，所以 Jev 拿到的選項裡，沒有一個看得出是哪張訂單的點擊目標。

把兩邊放在一起看就很清楚了。上一篇同一個 Jev 透過 marionette 是 17/18，但那次是在 macOS 桌面版上跑的，所以我在同一台 iOS 模擬器上，用上一篇的 runner 透過 marionette 重跑了同樣六個任務各三次，一樣是 Jev 挑、flash-lite 寫，結果是 18/18，拿到的是有型別、有 Key 的選項；第一輪透過 XCTest，拿到的卻是一排 `Other`。模型一樣，差別在它拿到的選項。

LLM 那一組第一輪是 10/12，能過是因為它可以自己決定對哪個節點打字，不受角色限制，第一次打字讓 session 失效之後，它看到畫面變了也會自己再打一次。

### 用新版 e2e 重跑一次

寫完第一輪之後 e2e 更新到了 0.23.0，所以 11 月我重跑了 e2e 加 Jev 這一組。原本的 iOS 26.5 模擬器已經隨 Xcode 更新被移除，這次是在 iOS 27.2 的模擬器上跑，所以這一輪的數字只跟同一個環境裡的結果比較。

先說好消息，文字欄位的問題已經修好了。在同一台模擬器上，e2e 0.19 讀到的 Email 欄位還是 `other`，換成 0.23 就變成 `textbox`，所以這部分是 e2e 那邊修好的，Jev 終於有可以打字的選項。

不過結果還是 0/4，這次卡在兩個地方：

- 密碼欄位 → 第一次打字一定失敗，錯誤是 `No focused text input`，用 locator 填也一樣要第二次才成功。LLM 失敗了會自己再打一次，Jev 不會，所以停在登入
- 訂單列表 → 我把登入寫死成 locator，讓 Jev 只負責後面的流程。它很有把握地點了 Orders 分頁（機率 0.97），接著就停下來了，因為訂單在無障礙樹裡還是沒有名字的 `other`，它找不到可以點的目標

我也把 `vision` 打開試了一次。打開之後 Jev 多了看截圖、用座標點擊的選項，但它一次都沒有選，結果一樣是 0/4。

### 改 app 這一邊

既然卡住的是 app 回報給 iOS 的資訊，我就回到 Flutter 這邊改。[e2e 的文件](https://e2e.com/docs/mobile)建議 Flutter 用 `MergeSemantics` 把節點合在一起，讓 id、文字和角色落在同一個節點上。另外我發現 `InkWell` 只提供點擊的動作，不會回報按鈕的角色，所以在 iOS 上，可以點的列表項目看起來就是一段文字。兩個改動都只有幾行：

```dart
Widget identified(String id, Widget child) {
  // 合併之後，id、文字和角色會落在同一個節點上
  return MergeSemantics(
    child: Semantics(identifier: id, container: true, child: child),
  );
}

// InkWell 只有點擊動作，沒有按鈕角色，可以點的列表項目要另外標成按鈕
return onTap != null ? Semantics(button: true, child: card) : card;
```

我把兩個改動分開測，Jev 的設定和測試都沒有動：

- 只加 `MergeSemantics` → 按鈕都有了名字和 id，訂單列也變成帶 id 的文字，但它還不是按鈕，Jev 一樣 0/4
- 再把可以點的列表項目標成按鈕 → 退貨流程連續三次都自己跑完，store 也確認訂單 5207 進入退貨。Jev 負責的部分每次 11.6 到 11.8 秒、16 次模型呼叫，整支測試含登入約 30 秒，一輪四支的模型費用是 $0.0024 到 $0.0027

把三種 build 放在一起看會更清楚，畫面完全一樣，差別只在 iOS 拿到的那個節點：

![訂單頁截圖，框出訂單 #5207 那一列。原樣時 e2e 讀到沒有名字的 other，加 MergeSemantics 後是 text，Jev 都停住；標成按鈕後是 button，退貨流程連續 3 輪跑完](https://img.yiichenhi.com/fbd5f39e95884b45/1400.webp)

剩下三條還沒過，原因也都看得出來：

- 加入購物車 → 商品卡是另一個 widget，這次沒有標成按鈕，Jev 進到 Shop 分頁後找不到可以點的商品（三次裡有一次是登入後的檢查就沒過）
- 聯絡客服 → 點了 Support 分頁之後，「Contact us」按鈕回報的位置是空的（`no usable bounds`），連續兩次都點不到
- 新增地址 → 兩個欄位都填好、也按了儲存，畫面卻還停在表單上，接著連續三次想收起鍵盤都失敗

所以這一輪 e2e 加 Jev 是四條過一條，還不到可以拿來用的程度。不過這個過程剛好說明了這篇想講的事，Jev 的設定和測試從頭到尾都沒有改，我只改了 app 回報給 iOS 的資訊，它就從停在訂單列表，變成可以把退貨流程跑完。

另外要說明兩件事。第一，同一個環境裡 LLM 那一組也只有 1/4，登入寫死之後是 2/4，比第一輪的 10/12 低很多。舊的模擬器已經不在了，我沒辦法分辨是 e2e 新版、iOS 27.2 還是模擬器機型造成的，所以兩輪的數字不要直接拿來比。第二，這些結果目前只在 iOS 成立，Flutter 的文字欄位在 Android 上是 `EditText`，e2e 加 Jev 在 Android 上的結果可能不一樣，這次的 demo app 沒有 Android 平台，所以還沒有測。

## AI 放在哪裡：開發中的驗證，以及 Patrol 壞掉時的修復

所以 AI agent 不放進把關測試，腳本知道每一步的答案，只要它是正確的，就一定比 agent 快，也不會假通過。我把 AI 放在兩個不擋流程的地方，兩個都透過 marionette 操作 app，由 Jev 挑選每一步：

- 開發中的驗證 → coding agent 改完程式碼後，自己把流程點一遍，Jev 挑、flash-lite 寫，在 iOS 模擬器上是 18/18，一次中位數 8.3 秒、約 $0.001
- Patrol 的修復 → key 改名讓 Patrol 紅燈時，由 AI 走一次同樣的流程、找出新的 key，提出修正讓人審

第一個前面已經量過了，第二個是這次新做的。平常 Patrol 因為改名紅燈時，要有人打開 app、找到新的名字、再回去改測試。我寫了一支 `runner/repair.py` 把這件事變成一份提案，流程是這樣：

1. 在改版後的 debug build 上，讓 Jev 透過 marionette 走一次同樣的任務，要打字的地方用一張手寫的值表
2. 收集它實際操作過的 key
3. 跟腳本裡的 key 配對，產生「舊 key → 新 key」的對照，另外列出腳本裡沒有的動作
4. 人看過之後再套用到 Patrol 測試

這裡要注意，marionette 和 Patrol 不能放在同一個 build 裡。`MarionetteBinding` 跟 Patrol 的 binding 會互相衝突，一個行程只能有一個 binding，所以修復模式是跑在另一個加了 `MarionetteBinding` 的 debug build 上。

退貨流程跑出來的提案長這樣：

```json
"mapping": {
  "nav_orders": "nav_orders_v14",
  "start_return_button": "start_return_button_v14",
  "return_next_button": "return_next_button_v14"
},
"extra": ["scroll", "return_notes_field"]
```

Jev 完成了任務，store 確認訂單 5207 進入退貨，一共 14 步、20 次模型呼叫、12.5 秒、$0.00097。腳本裡被改名的三個 key，它都實際操作過，配對出來的對照也都正確。不過配對是用名稱前綴比對的，這個 demo app 改名的方式是在後面加尾碼，所以只要 Jev 操作過就一定配得上；真實專案如果整個換掉名字，就要靠人從 extra 裡對回去。

反而是套用的過程我出錯比較多。第一次我只換了 key，沒有理會 extra 裡的 `scroll`，測試照樣紅燈，因為 `order_5207` 在畫面外。加上 `scrollTo()` 之後又紅了一次，Patrol 的 `scrollTo()` 預設會捲動畫面上第一個 Scrollable，而這一頁的第一個是上方那一排篩選 chip。指定捲動訂單清單之後，6 秒轉綠：

```dart
// 提案的 extra：Jev 在這裡捲動過。這一頁第一個 Scrollable 是篩選 chip，
// 所以要指定訂單清單
await $(#order_5207).scrollTo(view: find.byType(Scrollable).last).tap();
await $(#start_return_button_v14).tap();
```

修好的測試跑了三次才轉綠，前兩次失敗都是我套用時漏了細節，Jev 的提案本身沒有錯。所以我會把它定位成「開一個修正 PR 給人審」，不讓它自動改測試，提案裡的 extra 也值得一起看，它常常就是腳本少掉的那一步。

## 三個工具各自適合的情境

把前面的實測整理一下，三個工具適合的情境其實分得很清楚：

| 工具 | 適合的情境 | 不適合的情境 | 實測速度與成本 |
|---|---|---|---|
| Patrol | 每個 PR 和上架前的把關、需要點系統權限彈窗或通知的流程、要直接檢查 app 資料的測試 | 還沒有人寫腳本的新流程，以及 UI 常常大改、腳本一直需要修的畫面 | 測試本身每支 5 到 7 秒，整輪每支約 26 秒，不需要模型費用 |
| marionette 加 Jev | 開發中讓 coding agent 改完程式碼自己點一遍，以及 Patrol 因為改名紅燈時找出新的 key | 擋流程的 CI 關卡（只能跑 debug / profile build，LeanCode 自己也不建議），以及需要系統彈窗的流程 | 18/18，每次約 8.3 秒、$0.001 |
| e2e 加 LLM | 拿不到原始碼、只有安裝檔的 app，對正式包跑冒煙測試，以及在 Nightly 讓 agent 自由探索 | 擋 merge 的關卡（慢，而且會假通過），以及需要檢查 app 內部資料的流程 | 正常版每支 49 到 68 秒，$0.007 到 $0.023 |

三者擅長的地方幾乎沒有重疊，所以接下來我把它們放進同一套流程，各自負責不同的階段。

## 整理成一套流程

會擋住 merge 或上架的測試必須是確定性的，原因有兩個。第一個是機率，就算每條流程有 98% 的可靠度，50 條全部綠燈的機率也只有 0.98^50，大約 36%。第二個是 agent 自己回報的結果不可靠，上一篇 flash-lite 拿到錯的資料仍然回報成功，18 次裡有 6 次；這次 e2e 也出現了一次假通過。所以把關交給 Patrol，判定看 app 實際存了什麼，agent 放在旁邊幫忙。

依照開發的不同階段，我會這樣安排，上面一排是會擋流程的 Patrol，下面一排是不擋流程的 AI 輔助：

![腳本把關，AI 在旁邊幫忙：擋流程的都是 Patrol，開發中寫成測試、每個 PR 跑 Android 模擬器、Nightly 跑 iOS 模擬器加實機、上架前在 RC 上重跑全套；不擋流程的是 marionette 加 AI 驗證、AI 修復開修正 PR、e2e 探索、e2e 對正式包冒煙](https://img.yiichenhi.com/6cffad7c5fc3828f/1400.webp)

這裡有兩個名詞簡單說明一下：

- Nightly → 讓 CI 每天晚上排程跑一次，跟每個 PR 的檢查分開，適合放比較慢、比較貴的測試，例如 iOS build 和實機
- RC（Release Candidate）→ 準備拿去上架的那個版本，切出來之後只修 bug，測試通過就把同一份送上商店

上架前之所以要兩道檢查，是因為兩者看的東西不一樣。Patrol 在 RC 上重跑，確認功能是對的；但它跑的是自己打包、帶著測試程式的 build，有些問題只會出現在真正要上傳的那一包，例如 R8 / ProGuard 混淆、`--obfuscate`、正式環境的 `--dart-define`、簽章和 entitlement。e2e 從外面操作真正的正式包，剛好可以補上這一塊。

這套分工還需要一個共用的地基：所有 key 放在 app 和測試共用的同一個檔案，關鍵元件的 `Semantics(identifier:)` 也設成同一個值。Patrol 和 marionette 讀 Key，e2e 讀 identifier，兩邊用同一個名字，改名時也只需要改一個地方。如果打算讓 e2e 這類從 OS 層操作的工具接 AI，再加兩件事：外面包一層 `MergeSemantics`，可以點的列表項目加上 `Semantics(button: true)`。Flutter 的文件也提到，標成按鈕之後 VoiceOver 會提示使用者這是一個按鈕，所以這兩個改動對無障礙本身也有幫助。

## 導入前要注意的地方

最後整理幾個這次踩到、導入前值得先知道的地方：

- marionette 只能跑 debug 和 profile build，而且 `MarionetteBinding` 會跟 Patrol、integration_test 的 binding 衝突，專案如果已經用了 Sentry 自己的 binding 也一樣，建議準備一個只給開發用的進入點
- Patrol 在 iOS 上的設定步驟比較多，建議寫成腳本，之後新增 target 或升級時比較好重做
- e2e 加 Jev 在 Flutter iOS 上還不適合直接用。新版 e2e 已經讀得到文字欄位，但密碼欄位第一次打字會失敗，Jev 不會重試，可以點的列表項目也要在 app 裡補上按鈕角色，它才看得到；補上之後四條流程過了一條。e2e 加 LLM 可以用，但要自己另外確認 app 的資料，不能只看畫面
- e2e 的文件提到，打開 `vision` 之後，decision executor 可以對樹裡沒有列出的控制項用截圖定位點擊。重跑時我打開試過，Jev 一次都沒有選擇用截圖點擊，結果跟關掉時一樣，所以目前不能靠它補 Flutter 回報不足的部分
- 修復模式目前只在 seed 4 的退貨流程跑過一次，用的是 Jev 加手寫值表。上一篇同樣的設定，在改到 email 欄位的 seed 7、91 都是 0/3，因為值表用舊的 key 查不到值；讓 flash-lite 負責寫字的組合在這兩個 seed 是 3/3，正式用之前建議先換成這個組合再試
- 這次 e2e 跑的都是 debug build，對正式包的冒煙測試還沒有實測。正式包也沒有 VM service，沒辦法像這次一樣讀 store 判定，只能檢查畫面，所以更要注意假通過
- 這次的範圍是一個 app、iOS 模擬器、每種跑法二到三次，其中 marionette 那組是後來補跑的，模擬器已經隨 Xcode 更新到 iOS 27.0，e2e 加 Jev 的重跑則是 iOS 27.2、每種改法一到三次；沒有 Android，也還沒有在真實產品上跑過，如果要拿這些數字說服團隊，建議先在自己的 app 上跑一輪

## 總結

這次把同一個 app、同樣四條流程交給三個工具，最清楚的一件事是工具掛在哪一層，決定了它看得到什麼、能不能直接檢查 app 的資料，也決定了 AI 拿得到哪些選項，像 Jev 這種只會從選項裡挑的模型最受影響。e2e 加 Jev 的重跑也看得到這一點，模型沒換，app 多回報了按鈕的角色，它就從停在訂單列表變成能跑完退貨流程。要讓 Flutter 的測試更完整，我的做法是腳本把關、AI 在旁邊幫忙：Patrol 負責擋 merge 和上架，AI 透過 marionette 在開發中自己驗證、在 Patrol 壞掉時提出修法，e2e 則負責探索和正式包的冒煙測試。

程式碼都放在 [flutter-jev](https://github.com/chyiiiiiiiiiiii/flutter-jev)，Patrol 測試在 `demo_app/patrol_test/`，e2e 專案在 `e2e/`，修復模式是 `runner/repair.py`，完整數字在 `results/REPORT.md` 的專案 H。

我下一步會先把商品卡和客服頁面也補上按鈕角色，看剩下三條流程能不能跑完，再到 Android 上跑一輪，Flutter 的文字欄位在 Android 是 `EditText`，e2e 加 Jev 很可能會有不同的結果，接著把 AI 驗證和修復整理成兩個指令，讓它可以直接放進 CI。有在用 Patrol 或 e2e 的朋友，也很歡迎留言分享你們的做法。

## 參考與相關資源

- [你的 widget tree 已經是一份選項清單：Jev 在 Flutter 專案裡的位置（上一篇）](https://yiichenhi.substack.com/p/widget-tree-jev-flutter)
- [flutter-jev（本文程式碼）](https://github.com/chyiiiiiiiiiiii/flutter-jev)
- [Patrol](https://patrol.leancode.co/)
- [marionette_mcp](https://github.com/leancodepl/marionette_mcp)
- [e2e（TesterArmy）](https://e2e.com/)
- [e2e 文件：Mobile（Flutter 的 MergeSemantics 建議）](https://e2e.com/docs/mobile)
- [e2e 原始碼](https://github.com/tester-army/e2e)
- [TypeSafe：Introducing System One models and Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev)
