【2026 最新】TesterArmy e2e 教學：何時加 Agent 步驟？Playwright、快取與驗收

你把購物網站的結帳流程寫成自動測試：昨天按鈕叫「前往付款」，今天改成「確認訂單」，測試就紅了。改用 AI Agent 幫忙找路，是否又會讓真正的錯誤悄悄通過？TesterArmy e2e 教學要解的正是這個取捨。

這篇寫給第一次接觸端對端測試、但願意照著範例改幾行程式的讀者。我們用同一個「選商品 → 加入購物車 → 核對數量」流程，示範如何保留 Playwright 的確定性檢查，只把容易變動的一小段交給 Agent，並觀察首次執行、快取重播和介面改版後的訊號。這是依截至 2026 年 10 月 6 日的官方快速上手與快取文件設計的可重做方法；本文不宣稱 AlphaLab 已取得三輪跑次的效能結果。

先說結論：TesterArmy e2e 教學何時該加 Agent？

一句話記住：穩定步驟交給 locator，會變的找路步驟交給 Agent，最後仍用明確斷言驗收。把 Agent 當成會自己找貨架的店員，locator 當成收銀台的條碼掃描；店員可以換路走，但結帳數量必須掃得出來。TesterArmy e2e 的核心是把兩者寫在同一支測試裡。它的 agent.act() 負責完成目標，後續的 expect(...) 負責說清楚究竟驗過什麼。

如果網站有穩定的可存取名稱、data-testid 或清楚的表單標籤，先用 locator。只有當流程需要理解頁面意思、下一個按鈕位置常變，而且有獨立可檢查的結果時，再試一個 Agent 步驟。快取節省的是重複找路的模型呼叫，通過快取不等於驗收完成；斷言仍要檢查結果。

TesterArmy e2e 與 Playwright：先看懂三個零件

端對端測試就是讓程式像使用者一樣從入口走到結果。Playwright 官方建議優先使用角色、名稱、標籤與明確的測試 ID 找元素；這些 locator 會在動作時重新找節點，適合可說清楚「要按哪一個」的場景。TesterArmy e2e 的網頁引擎建在 Playwright 上，讓確定性 locator、斷言與 Agent 步驟共存於一套測試 API。

• ① locator＝指定窗口：screen.getByRole('button', '加入購物車') 指向已知控制項。若頁面有兩個同名按鈕，就要縮小範圍或改用明確標籤。
• ② Agent＝描述任務：agent.act('把指定商品加入購物車') 讓模型觀察畫面並選路。這會產生模型呼叫與等待。
• ③ 斷言＝驗收收據：expect(screen.getByRole('status')).toContainText('1 件') 檢查可見結果。若 Agent 找到的是錯的商品，還要再核對商品名稱與總額，不能只看數量。

這也是本文的判斷式：好測試＝可重做的操作＋能抓錯的結果檢查＋可追查的失敗紀錄。只把整段流程寫成自然語言，卻沒有結果斷言，就像請店員說「我買好了」而不看收據。想補 Agent 的執行循環，可先讀Agent Harness 是什麼；想做產品層的回歸驗收，再讀AI Evals 入門。

同一流程先寫確定性基線，再加一個 Agent 步驟

先準備一個你能控制的測試站：固定商品「藍色筆記本」、固定購物車初始為空，加入後畫面顯示「1 件」和商品名稱。請用測試環境與假資料，並讓每輪從相同狀態開始。這個頁面是教學規格，不是本文聲稱已上線的範例站。

第一輪：只用 Playwright。在現有 Playwright 專案，依官方測試寫法把入口、點擊與結果分開。下面的路徑與文字要改成你自己測試站的實際名稱：

import { test, expect } from '@playwright/test';
test('購物車基線', async ({ page }) => {
  await page.goto('http://localhost:3000/shop');
  await page.getByRole('button', { name: '加入購物車' }).click();
  await expect(page.getByRole('status')).toContainText('1 件');
  await expect(page.getByText('藍色筆記本')).toBeVisible();
});

第二輪：把「找商品並加入」換成一個 Agent 步驟。先在專案執行 npx e2e init，按精靈選 Web 引擎與你已可使用的模型供應商，設定測試站 URL。官方快速上手說明精靈會產生設定與範例。以下採用官方 e2e 的測試匯入形式；依精靈實際產生的設定調整，不要把 Playwright 的 page API 原封不動貼進 e2e 測試：

import { test } from '@e2e-dev/web';
import { expect } from 'e2e';
test('購物車混合流程', async ({ app, agent, screen }) => {
  await app.open('/shop');
  await agent.act('找到藍色筆記本，把一件加入購物車');
  await expect(screen.getByRole('status')).toContainText('1 件');
  await expect(screen.getByText('藍色筆記本')).toBeVisible();
});

這段示範故意把 Agent 的任務縮小，讓「買對商品」與「數量正確」仍由確定性斷言負責。若商品卡有穩定測試 ID，連找商品都可繼續用 locator；Agent 並非越多越好。範例略去測試站啟動、模型供應商設定與失敗清理，實際專案依官方設定文件完成，並確保重跑前購物車歸零。

TesterArmy e2e 教學：快取三種狀態怎麼驗？

官方重播快取說明指出，agent.act() 後面若有成功的結果檢查，動作才有機會被記錄；下次可按角色、名稱、測試 ID 與周邊脈絡重播。摘要的 replayed／handed off／missed 對應步驟 cache.mode 的 self-finalized／agent-concluded／missed。agent.assert()、agent.waitFor() 和 agent.extract() 仍會即時執行。因此要比較模型呼叫，先固定你比較的是哪一種步驟，別把整支測試的零呼叫當成必然。

