沒有桌面的 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 功能仍須依需求驗證。