沒有桌面環境，也能讓 AI agent 開啟網站、點擊、輸入、檢查結果並留下截圖。本文以 Playwright CLI 為瀏覽器操作工具，示範在 Linux 終端機中搭配 Antigravity CLI（AGY）、Claude Code 或 Codex，驗證 agent 剛完成的 Angular 網站功能。
本文假設三種 agent 已安裝並完成登入，Angular 專案也已存在。重點是安裝 Playwright CLI、讓 agent 讀到操作說明，以及在開發完成後要求它依原需求驗證實際頁面。
1. Playwright CLI 是什麼？
Playwright CLI 是為 coding agent 設計的瀏覽器命令列工具。Agent 在終端機執行 playwright-cli 指令，就能開啟網頁、取得頁面快照、操作元素和截圖。瀏覽器預設以 headless 模式執行，所以 Linux 主機不需要桌面或 DISPLAY 才能跑本文的範例。
它的基本工作方式是：
open開啟網站，CLI 回傳目前頁面資訊。snapshot提供頁面元素及其參照編號（例如e8）。- Agent 根據當下的快照，用
fill、click、check等指令操作；操作後再讀取頁面狀態。 screenshot保存畫面，最後由 agent 對照預期結果回報通過或失敗。
CLI 是實際操作瀏覽器的程式；skill 是教 agent 使用這些指令的本地說明文件。本文做的是即時操作與結果回報。若需要提交到版本庫、日後一鍵重跑的自動化測試，則還要另外撰寫 Playwright Test 測試檔。
本文使用
playwright-cli。它與npx playwright test（執行 Playwright Test 測試檔）是不同用途的命令。
2. 在 Linux 安裝 CLI，並提供給 AGY、Claude Code、Codex
以下命令都在 Linux 終端機 執行。先準備 Node.js 20 以上、npm，以及可執行 shell 命令的 AGY、Claude Code 或 Codex。確認版本：
node --version
npm --version
安裝 Playwright CLI 與瀏覽器。--with-deps 會一併安裝 Linux 所需的系統套件；系統套件安裝可能需要管理員權限。
npm install -g @playwright/cli@latest
playwright-cli --help
playwright-cli install-browser --with-deps
接著選擇 專案安裝 或 全域安裝 skill。CLI 程式已由前面的 npm install -g 裝到全域；以下選擇的是 skill 的適用範圍。
安裝到單一專案
切換到要測試的專案目錄，安裝對應的 skill。playwright-cli install 系列指令會初始化此工作目錄：建立 .playwright/，並把 .playwright-cli/ 加入 .gitignore。之後的快照、console 紀錄等輸出都會存在 .playwright-cli/，可能含有登入資訊，不要提交到版本庫。下列 skill 會放在專案內，而不是安裝 agent 本身。
| 使用的 agent | 在專案目錄執行 | skill 位置 |
|---|---|---|
| AGY（Antigravity CLI） | playwright-cli install --skills=agents |
.agents/skills/playwright-cli/ |
| Claude Code | playwright-cli install --skills=claude |
.claude/skills/playwright-cli/ |
| Codex | playwright-cli install --skills=agents |
.agents/skills/playwright-cli/ |
例如三種 agent 都要在同一個專案使用，只需各執行一次這兩條命令：
cd /path/to/your-project
playwright-cli install --skills=agents
playwright-cli install --skills=claude
安裝到目前使用者的所有專案
-g 會把 skill 裝進使用者家目錄，且不會初始化目前的專案。Claude Code 與 Codex 各執行一次：
playwright-cli install --skills=claude -g # ~/.claude/skills/playwright-cli/
playwright-cli install --skills=agents -g # ~/.agents/skills/playwright-cli/
Codex 會讀取 ~/.agents/skills。AGY CLI 的全域 skill 路徑不同：它讀取 ~/.gemini/antigravity-cli/skills，因此把已安裝的完整 skill 資料夾複製過去：
mkdir -p "$HOME/.gemini/antigravity-cli/skills"
cp -a "$HOME/.agents/skills/playwright-cli" "$HOME/.gemini/antigravity-cli/skills/"
此時三種 agent 都能在目前 Linux 使用者的其他專案使用 skill。若只用 AGY CLI，仍可先執行 playwright-cli install --skills=agents -g 作為複製來源。更新 Playwright CLI 或重新安裝 skill 後，也要重新複製到 AGY CLI 的目錄。上述 AGY 路徑依 Antigravity 官方 skill 文件；Codex 的全域讀取位置依 OpenAI Docs。
安裝後，從要測試的專案目錄啟動或重新啟動 agent，讓它載入新 skill：AGY 用 agy、Claude Code 用 claude、Codex 用 codex。AGY 可在互動介面輸入 /skills，確認 playwright-cli 出現在清單中。即使 agent 沒有讀到 skill，也可在 prompt 中要求它先執行 playwright-cli --help 取得指令用法。Playwright 安裝文件也提供這種用法。
先做一個不依賴桌面環境的基本檢查：
playwright-cli open https://demo.playwright.dev/todomvc/
playwright-cli snapshot
playwright-cli close
open 應回傳 TodoMVC 的網址、標題與快照檔路徑。snapshot 則印出頁面元素清單，每個元素附有 e8 這類編號，例如（節錄）：
- generic [ref=e6]:
- heading "todos" [level=1] [ref=e7]
- textbox "What needs to be done?" [active] [ref=e8]
縮排代表元素的層級，textbox ... [ref=e8] 就是頁面上的輸入框。後續指令用這個編號指定操作對象，例如 playwright-cli fill e8 "買牛奶"。編號會隨頁面狀態改變，每次操作前應重新取得快照。
檢查完用 close 結束瀏覽器。如果啟動失敗，先檢查 node --version 與 playwright-cli --help，再重新執行 playwright-cli install-browser --with-deps。Linux 發行版與容器映像仍須符合 Playwright 的系統需求。
3. Angular 開發完成後，怎麼要求 agent 驗證？
最實用的時機是 同一個 agent 剛完成 Angular 功能、仍看得到原始需求與開發過程時。這時不必重新敘述整個功能；要求它從原需求和本次修改整理驗收項目，再到真正運行的網頁操作。以下 prompt 可直接接在 AGY、Claude Code 或 Codex 的開發對話後面；採專案安裝時，請從安裝 skill 的 Angular 專案目錄啟動 agent。
請用 playwright-cli 在實際運行的網站上驗證這次開發的功能，
不要只憑程式碼或編譯成功就判定通過。
- 從這次的原始需求整理驗收流程，只測本次相關功能。
- 關鍵畫面截圖存到 artifacts/playwright-validation/。
- 因缺少帳號、資料或服務而無法驗證的項目，標為「未驗證」並說明原因。
最後用表格回報：流程、預期結果、實際結果、通過／失敗／未驗證、截圖路徑。
這段 prompt 只交代 agent 不會自己做的事：「驗證標準」回到原始需求，「驗證證據」來自實際瀏覽器操作，無法驗證就誠實標示。至於如何讀取快照、依元素參照操作、截圖、查看 console 與網路請求，skill 已經說明，不必在 prompt 重複。對於需要登入或會修改資料的功能，開發任務中應先提供測試環境、測試帳號和允許操作的資料範圍。
前一節的 TodoMVC 命令只用來確認 CLI 能啟動瀏覽器。Angular 功能是否完成，仍以這次需求對應的頁面操作與實際結果為準。
沒有留言:
張貼留言