前端工程師：測試自動化與無障礙

這行的痛點

前端工程師的日常有兩種「看起來做完了」最容易騙人：一種是測試全綠，一種是無障礙掃描工具吐出的報告一片乾淨。這兩種假象的病灶其實一樣——Anthropic 官方〈Best practices for Claude Code〉講得很白：AI 寫程式碼「看起來完成」的唯一訊號，就是有沒有人給它一個能自己跑的檢查；沒有這個檢查，「看起來做完」就是唯一的訊號，而你自己會變成那個手動驗證迴圈的人。測試自動化與無障礙稽核，本質上都是「幫 Claude 造一個會吐出 pass/fail 的檢查」，差別只在檢查的對象是「功能有沒有壞」還是「螢幕閱讀器讀不讀得到」。

這也是為什麼這兩個子題放在同一章講：Playwright MCP 讓 Claude 讀真實 DOM 產生會通過的測試選擇器，而不是憑空猜 CSS class；Anthropic 官方的 accessibility-review skill 同樣要求先讀真實頁面（或 Figma 稿）再產出稽核報告——兩邊都靠「讓 AI 真的看到東西」取代「讓 AI 用猜的」。更巧的是，兩邊都撞上同一種陷阱：數字好看不等於品質好。有工程師用 Claude Code 三週衝出 154 個測試、17 個測試檔案，唯獨漏了「發文」這個最核心的功能；另一位工程師的無障礙稽核工具跑出 29 項錯誤，Claude 自己看出「這不是 29 個問題，是 4 種模式重複出現」。兩個故事講的其實是同一件事——測試數量與稽核發現數量都只是代理指標，真正要盯的是「覆蓋到的東西重不重要」，而不是「數字夠不夠大」。

對讀者的實際意義是：如果只把 Claude Code 當成「幫我把測試或稽核跑完」的工具，你會得到一堆綠燈，卻可能漏掉要命的東西；但如果懂得怎麼設計「檢查」本身——選擇器要不要來自真實 DOM、稽核要不要分層到人工鍵盤與螢幕閱讀器測試——Claude Code 才會變成真正省時間的夥伴，而不是製造假安全感的機器。

動手前的準備

• 先確認 Claude Code CLI 已安裝並登入（本站「新手上路」分類的安裝章節有完整步驟，這裡不重複）。
• 專案裡已經有跑得起來的測試框架（Playwright 和／或 Vitest），本機執行 npm test 或 npx playwright test 至少要能動。
• 想用 Playwright MCP／Chrome DevTools MCP 需要先裝好 Node.js 與對應瀏覽器；Chrome 136 之後遠端除錯埠不能用預設使用者設定檔，得指定獨立的 --user-data-dir。
• 想跑無障礙稽核，先準備一種自動化掃描工具（pa11y 搭配 axe-core，或裝一顆 MCP 化的 a11y 稽核伺服器），這類工具都只能抓到約三成問題，人工鍵盤與螢幕閱讀器測試不能省。
• 若要對照 Codex CLI 段落，需要先有 Codex CLI 帳號、一份對應 CLAUDE.md 角色的 AGENTS.md，以及能接受「雲端沙箱、非同步出 PR」這種跟本機互動明顯不同的工作模式。

場景一：讓 Claude 真的「看見」頁面再寫測試

QA 產能常常追不上出貨速度，若只靠一句話描述 UI 讓 AI 憑空猜測 DOM 結構寫測試，選擇器很容易在下一次部署後就失效——因為 AI 從沒真正「看過」那個頁面。Playwright MCP 把「開瀏覽器、點擊、截圖」變成 Claude 讀得懂的訊號，讓它改成讀真實 DOM／無障礙樹（accessibility tree）來產生選擇器，而不是用猜的 CSS class。

Claude Code 怎麼做

