使用 Playwright CLI 進行視覺品質保證
黃金法則：沒有新鮮的命令輸出就沒有結論。拒絕「看起來應該沒問題」的說法。
最低設定
- Playwright 作為專案的 devDependency；
playwright.config.ts中需明確設定 viewport 為 375px（不要使用devices['Pixel 7']，因為它是 412px），並包含desktop-chrome和mobile-chrome兩個專案。 - 截圖腳本放在
scripts/shot.mjs中（不要為此使用 MCP：CLI 更快且更具可重複性）。 - 為了使用 axe：需要
@axe-core/playwright。 - 啟動正式環境的建置（
npm run build && npm run start）來測量真實的效能；開發環境僅用於除錯。
每個頁面和每個地區的檢查項目
- 主控台與網路：
page.on('console')、page.on('pageerror')、page.on('requestfailed')以及狀態碼 ≥400 的回應。任何失敗都標記為紅色。 - 溢出：在每個 viewport 檢查
document.documentElement.scrollWidth <= clientWidth + 1；如果有溢出，列出導致溢出的元素（getBoundingClientRect().right > innerWidth）。 - 可及性：axe 不能有
critical/serious等級的違規；唯一的h1；所有img[alt]屬性完整；所有可互動元素上的焦點可見（使用真實鍵盤檢查:focus-visible，而非僅看 CSS）；Tab 順序邏輯合理。 - 減少動畫：使用
page.emulateMedia({ reducedMotion: 'reduce' })；不得有閃爍、自動播放或持續時間超過 200ms 的動畫。 - 連結：提取所有
href，驗證內部連結（200），外部連結標記為僅供參考；0 個href="#"且無事件處理器。 - SEO：
title、meta description、canonical、OG 標籤、每個地區的hreflang、可解析的 JSON-LD、sitemap.xml和robots.txt應回傳 200。 - 效能：使用 PerformanceObserver 在載入後測量 LCP/CLS；桌面版目標 LCP < 2.5s 且 CLS < 0.1；使用 rAF 在自動滾動 5 秒期間計算長任務幀（>50ms）來測量滾動抖動。
- Canvas/滾動：由於 canvas 在無頭模式下可能顯示為黑色，請通過 DOM 驗證：檢查預期的 opacity/transform 元素、在正確範圍內的節拍文字是否存在且可見，以及狀態是否暴露在
window中（如果存在的話）。
迭代循環
- 每次執行後：生成一份報告，包含表格（檢查項目/命令/結果/狀態）以及帶有證據（選擇器、日誌或截圖）的阻礙項目列表。
- 如果某個檢查項目失敗：修復它（修改自己的測試/腳本）或提出具體的
src/修正方案並附上證據；然後重複整個循環。 - 將帶有日期的截圖儲存在
docs/qa/中（主要地區的桌面版 + 行動版），並作為基線用於比較回歸。 - 任何檢查項目為紅色或尚未執行時，不得宣告「就緒」。
誠實的限制
- 無法從無頭模式驗證真實 iOS 上的幀序列：請在報告中註明這一點。
- 透過
npx lighthouse使用 Lighthouse 是可選的，但在正式環境建置中建議使用；如果無法執行，請直接說明，不要估算。