• 首次執行：清空專屬快取，跑混合測試，保存 .e2e/report.json、執行摘要與測試站版本。記下通過與否、總耗時、modelCalls、step.cache.mode 和可見結果。
• 相同介面重播：保留快取與相同初始資料，再跑一次。看報告是否標為 replayed，再看斷言是否依舊檢查「藍色筆記本」與「1 件」。若是 missed，先查測試名稱、指令、參數、引擎版本與快取目錄。
• 介面改版：只改商品卡的導覽或按鈕名稱，保留商品與正確結果。再跑一次，觀察是 replayed、handed off 還是 missed；用 npx e2e run --no-cache 另外跑一輪，隔離快取因素。若要讓過期錄製在 CI 明確失敗，參考官方 --strict-cache 說明。

把紀錄排成同一張比較表：版本、初始資料、通過率、耗時、模型呼叫、快取模式、失敗原因、最後畫面。每種狀態至少重複幾次，才看得出偶發失敗；本文不提供未執行的完成率、秒數或成本。模型費用依實際供應商與用量記帳，開源框架本身的價格不能代替你的模型帳單。

快取會不會掩蓋錯誤？做兩個故障注入

故障 A：讓錯商品也能顯示「1 件」。保留一個只查數量的測試，再增加商品名稱斷言。若只查數量的版本通過、完整斷言失敗，你抓到的是「驗收條件太弱」，不是快取自行證明了流程正確。再用無快取跑次核對結果，確認問題和重播是否有關。

故障 B：把已知 locator 指向錯按鈕。建立兩個視覺相近、名稱不同的控制項，故意把測試 selector 改到另一個。執行後應看清楚是定位器找不到、點到別處，還是最後斷言擋住了錯誤。Playwright 的Trace Viewer可回看每個動作的 locator、畫面快照與錯誤；e2e 則查看自己的報告、步驟與快取原因。兩邊採同一個結果判準，才有比較意義。

2026 年 10 月 3 日一則Android issue #797回報，在 e2e 0.15.1、mobile 0.9.0 的特定模擬器環境，確定性 locator 的點擊座標落在錯誤控制項。這是回報者的單一案例，並非本文網頁流程的實測結果；它提醒我們在行動端也要保存畫面與手勢證據，不要把「locator 已找到」等同「實際點對」。

決策表：哪些步驟值得交給 Agent？

選 locator，如果：角色與名稱穩定、操作目標精確、資料可固定、這一步要在每次 CI 中快速重複。選一個 Agent 步驟，如果：介面路徑常變、目標可用自然語言清楚描述、結尾可由獨立斷言驗證，而且你接受首次執行的模型等待與費用。暫緩加入 Agent，如果：連成功畫面都說不清楚，或測試資料每輪不同到無法比對；先補驗收條件與資料重置。

若你要把這套測試放進 CI，先讓確定性基線穩定，再挑一段高維護成本的路徑做小規模試驗。快取模式與模型呼叫放進報告；失敗時保留畫面和版本。這跟Coding Agent 測試驗收的思路相同：測試通過要能指出是哪個檢查證實了結果。若想理解為何 Agent 系統需要可觀測的執行層，可接著看建立 Agent Harness。

常見問題：先給直接答案

1. TesterArmy e2e 可以取代 Playwright 嗎？

看你要替換的範圍。e2e 的網頁引擎使用 Playwright，官方也提供遷移指南；先用一支重要流程比較 API、報告和 CI 需求，再決定是否移動其餘測試。

2. 每個步驟都要呼叫模型嗎？

不用。官方 README 說純確定性測試不需要模型；就 agent.act() 而言，首次執行、快取未命中或重播交接時會產生模型呼叫。若另寫 agent.assert()，它每輪都會即時執行。

3. 快取命中就代表商品買對了嗎？

不代表。重播說明的是動作錄製可在當前介面重走；你的獨立斷言仍需核對商品、數量與重要結果。

4. 怎麼查某一步有沒有用到模型？

看執行摘要的 model calls，以及步驟結果的 modelCalls、cache.mode 與原因。把整支測試總數和個別步驟分開讀。

5. 介面改版後，快取如何處理？

官方文件描述，重播若找不到控制項或最後狀態不符，通常會把工作交回 Agent；CI 可用 --strict-cache 讓過期錄製成為明確失敗訊號。

6. 為什麼 Agent 動作後還要 expect？

因為測試需要可追查的通過條件。官方快取文件也把後續驗證列為錄製條件；只完成動作、沒有可見結果，不能建立可信的回歸檢查。

7. 網頁流程和 Android issue 是同一個問題嗎？

不是同一個測試環境。issue #797 描述特定 Android 模擬器與套件版本的點擊座標，這篇的示範是網頁購物車；只能把它當作設計故障注入的警訊。

8. 新手第一步該做什麼？

先做一個可重置的假站流程，寫好兩個結果斷言，跑通 Playwright 基線。接著只替換一個找路步驟，記錄三種狀態的報告，再決定是否擴大。

給新手的三個重點

• 先定義「什麼結果才算對」，再決定用 locator 或 Agent。
• 把快取的 replayed、handed off、missed 與模型呼叫寫進同一份跑次紀錄。
• 用錯商品、錯控制項做故障注入；能抓出錯誤的測試，才值得放進 CI。