1. 1

   安裝 Playwright MCP server，全域裝法：npm install -g playwright-mcp，接上 Claude Code：claude mcp add playwright-mcp playwright-mcp；專案層級也可以直接寫進 .mcp.json：

   {
     "mcpServers": {
       "playwright": {
         "type": "stdio",
         "command": "npx",
         "args": ["@playwright/mcp@latest"]
       }
     }
   }

   複製
2. 2

   用自然語言描述測試流程，讓 Claude 直接開瀏覽器導覽、點擊、填表、截圖定位元素，例如：

   Navigate to the checkout page, fill out the shipping form with sample
   data, and submit it. Take a screenshot before writing selectors, then
   generate a Playwright test that verifies the confirmation message appears.

   複製
3. 3

   因為 Claude 讀的是真實 DOM，產生的選擇器會 resolve，而不是憑空猜的 class。

4. 4

   專案規模變大時，可以把流程拆成分工的 subagent：探索代理讀應用產出 app.context.md → 測試案例代理提出覆蓋範圍（人工核准）→ 自動化代理寫 page object 與 spec → 維護代理只靠 CI 歷史診斷失敗、出 diff 但不自動套用修復。有實測案例指出，一個 API key 工作流吃掉 200k context window 的 55%（約 110k tokens）才產出 3 個 page object 加 1 個 spec，讀單一大檔案就耗掉 137.9k tokens——page object 檔案要切小，是這套分工能不能撐住的關鍵細節。

5. 5

   有一份開源 Playwright MCP server 的實測遙測資料（980 名使用者）可以拿來校準期望：355,654 次工具呼叫、643,424 張截圖對 264,268 次瀏覽器初始化（約 6:1，代表 agent 高度依賴視覺確認而非盲跑）、中位數測試 8 個步驟；但也有 41% 的使用者在 5 次事件後就放棄，說明首次設定的門檻其實不低。

換成 Codex CLI

Codex CLI 這邊有實測可查證的雲端流程，但架構跟 Claude Code 明顯不同：在 ChatGPT 的 Codex 介面連上 repo、送出具體的任務 prompt（模糊指令如「幫登入頁寫測試」表現明顯較差），Codex 會在網路隔離的沙箱裡複製 repo、安裝依賴、產生程式碼，過程是非同步的「送出去就不用等」，沙箱內自己跑 npx playwright test 驗證，最後產出一份附完整變更與終端機記錄的 Pull Request。單檔測試任務約耗時 2 到 8 分鐘，有案例引用透過這套流程把 CI 支出砍了 73%。核心差異可以總結成一張對照表：Codex 走雲端沙箱、非同步、只能 headless 存取瀏覽器、產出是 PR；Claude Code 走本機、即時、透過 MCP 完整存取瀏覽器、直接編輯檔案。簡單說，Codex CLI 適合「批次大量產生」，需要當場盯著瀏覽器互動除錯的場景，本機工具還是比較順手。

場景二：154 個測試全綠，但核心功能「發文」完全沒被測到

有位開發者在專案指令裡明確要求「為每個新的使用者介面行為撰寫測試」，三週後累積 154 項端到端測試、17 個測試檔案，看起來覆蓋率很高。但整個應用最核心的「發佈貼文」功能完全沒有真正的端到端測試——對應的測試檔只驗證頁面有沒有渲染出來，從沒測過「搜尋相簿、填評論表單、送出貼文、確認出現在動態消息裡」這條完整流程。後續認證邏輯重構時，這條沒被測試網住的路徑一次壞掉 25 個以上的後端路由，得靠連續四次「連鎖修復」提交才補完；一個原本只該留在開發環境的除錯端點也因此誤帶上線，導致正式環境當機。作者的原話很扎心：「它測試了除了那個真正重要的東西以外的所有東西」，而且「每一次開發工作階段都『在講』發文，卻沒有一次真正聚焦在發文上」。

Claude Code 怎麼做

這個案例的教訓是：籠統的一句「每個功能都要寫測試」，Claude 會傾向在最容易下手、上下文還熱著的次要模組花時間，而不是自動導向邏輯最複雜、往往也最重要的核心流程。要避免重蹈覆轍，指令要明確指名核心路徑，而不是丟一句概括性要求：

