playwright

playwright skill 概覽

這個 playwright skill 能做什麼

playwright skill 是用 playwright-cli 從終端機直接驅動真實瀏覽器，特別適合你需要導覽頁面、填表、截圖、取得快照、擷取內容，或排查 UI 流程問題的情境。它是為瀏覽器自動化而設計，不是拿來撰寫測試套件；它偏好以 CLI 為核心的工作流程，並透過一個 wrapper 腳本運作，即使系統沒有全域安裝 Playwright 也能使用。

誰適合安裝

如果你想要可靠的瀏覽器控制，又不想手動搭一整套自動化架構，就很適合安裝 playwright skill。它特別適合需要檢視即時頁面、重現使用者流程、收集頁面內容，或以可重複方式除錯介面行為的 agent。

最重要的重點

它最大的差異在於以 wrapper 為核心的工作方式：先確認 npx 可用，接著只要設定一次 skill 路徑，就能透過 PWCLI 使用 playwright-cli 指令。這會大幅降低設定摩擦，讓 playwright skill 在臨時自動化任務中尤其實用，特別是當瀏覽器工作內容很雜、或 UI 經常變動時。

如何使用 playwright skill

安裝並設定 skill 路徑

先走標準的 skill 安裝流程：

npx skills add openai/skills --skill playwright

接著在目前的 shell session 或個人設定檔中只要設定一次路徑：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"

在做其他事情之前，先確認 npx 是否存在。如果沒有，先安裝 Node.js/npm；這個 wrapper 依賴它才能運作。

把模糊目標變成好 prompt

要給 skill 一個具體的瀏覽器工作，而不是模糊需求。好的輸入會包含網站、目標動作，以及你想拿回來的成果。

好的 prompt 範例：

• “Use playwright skill to log into the staging app, navigate to the invoices page, and capture a screenshot of the filtered table.”
• “Use playwright for Browser Automation to open this URL, extract the visible product names, and report any console warnings.”
• “Use playwright skill to reproduce this signup error and capture a trace plus the final page state.”

這樣能幫助 skill 選對指令、快照與除錯步驟。

先讀這些檔案

實際使用時，建議先看：

• SKILL.md：核心工作流程與限制
• references/cli.md：指令涵蓋範圍
• references/workflows.md：互動模式與 session 用法
• scripts/playwright_cli.sh：了解 wrapper 如何解析 npx

如果你是在判斷這個 skill 是否適合你的環境，也可以順手看 agents/openai.yaml 了解預設意圖，並查看 NOTICE.txt 了解來源資訊。

實務上的工作流程建議

使用標準循環：開頁面、snapshot、針對元素 ID 操作，然後再 snapshot 一次確認狀態變化。處理表單時，如果你已經知道欄位內容，優先用 fill，不要一個字元一個字元地輸入。做除錯時，請在失敗前後記錄 console、network，以及 tracing-start/tracing-stop，不要只靠猜測。

playwright skill 常見問題

playwright 只是提示詞，還是可實際安裝的工作流程？

它是可實際安裝的 playwright skill，包含 wrapper 腳本與參考指令，不只是提示文字。這點很重要，因為安裝後你會得到可重複的指令結構、session 處理方式，以及可預期的進入點。

什麼情況下不該用 playwright？

如果你只需要靜態程式碼產生、一般 HTTP 請求，或是測試執行器，就不適合用它。如果你的環境無法提供 npx，它也不是好選擇，因為 wrapper 會卡住，直到 Node.js/npm 可用為止。

這適合新手嗎？

如果你的任務確實是瀏覽器工作，而且你能清楚描述頁面與目標，那就適合。主要學習門檻不在 Playwright 語法，而是在於學會把瀏覽器結果描述得具體，並在動作前先檢查 snapshots。

這和 @playwright/test 有什麼不同？

當你要的是 CLI 驅動的瀏覽器自動化時，用這個 skill。當你明確需要測試檔、斷言，或完整 test harness 時，才用 @playwright/test。這個 skill 是為互動式使用與即時工作流程優化，不是完整測試專案。

如何改善 playwright skill

提供更好的起始狀態

最好的結果通常來自明確的輸入：寫出 URL、登入狀態、裝置或 viewport 限制，以及你要拿回的成品。如果任務涉及驗證，請說明是否已有憑證、是否預期 MFA，以及 skill 應該在導覽後停下，還是要繼續送出表單。

清楚說明成功條件

把結束條件講具體，例如：「關閉 modal 後存一張截圖」、「擷取前 20 筆可見列」、「按下 Checkout 後回報任何 console errors」。這能減少不必要的探索，也讓 playwright 的使用結果更可預測。

要求正確的除錯產物

如果流程失敗，請直接要求你需要的證據：用 snapshots 看結構、用 screenshots 看視覺狀態、用 traces 看互動時間序列、用 console/network 看執行階段錯誤。這些都比泛泛地要求「把問題修好」更有用。

避免常見失敗模式

最常見的錯誤，是把 UI 路徑講得太少，卻把實作方式限制得太死。不要要求固定點擊幾次，因為頁面很可能會變；應該直接說明目標，讓 skill 依照當下頁面狀態導航。另外，除非你真的需要 @playwright/test，否則不要把瀏覽器自動化和測試套件需求混在一起。