沒有桌面的 Linux 也能讓 AI agent 操作網站並截圖。本文以 Playwright CLI 搭配 Antigravity CLI（AGY）、Claude Code 或 Codex，驗證 agent 剛完成的 Angular 功能。以下假設 agent 已安裝並登入，Angular 專案也已存在。
1. Playwright CLI 是什麼？
Playwright CLI 是給 coding agent 使用的瀏覽器命令列工具。它預設以 headless 模式啟動瀏覽器，因此本文的範例不需要桌面或 DISPLAY。
它的基本工作方式是：
open開啟網站，snapshot取得元素及其參照編號（例如e8）。- Agent 依快照用
fill、click、check等指令操作，再檢查結果。 screenshot保存畫面，供 agent 對照需求回報結果。
CLI 負責操作瀏覽器；skill 是教 agent 使用 CLI 的本地說明文件。本文示範即時驗證；若要把測試提交到版本庫、日後重跑，需另寫 Playwright Test 測試檔，並用 npx 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：
npm install -g @playwright/cli@latest
沒有瀏覽器：選擇 Chromium 安裝方式
若只跑 headless，安裝 Chromium headless shell 即可。它本身就是瀏覽器程式，無須另外安裝完整 Chromium：
playwright-cli install-browser chromium --with-deps --only-shell
在要測試的專案中建立 .playwright/cli.config.json，只指定 browserName；不要指定 channel：
cd /path/to/your-project
mkdir -p .playwright
printf '%s\n' '{"browser":{"browserName":"chromium"}}' > .playwright/cli.config.json
playwright-cli open https://demo.playwright.dev/todomvc/
playwright-cli close
這樣的 open 會使用 headless shell。不要加 --browser=chromium；該選項會改用完整版 Chrome for Testing。下方安裝專案 skill 時，也須跳過自動下載完整版 Chromium。Playwright 的 headless shell 說明
若要使用 open --browser=chromium，需安裝完整版 Chromium。下列指令會下載 Chrome for Testing 與 headless shell：
playwright-cli install-browser chromium --with-deps
兩種安裝指令都應以平常執行 open 的 Linux 使用者執行。--with-deps 安裝系統套件時可能要求管理員權限；不要在整條指令前加 sudo，以免瀏覽器下載到 root 的快取。
已有 Chrome 或 Edge：使用本機瀏覽器
已有 Chrome 或 Edge 時，只需安裝 CLI。它們本身支援 headless，無須再下載 Chromium 或 headless shell。啟動時指定瀏覽器：
playwright-cli open https://example.com --browser=chrome
playwright-cli close
# 或
playwright-cli open https://example.com --browser=msedge
playwright-cli close
install-browser <名稱> 與 open --browser=<名稱> 的差別：
| 名稱 | install-browser |
open --browser=... |
|---|---|---|
chromium |
下載完整版 Chrome for Testing 與 headless shell 到 Playwright 快取；加 --only-shell 則只下載 shell |
使用完整版 Chrome for Testing；只裝 shell 時須用上方不指定 channel 的設定檔 |
firefox |
下載 Playwright 修改過的 Firefox 到快取 | 使用 Playwright 管理的 Firefox |
webkit |
下載 Playwright 管理的 WebKit 到快取 | 使用 Playwright 管理的 WebKit |
chrome |
安裝正式版 Chrome 到系統位置，可能覆蓋原有安裝 | 使用本機 Chrome |
msedge |
安裝正式版 Edge 到系統位置，可能覆蓋原有安裝 | 使用本機 Edge |
沒有設定檔，也未指定 --browser 時，open 預設使用本機 Chrome。CLI 預設以 headless 模式執行；headless 仍需要瀏覽器程式。參見 Playwright 瀏覽器說明與 CLI 安裝文件。
只有在有桌面環境且要顯示瀏覽器視窗時，才在 open 加上 --headed。
Playwright CLI 通常會為自動化工作建立獨立的瀏覽器使用者資料，不會直接沿用你日常瀏覽器的分頁或登入狀態。
接著選擇 skill 的適用範圍。CLI 程式已由前面的 npm install -g 安裝。
安裝到單一專案
在要測試的專案目錄執行 playwright-cli install --skills=...。它會建立 .playwright/，若專案是 Git 版本庫，還會把 .playwright-cli/ 加入 .gitignore。沒有設定檔時，它會優先使用本機 Chrome、其次 Edge；兩者都沒有則下載完整版 Chromium，並建立設定檔。快照等輸出存於 .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
只裝 headless shell 時，用以下命令取代上面的兩條，避免 install --skills 再下載完整版 Chromium：
cd /path/to/your-project
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 playwright-cli install --skills=agents
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 playwright-cli install --skills=claude
安裝到目前使用者的所有專案
-g 把 skill 裝到使用者家目錄，不初始化專案，也不下載瀏覽器或建立設定檔：
playwright-cli install --skills=claude -g # ~/.claude/skills/playwright-cli/
playwright-cli install --skills=agents -g # ~/.agents/skills/playwright-cli/
若使用前面安裝的 Chromium，可在家目錄建立設定檔，讓所有專案的 open 預設使用它。完整版 Chromium 的設定：
mkdir -p ~/.playwright
echo '{ "browser": { "browserName": "chromium", "launchOptions": { "channel": "chromium" } } }' > ~/.playwright/cli.config.json
只裝 headless shell 時，省略 channel：
mkdir -p ~/.playwright
printf '%s\n' '{"browser":{"browserName":"chromium"}}' > ~/.playwright/cli.config.json
若同時有專案與全域設定檔，兩者應選用同一種 Chromium 安裝方式；只裝 headless shell 時，兩處都不可指定 channel。
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/"
若只用 AGY CLI，仍先執行 playwright-cli install --skills=agents -g 作為複製來源。更新 skill 後，也要重新複製到 AGY CLI 的目錄。全域路徑依 Antigravity 官方文件與 OpenAI Docs。
從專案目錄啟動或重新啟動 agent，載入新 skill：AGY 用 agy、Claude Code 用 claude、Codex 用 codex。AGY 可輸入 /skills 確認 skill 已載入。
用 TodoMVC 確認 CLI 可以開啟頁面：
playwright-cli open https://demo.playwright.dev/todomvc/
playwright-cli snapshot
playwright-cli close
此處的 open 使用上方的專案或全域設定。若選擇本機 Edge 且未建立設定檔，在 open 後加上 --browser=msedge。
open 應回傳網址、標題與快照檔路徑。snapshot 會列出元素，例如：
- 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 "買牛奶" 操作。參照編號會隨頁面改變，操作前要讀取當下的快照。
啟動失敗時，檢查所選瀏覽器是否已安裝、設定檔是否指向相同瀏覽器，以及 Linux 發行版或容器映像是否符合 Playwright 系統需求。
3. Angular 開發完成後，怎麼要求 agent 驗證？
在 agent 完成 Angular 功能後，接著要求它依原需求操作實際網站。以下 prompt 可直接接在 AGY、Claude Code 或 Codex 的開發對話後；採專案安裝時，須從安裝 skill 的專案目錄啟動 agent。
請用 playwright-cli 在實際運行的網站上驗證這次開發的功能，
不要只憑程式碼或編譯成功就判定通過。
- 從這次的原始需求整理驗收流程，只測本次相關功能。
- 關鍵畫面截圖存到 artifacts/playwright-validation/。
- 因缺少帳號、資料或服務而無法驗證的項目，標為「未驗證」並說明原因。
最後用表格回報：流程、預期結果、實際結果、通過／失敗／未驗證、截圖路徑。
驗證標準來自原始需求，結果來自實際瀏覽器操作。skill 已說明快照、元素操作、截圖、console 與網路請求的指令。若功能需要登入或修改資料，應先提供測試環境、帳號和可操作的資料範圍。
前一節的 TodoMVC 只檢查安裝是否可用；Angular 功能仍須依需求驗證。
沒有留言:
張貼留言