Before writing any more UI tests, list every core user journey in this
app ranked by business importance. For the #1 journey (posting), write
a full end-to-end test that actually exercises the flow end to end —
search for an item, fill the comment form, submit the post, and verify
it appears in the feed. Do not mark this journey "tested" until that
specific test exists and passes.

寫完之後，人工複查測試清單裡有沒有漏掉「最重要的那一個」，比再多寫幾十個次要測試更值得花時間——測試數量高不代表關鍵路徑有被覆蓋，覆蓋率要按業務重要性衡量，不是按檔案數。

換成 Codex CLI

Codex CLI 目前找不到這個場景的第一手案例，但用它的通用能力應該也能做到類似效果：這個「數字好看但漏掉核心功能」的陷阱換到 Codex 的雲端非同步流程裡，風險可能更隱蔽——因為 Codex 產出的是一份附終端機記錄的 Pull Request，人工審查很容易只看「CI 是不是綠的」就核准合併，而不會像本機互動那樣邊寫邊盯著關鍵流程。換句話說，用 Codex CLI 批次產生測試時，「明確指名核心路徑、寫進 PR 描述要求人工對照檢查」這一步可能比在 Claude Code 裡更不能省。

場景三：官方無障礙稽核 skill——同一份規則，稽核自家程式碼也能稽核別人的網站

前端工程師常常想要一個「官方維護、不是隨便哪個 GitHub 個人專案」的無障礙稽核工具，而且希望同一份規則能同時用在「有原始碼」（Claude Code）與「只有網址、沒有原始碼存取權」（Claude in Chrome）兩種情境，例如稽核客戶的第三方網站，或設計交付前的 Figma 稿。Anthropic 官方在 anthropics/knowledge-work-plugins repo 裡維護了 accessibility-review skill，正是為此設計。

Claude Code 怎麼做

1. 1

   Skill 路徑：design/skills/accessibility-review/SKILL.md，觸發詞可以是自然語言（「audit accessibility」「check a11y」），也可以是明確指令：

   /accessibility-review https://your-site.com/checkout

   複製

   $ARGUMENTS 可以傳 Figma URL、網頁 URL，或純文字介面描述。

2. 2

   Skill 內建的測試方法分五層，不是跑完自動化掃描就結束：自動化掃描（skill 文件自己承認「僅捕捉約 30% 問題」）→ 純鍵盤導覽測試 → 螢幕閱讀器測試（VoiceOver、NVDA）→ 色彩對比驗證 → 200% 縮放確認版面不破版。

3. 3

   Skill 內建 WCAG 2.1 AA 速查表，涵蓋 1.1.1（替代文字）、1.4.3（對比 4.5:1／大字 3:1）、1.4.11（非文字對比 3:1）、2.1.1（鍵盤可操作）、2.4.7（焦點指示器）、2.5.5（觸控目標 ≥44×44px）、3.3.1／3.3.2（錯誤識別／標籤）、4.1.2（name/role/value）。

4. 4

   輸出固定是 Markdown 表格，依 Perceivable／Operable／Understandable／Robust 四大分類列出問題、對應 WCAG 準則、嚴重度標記，並附色彩對比檢核表（前景色／背景色／實測比／門檻／是否通過）。

5. 5

   記得這個 skill 明確自陳「自動化僅抓 30%」，不能拿它跑完的綠燈當合規證明，人工鍵盤與螢幕閱讀器複測仍然要做。

換成 Codex CLI

目前找不到 OpenAI 官方對等的 skill，這是 Anthropic 獨有的一手資源。若要在 Codex CLI 上做類似的事，比較務實的替代路徑是掛載通用的 a11y MCP 伺服器（底層一樣是 Deque 的 axe-core 加 Puppeteer），設定方式跟 Claude Code 對等：codex mcp add playwright -- npx -y @playwright/mcp，理論上可以比照掛一顆專門的 a11y 稽核 MCP server。但這只是架構上的推測，目前沒有查到有人實際這樣做過的第一手紀錄，成效不列入正式引用。

場景四：29 個錯誤其實是 4 種模式——用「模式優先於計數」拆解稽核報告

Brent W. Peterson 想稽核自家行銷網站的無障礙，直接和 Claude Code 進行一場訪談式對話，請 Claude 解釋它怎麼做無障礙稽核、發現了什麼、該怎麼修。初次稽核回報 29 項錯誤，Claude 的關鍵洞察是：「不是 29 個獨立問題——而是 4 種模式重複出現」，包括漸層文字標題、text-primary span、text-offset 段落、header 導覽裡重複出現的同類問題。其中最棘手的案例是漸層文字：網站用 background-clip: text 搭配 -webkit-text-fill-color: transparent 做出漸層美術效果，自動化工具偵測到的技術對比度是 0:1（透明文字色），但人眼看起來完全可讀。Claude 對這個矛盾的說法是：「無障礙工具看到『隱形文字』會警報，人類看到漂亮的漸層標題，雙方都正確」。

Claude Code 怎麼做

1. 1

   起手式指令跑一次基準掃描，號稱 30 秒內能抓到 8 成問題：

   npx pa11y --runner axe --standard WCAG2AA https://your-site.com

   複製
2. 2

   拿到一串二位數以上的 violation 清單時，先請 Claude 依「模式」而不是逐項數量分組，例如：「這 29 個錯誤裡，有哪幾個其實是同一個 CSS class 或同一個元件重複造成的？」

3. 3

   對每個模式套用兩個決策問題：真實使用者能不能實際操作？工具測量的東西是不是真的重要？漸層文字這類「設計上刻意」的個案，屬於工具測得出但不一定代表真問題的類型。

4. 4

   具體修復照嚴重度處理：色階從 -400 換成 -200（例如 pink-400 對比可能只有 3.5:1，換成 pink-200 能推過 4.5:1 門檻）；按鈕文字改用深灰取代白色；漸層文字可以加 aria-label 提供文字替代，或採組合方案兼顧設計與螢幕閱讀器可用性。

5. 5

   把這套流程收斂成自訂 slash command——跑 Pa11y 稽核 → 按模式分組 → 依 WCAG 準則分類並標優先度 → 產出修復建議與待辦清單——讓稽核變成可重複使用的工作流，而不是一次性任務。Claude 額外提供的 dark mode 六項檢查清單（文字顏色、強調色、互動元素、文字與圖像／漸層疊合、焦點狀態、連結底線）也值得直接沿用。

換成 Codex CLI

Codex CLI 目前找不到這個場景的第一手案例，但用它的通用能力應該也能做到類似效果：pa11y 本身只是一支 Node CLI 工具，理論上 Codex CLI 一樣能執行同一條 npx pa11y 指令、拿到結構化輸出，「先按模式分組再排優先序」這個方法論也不是 Claude Code 專屬的能力，而是提示詞設計技巧，換到 Codex CLI 應該同樣適用。但有一個實際的環境限制要注意：Codex CLI 預設在網路隔離的沙箱裡執行，若目標網址不是本機或已 mock 的服務，稽核指令可能連不到真實網站，這點在規劃 Codex CLI 版本的稽核流程時得先解決，而不是假設它跟本機環境一樣暢通。

常踩的坑

延伸資源

• Anthropic 官方〈Best practices for Claude Code〉
• Anthropic 官方 accessibility-review skill 原始檔
• TestDino：Claude Code 搭配 Playwright 的 4-agent 流水線與 token 成本細節
• qaby.ai：980 名使用者的 Playwright MCP 實測遙測與「畢業信號」
• christophermeiklejohn.com：154 個測試全綠但核心功能沒測到的真實故事
• Brent W. Peterson：29 個錯誤其實是 4 種模式的無障礙稽核對談