Playwright 和 widget test 的互補

Widget test 在 Flutter test framework 中執行，不需要瀏覽器，驗證的是 widget tree 的結構和狀態。Playwright 在真實瀏覽器中執行，驗證的是渲染後的 DOM 和視覺呈現。

兩者的分工：widget test 驗證「邏輯上正確」（該有的元素存在、該觸發的事件發生），Playwright 驗證「視覺上正確」（元素在正確的位置、顏色和大小符合設計）。

Playwright test 的基本結構

 1import { test, expect } from '@playwright/test';
 2
 3test('terminal screen shows connection status', async ({ page }) => {
 4  await page.goto('http://localhost:8080');
 5  
 6  // 點擊連線按鈕
 7  await page.click('text=Connect Terminal');
 8  
 9  // 等待畫面轉換
10  await page.waitForSelector('[data-testid="terminal-screen"]');
11  
12  // 驗證連線狀態顯示
13  const status = page.locator('[data-testid="connection-status"]');
14  await expect(status).toBeVisible();
15});

三個位置的斷言

Playwright test 中的斷言放在三個位置，各自驗證不同的東西：

假設斷言（test 開頭）：驗證 test 的前置條件。頁面載入成功、初始狀態正確。如果假設斷言失敗，test 的後續結果不可信。

行為斷言（操作之後）：驗證 UI 操作的即時效果。點擊按鈕後 dialog 出現、表單提交後顯示成功訊息。

互動斷言（流程結束）：驗證完整操作流程的最終狀態。多步驟操作完成後畫面回到預期狀態。

Selector 策略

Playwright 用 selector 定位 DOM 元素。Selector 的穩定性決定了 test 的維護成本。

推薦：data-testid

在 HTML 元素上加 data-testid 屬性，Playwright 用 [data-testid="xxx"] 定位。data-testid 不受 CSS class 改名、文字內容變更、DOM 結構調整影響。

1<button data-testid="connect-button">Connect Terminal</button>

可接受：文字內容

用 text=Connect Terminal 定位。在按鈕文字穩定的場景下可用，但多語系支援或文案調整時會斷。

避免：CSS selector

用 .btn-primary 或 #main-content > div:nth-child(2) 定位。CSS class 和 DOM 結構的改動頻率高，test 頻繁因無關變更而失敗。

和開發伺服器的整合

Playwright test 需要一個正在運行的 web 應用。整合方式：

手動啟動：開發者先啟動 dev server，再跑 Playwright test。適合本地開發。

自動啟動：Playwright 設定檔中指定 webServer 配置，Playwright 自動啟動 dev server，test 結束後自動停止。適合 CI。

1// playwright.config.ts
2export default defineConfig({
3  webServer: {
4    command: 'npm run dev',
5    port: 8080,
6    reuseExistingServer: !process.env.CI,
7  },
8});

下一步路由

• 視覺比對 → 螢幕截圖比對
• 狀態覆蓋策略 → Widget test 的狀態覆蓋策略
• 導航路徑 test → 導航路徑 test

待寫章節

• Widget test 的狀態覆蓋策略（從狀態矩陣推導 test case）
• 導航路徑 test（back 按鈕、route 可達性）
• Playwright 瀏覽器驗證流程
• 螢幕截圖比對（visual regression）

跨分類引用

• ← ux-design 模組一 畫面狀態機：狀態矩陣是 test case 的 SOT
• ← ux-design 模組五 導航模式：go vs push 語意影響 test 斷言

運作方式

建立 baseline

第一次執行時擷取每個測試畫面的螢幕截圖，儲存為 baseline。Baseline 代表「目前正確的視覺狀態」。

比對差異

後續執行時擷取當前截圖，和 baseline 逐像素比對。差異超過閾值時 test 失敗，產出 diff 圖片標示差異區域。

更新 baseline

視覺變更是刻意的（新設計、改佈局）時，用新截圖覆蓋 baseline。更新 baseline 是明確的決策 — 代表「新的視覺狀態是正確的」。

Playwright 的截圖比對

Playwright 內建 toHaveScreenshot() 方法：

1test('terminal screen matches baseline', async ({ page }) => {
2  await page.goto('http://localhost:8080/terminal');
3  await page.waitForSelector('[data-testid="terminal-screen"]');
4  
5  await expect(page).toHaveScreenshot('terminal-connected.png', {
6    maxDiffPixelRatio: 0.01,  // 允許 1% 像素差異
7  });
8});

首次執行時自動建立 baseline 截圖，後續執行時自動比對。Diff 圖片儲存在 test results 目錄。

Diff 閾值設定

像素比對的閾值影響 test 的敏感度：

過低（0.001）：anti-aliasing 差異、字體渲染微調、次像素定位變化都會觸發失敗。Test 頻繁因無關變化而失敗（flaky）。

過高（0.1）：小型 layout 偏移、顏色微調、邊框消失可能不被偵測。Test 的保護力下降。

建議起點（0.01）：允許 1% 的像素差異。能容忍 anti-aliasing 差異，同時捕捉有意義的視覺變化。根據實際 flaky 頻率調整。

Baseline 管理

版本控制

Baseline 截圖加入 git。每次視覺變更的 PR 包含 baseline 更新，reviewer 從 diff 中看到「視覺變化了什麼」。

Baseline 檔案較大（PNG，數十 KB 到數百 KB）。Git LFS 適合管理這類二進位檔案。

跨平台差異

不同作業系統的字體渲染、anti-aliasing 演算法不同。同一段 HTML 在 macOS 和 Linux 上的截圖會有微小差異。

處理策略：

• 一個平台一套 baseline：macOS 和 Linux 各自維護 baseline。CI 環境固定在一個平台。
• 只在 CI 比對：本地開發不跑截圖比對（平台差異導致 flaky），CI 環境固定平台後比對。

動態內容

畫面中有動態內容（時間戳、隨機 ID、動畫）時，截圖每次都不同。

處理策略：

• 遮蔽動態區域：截圖前用 CSS 隱藏動態元素，或在截圖比對時指定忽略區域。
• 固定動態值：test 中 mock 時間和隨機數，讓畫面內容確定。
• 只截靜態區域：用 element screenshot（locator.screenshot()）而非 full page screenshot，只截不含動態內容的區域。

和其他 test 層的關係

截圖比對是 UI test 的最外層 — 驗證視覺呈現而非邏輯行為。它和 widget test（驗證 widget 結構）、導航 test（驗證路由行為）互補：

widget test 通過但截圖比對失敗 = 邏輯正確但視覺不對（CSS bug）。截圖比對通過但 widget test 失敗 = 視覺沒變但邏輯壞了（功能 bug 還沒影響到視覺）。

下一步路由

• 狀態覆蓋策略 → Widget test 的狀態覆蓋策略
• Playwright 驗證流程 → Playwright 瀏覽器驗證流程
• 畫面狀態矩陣 → ux-design 模組一 畫面狀態矩陣

Playwright 不是最後手段、是縮短診斷迴圈的工具。 當靜態 CSS 推理 + 視覺截圖溝通的循環失敗 ≥ 2 次、就應該停止推理、改用 playwright browser_evaluate 直接讀 live DOM 與 computed style。早一點用 = 試錯次數更少、心智負擔更輕。

為什麼推理迴圈有極限

商業邏輯

CSS 行為由「規則 + DOM tree + 樣式繼承 + 框架渲染」四個變數共同決定。靜態推理只能基於假設的 DOM tree — 假設錯了、推理就錯。視覺截圖溝通只能傳達「結果是什麼」、無法傳達「為什麼是這個結果」。

Playwright 的 browser_evaluate 直接執行 JS 在 live page、返回真實的 DOM tree、computed style、bounding rect — 把「四個變數」全部變成已知。

推理 vs 量測的成本曲線

第 1 次推理快、後續成本爆炸；playwright 起步慢、後續穩定。門檻在第 2 次。

這次任務的實際情境

觀察

要把 search scope UI 放在「搜尋輸入框與結果之間」。

第一輪：基於 class name 推測 DOM tree、用 grid + display:contents 設 grid-row 排序。第二輪：發現 scope 跑到頁尾、嘗試調 grid-template-rows。第三輪：嘗試 absolute 定位但時機不對。第四輪：使用者說「思路錯了」、要我換方向。

判讀

四輪推理都基於同一個假設：drawer 是 .pagefind-ui 的直接子節點、跟 form 並列。實際用 playwright 一查：

1const drawer = document.querySelector('.pagefind-ui__drawer');
2let parents = []; let el = drawer;
3while (el && el !== document.body) {
4  parents.push(el.tagName + '.' + el.className);
5  el = el.parentElement;
6}

返回：

1DIV.pagefind-ui__drawer
2FORM.pagefind-ui__form    ← drawer 在 form 內！
3DIV.pagefind-ui

假設錯了 — drawer 是 form 的 child、不是 sibling。grid 規則無論怎麼寫都不會生效，因為 drawer 跟 form 共用同一個 grid cell。

四輪推理 ≈ 30 分鐘。Playwright 一次查清楚 ≈ 2 分鐘。

執行

確認 DOM 結構後：grid 不適合這個場景、改用 absolute + drawer margin-top spacer。一次到位。

Playwright 在開發循環的三個位置

1. 假設驗證

寫 CSS 規則前先量 DOM、確認結構符合假設。

1async () => ({
2  parents: [].slice.call(document.querySelectorAll('.target')).map(el => {
3    let chain = []; let n = el;
4    while (n) { chain.push(n.tagName + '.' + n.className); n = n.parentElement; }
5    return chain;
6  })
7})

2. 行為驗證

Layout 規則寫完後驗證實際結果。

1async () => ({
2  rect: document.querySelector('.target').getBoundingClientRect(),
3  computed: getComputedStyle(document.querySelector('.target')).gridRow,
4})

3. 互動驗證

驗證使用者互動後的狀態。

1async () => {
2  const input = document.querySelector('.search-input');
3  input.value = 'pre';
4  input.dispatchEvent(new Event('input', { bubbles: true }));
5  await new Promise(r => setTimeout(r, 1000));
6  return Array.from(document.querySelectorAll('.result'))
7    .filter(el => getComputedStyle(el).display !== 'none')
8    .map(el => el.textContent.slice(0, 50));
9}

內在屬性比較：四種 debug 方法

選擇順序：簡單 layout 用 DevTools；複雜 / 反覆 debug 用 playwright；推理只在第 1 次試錯前。

引入 playwright 的最低門檻

1# 啟動本地 server（任何方式）
2python3 -m http.server 8000 --directory public
3
4# 或專案有 hugo
5hugo server

Playwright MCP 提供：

• browser_navigate(url) — 開頁
• browser_evaluate(fn) — 執行 JS 拿結果
• browser_take_screenshot() — 截圖
• browser_snapshot() — accessibility tree

寫一個 evaluate fn ≈ 30 行 JS，比反覆推理快得多。

設計取捨：CSS / DOM debug 工具選擇

四種做法、各自機會成本不同。這個專案在推理 ≥ 2 次失敗後選 A（playwright browser_evaluate）當預設、其他做法在特定情境合理。

本篇是 #42 2 次門檻 抽象原則在「debug 工具切換」這個面向的應用。

A：Playwright browser_evaluate 程式化讀 live DOM（這個專案的預設）

• 機制：起 server、用 browser_evaluate 寫 JS query 讀 DOM tree / computed style / bounding rect
• 選 A 的理由：取得資訊量最大、可重跑、可寫成測試
• 適合：推理失敗 ≥ 2 次、複雜或反覆 debug 的情境
• 代價：起步成本中（需要 server + 寫 evaluate）

B：靜態 CSS 推理 + 視覺截圖溝通

• 機制：純看 CSS 與假設的 DOM 推測、用截圖跟使用者溝通
• 跟 A 的取捨：B 起步成本 0、A 起步成本中；但 B 第 2 次以後成本爆炸（每輪都基於前輪錯誤假設）
• B 比 A 好的情境：第 1 次嘗試、預估假設正確機率高（簡單修改）

C：瀏覽器 DevTools 手動查

• 機制：開 DevTools 切 Elements / Computed / Layout 面板手動探索
• 跟 A 的取捨：C 不需 server / playwright setup、但每次手點切面板慢、不能寫成測試
• C 比 A 好的情境：一次性確認、不需要重複 query 同樣資訊

D：寫成 playwright 測試固化

• 機制：把 debug 過程寫成 playwright 測試、未來自動跑
• 跟 A 的取捨：D 是 A 的延伸 — 第 2 次 debug 同個版型時、值得固化（#15 layout tests）
• D 比 A 好的情境：版型 bug 出現第 2 次以上、值得寫測試防止回歸

判讀徵兆

核心原則：縮短診斷迴圈的工具該早一點用、不該等到推理徹底失敗。第 2 次推理失敗就切換、別等第 5 次。

延伸應用：playwright 也用來查「資料層 vs 視覺層的層錯位」 — 見 #55 Filter 與 Source 的抽象層錯位 用 browser_evaluate 量 source 真實 cardinality 與分批機制。

當一個版型被 debug 兩次以上、就值得寫成 playwright 測試。 測試替代「手動檢查 + 截圖」的循環、讓版型回歸可被機器發現。下次有人改 CSS 時、測試會立刻指出哪個假設被破壞。

為什麼版型問題適合自動化

商業邏輯

排版問題的特徵：

人腦適合「驚訝時注意」、不適合「重複檢查 100 個 case 是否如預期」。後者是機器擅長的。

兩種測試層次

兩種互補。視覺迴歸抓「整頁有沒有變」、結構斷言抓「特定關係有沒有保持」。

這次任務的測試機會

觀察

搜尋頁的版型在這次開發中被 debug 多輪：

判讀

每個 debug 過 ≥ 2 次的版型場景都值得寫測試 — 表示這個地方很容易壞、未來改 CSS 還會踩。

執行：寫 playwright 測試

 1// tests/search-layout.spec.js
 2import { test, expect } from '@playwright/test';
 3
 4test.describe('search page layout', () => {
 5  test('desktop ≥ 1400 顯示左側 filter sidebar', async ({ page }) => {
 6    await page.setViewportSize({ width: 1440, height: 900 });
 7    await page.goto('/blog/search/');
 8    await page.fill('.pagefind-ui__search-input', 'pre');
 9    await page.waitForSelector('.pagefind-ui__filter-panel');
10
11    const slot = await page.$('.search-filter-slot');
12    const isVisible = await slot.isVisible();
13    expect(isVisible).toBe(true);
14
15    const filterParent = await page.evaluate(() =>
16      document.querySelector('.pagefind-ui__filter-panel').parentElement.className
17    );
18    expect(filterParent).toContain('search-filter-slot');
19  });
20
21  test('viewport < 1400 filter 留在 pagefind drawer', async ({ page }) => {
22    await page.setViewportSize({ width: 1024, height: 900 });
23    await page.goto('/blog/search/');
24    await page.fill('.pagefind-ui__search-input', 'pre');
25    await page.waitForSelector('.pagefind-ui__filter-panel');
26
27    const filterParent = await page.evaluate(() =>
28      document.querySelector('.pagefind-ui__filter-panel').parentElement.className
29    );
30    expect(filterParent).toContain('pagefind-ui__drawer');
31  });
32
33  test('scope UI 在三互動狀態下都在 input 與 results 之間', async ({ page }) => {
34    await page.setViewportSize({ width: 1440, height: 900 });
35    await page.goto('/blog/search/');
36
37    async function getY(selector) {
38      return page.evaluate(s => document.querySelector(s).getBoundingClientRect().y, selector);
39    }
40
41    // 狀態 1：初始載入
42    let scopeY = await getY('.search-scope');
43    let inputY = await getY('.pagefind-ui__search-input');
44    expect(scopeY).toBeGreaterThan(inputY);
45
46    // 狀態 2：點 input
47    await page.click('.pagefind-ui__search-input');
48    scopeY = await getY('.search-scope');
49    inputY = await getY('.pagefind-ui__search-input');
50    expect(scopeY).toBeGreaterThan(inputY);
51
52    // 狀態 3：輸入字
53    await page.fill('.pagefind-ui__search-input', 'pre');
54    await page.waitForSelector('.pagefind-ui__results .pagefind-ui__result');
55    scopeY = await getY('.search-scope');
56    inputY = await getY('.pagefind-ui__search-input');
57    const resultsY = await getY('.pagefind-ui__results');
58    expect(scopeY).toBeGreaterThan(inputY);
59    expect(scopeY).toBeLessThan(resultsY);
60  });
61});

每個 expect 對應一條版型契約 — 這條被破壞時測試紅、改 CSS 的人立刻知道。

測試的維護成本與收益

內在屬性比較

第 1 次寫成本中、第 2 次以後成本碾壓手動。門檻在「會 debug 第 2 次嗎」。

測試什麼、不測什麼

適合測試的版型場景

• 跨 viewport 的元件顯示 / 隱藏切換
• 元件相對位置（A 在 B 上方 / 下方 / 左右）
• 元件順序（type 在 tag 前）
• 互動狀態下的位置不變（scope 在三狀態下都在 input 與 results 之間）

不適合用 playwright 測

• 純視覺差異（顏色微差、圓角 1px 差） — 用 visual regression 工具
• 動畫過程 — 不穩定、容易 flaky
• 字型 rendering 細節 — 跨 OS / 瀏覽器差異大

選擇原則：測「結構性契約」、不測「畫素」。畫素級檢查交給 visual regression。

設計取捨：版型驗證機制的選擇

四種做法、各自機會成本不同。這個專案在版型 debug ≥ 2 次後選 A（結構斷言測試）當預設、其他做法在特定情境合理。

本篇是 #42 2 次門檻 抽象原則在「驗證機制升級」這個面向的應用。

A：Playwright 結構斷言測試（這個專案的預設）

• 機制：寫 expect(scopeY > inputY) 這類斷言、自動跑、跨字型 / 主題都對
• 選 A 的理由：規範化（測試本身是文件）、跨環境穩定、回歸自動偵測
• 適合：debug ≥ 2 次的版型場景、需要長期保護的 layout 契約
• 代價：寫測試的初始成本、需要 playwright runtime

B：手動截圖檢查

• 機制：開頁面、看截圖、人眼確認
• 跟 A 的取捨：B 起步成本 0、A 起步成本中；但 B 重複成本高（每次回歸都要看）
• B 比 A 好的情境：第 1 次驗證（debug 過 1 次、不確定值不值得寫測試）、純探索期

C：Visual regression snapshot

• 機制：截整頁圖跟 baseline 比對、像素級差異
• 跟 A 的取捨：C 涵蓋率廣（整頁所有變動都偵測）、A 只測指定契約；但 C false positive 多（字型微調 / theme 換色都觸發）
• C 比 A 好的情境：純視覺驗證（marketing page）、設計穩定不常改

D：不寫測試

• 機制：純信任手動驗證
• 跟 A 的取捨：D 0 維護成本、A 有測試維護；但 D 在版型反覆壞時累積「腦中知識」、新人接手不知道
• D 才合理的情境：純探索期 / prototype、確定不上 production

判讀徵兆

核心原則：版型契約用測試固定 — 測試紅了表示契約被打破、不是測試壞了。每個紅色測試都是有人改了不該改的東西的訊號。

跟 #68 驗收的時間軸 的關係：layout test 是 Checkpoint 3「Ship 前」的具體做法 — 跨 viewport / 跨狀態 / 跨資料規模驗收、catch 開發中 checkpoint 看不到的整合錯。沒寫 layout test = 把 ship 前 checkpoint 跳過、所有版型回歸都進 ship 後（使用者反映才修）。

寫完 layout test 必須在「未修版型」跑 RED 確認測試會抓到該抓的、再在「修後版型」跑 GREEN 確認修對了 — 兩個訊號都看到、測試才被驗證。詳見 #69 Test-First：先看到 RED 才相信 GREEN。

驗證工具的引入時機不該等推理徹底失敗。 靜態 CSS 推理或視覺截圖溝通連續失敗 ≥ 2 次、立刻主動提「我們啟個 server、我用 playwright 看 live DOM」 — 工具的價值是縮短診斷迴圈、不是最後手段。

為什麼要主動提工具

商業邏輯

執行者堅持靠推理 = 把使用者拖進「截圖 - 反饋 - 再試」的長循環。每輪都消耗使用者時間（看截圖、描述問題、回應）— 對使用者是負擔。

主動提工具切換 = 把循環從「視覺溝通」改成「程式量測」。執行者直接讀 live DOM、診斷一輪到位、使用者只需要在最終確認。

主動提的成本是「打一句話建議」、收益是「省 N 輪截圖溝通」。

這次任務的實際情境

觀察

drawer 在 form 內、不是 sibling 這個假設錯誤、靠推理 + 截圖溝通走了多輪：

第 4 輪用 playwright browser_evaluate 讀 ancestor chain — 一個 query、一個答案、兩分鐘解。前三輪 ≈ 30 分鐘。

判讀

第 2 輪失敗時就應該主動提：

「我嘗試了兩次都失敗、根因可能在我對 DOM 結構的假設。要不要啟個 server、我用 playwright 直接讀 live DOM 確認？這樣比繼續用截圖溝通快。」

使用者啟 server、我跑 query、一輪解。

執行：主動提工具的 protocol

驗證工具該在這些時機主動提：

工具引入的成本與價值

內在屬性比較

「起步成本」是一次性、「每輪成本」是重複的。第 2 輪以後、playwright 的 ROI 已經正向。

主動提的具體話術

較差的提法

「要不要試試 playwright」

模糊、使用者不一定知道為什麼要試、可能答「先這樣吧」。

較好的提法

「我嘗試了兩次都失敗、根因可能不在 CSS、在我對 DOM 結構的假設。 要不要啟個 server（python3 -m http.server 8000 在 public/）、 我用 playwright browser_evaluate 直接讀 ancestor chain 確認？ 這樣比繼續用截圖快很多。」

說明：

• 為什麼提：兩次失敗、推理迴圈成本超過工具迴圈
• 要使用者做什麼：啟 server、給一行指令
• 我會做什麼：用 playwright evaluate 讀
• 預期收益：縮短迴圈

使用者明確知道 trade-off、決定簡單。

工具迴圈的標準流程

11. 使用者啟 server（python3 -m http.server / hugo server）
22. 執行者 navigate 到目標頁面
33. 執行者寫 evaluate fn 讀真實狀態
44. 執行者根據結果定位根因
55. 執行者改 CSS / JS
66. 執行者再 evaluate 驗證修復
77. 使用者目視最後確認（可選）

整個流程多數步驟在執行者這邊、使用者只在頭尾參與 — 對使用者負擔輕。

設計取捨：驗證工具引入的時機

四種做法、各自機會成本不同。這個專案選 A（推理 ≥ 2 次失敗主動提）當預設、其他做法在特定情境合理。

本篇是 #42 2 次門檻 抽象原則在「驗證工具切換」這個面向的應用。

A：推理 ≥ 2 次失敗主動提工具切換（這個專案的預設）

• 機制：靜態推理連續失敗 2 次、立刻提「啟個 server、我用 playwright 看 live DOM」+ 附啟用步驟與預期收益
• 選 A 的理由：對使用者透明（看到 trade-off）、縮短診斷迴圈
• 適合：CSS / DOM 行為跟預期不符的除錯
• 代價：執行者要主動辨識「推理迴圈成本」與「工具迴圈成本」的交叉點

B：等使用者要求才用工具

• 機制：執行者繼續推理、使用者覺得太慢時提
• 跟 A 的取捨：B 對使用者更被動、A 主動；B 在使用者不知道有 playwright 選項時、會一直繼續
• B 才合理的情境：使用者明確表達「想用推理練習」、把工具切換當成放棄

C：全程靜態推理、不用工具

• 機制：堅持推理到底
• C 是反模式：推理迴圈成本累積、最後可能需要 4-5 輪才解決
• 看起來吸引人的原因：覺得用工具是「能力不足」、想撐到自己想出來
• 實際發生的代價：時間成本指數放大（每輪推理基於前輪錯假設）、最後還是要切工具

D：一開始就用 playwright、不嘗試推理

• 機制：跳過推理、直接用工具量
• 跟 A 的取捨：D 跳過推理階段省去 2 次嘗試、但前期 setup 成本投入比例較高（簡單問題不值得）
• D 比 A 好的情境：問題明確需要 live DOM 才能診斷（例如「framework 渲染後的結構」）— 推理本來就無法解

判讀徵兆

核心原則：工具引入時機是「推理迴圈成本超過工具迴圈成本」的點 — 大多在第 2 次推理失敗時。早一點提、雙方都省時間。

跟 #68 驗收的時間軸 的關係：本卡是「debug 工具切換時機」、#68 是「驗收動作分散在四個時點」 — 兩者共用「動作該分配到哪個時點才有 ROI」這個結構。本卡的「第 2 次推理失敗就切工具」≈ #68 的「ship 前要設計 E2E case」 — 都是「把高 ROI 的動作放在對的時點、不要延後」。

協議的核心命題：先讀真實狀態、再寫規則；先量再改、不要靠假設。前端 bug 多半來自「寫 CSS 時假設的 DOM 結構與實際不符」、「JS 改完元素被 framework 還原」、「listener 觸發頻率失控」。Playwright 把這些假設變成可驗證的量測值。

Core Pillars（支柱）

Principles（原則速查）

讀者在本區塊能完成大方向判斷；具體展開（步驟 / 範例）依下方「觸發路由」進對應 reference。

1. 寫 CSS 前先確認 DOM topology

Class name 是約定、不是結構保證。寫 CSS 規則之前、用 playwright browser_evaluate 讀目標元素的 ancestor chain — 確認它在 DOM tree 的哪個位置、parent / sibling / 共用的 grid cell 是什麼。

Selector 設計三維度：起點（document / 元件根 / 函式參數 / closest）+ 範圍（直接子節點 / 子孫）+ 過濾（attribute / 已處理標記）。預設用最精準的、有證據再放寬。

2. CSS / JS 的邊界由「值能否 build-time 定下來」決定

能在 build time 算出來的值（design token、固定 breakpoint、靜態尺寸）→ 寫進 CSS variable / static rule。必須 runtime 才能知道的值（form 高度、scroll 位置、container 寬度）→ JS 量測後寫回 CSS variable、CSS 仍然只讀變數。

JS 的職責是 toggle class / 寫 var、不是設 inline style。!important / inline display: none 是 anti-pattern — 改用 class toggle 把樣式留在 CSS。Vendor CSS 用 @layer 包起來、自家 unlayered 自動贏 specificity。

3. Playwright 在開發循環的三個位置

位置 1：假設驗證（寫 CSS 前）— 讀 ancestor chain、確認結構符合假設。 位置 2：行為驗證（規則寫完後）— 讀 bounding rect / computed style、確認 layout 結果。 位置 3：互動驗證（dispatch event 後讀 state）— 模擬 input / click、量化驗證互動結果。

第 2 次同個版型 bug → 把 query 寫成 playwright 測試固化、CI 防回歸。

4. 與 framework-managed DOM 共處的邊界辨識

把 framework 子樹當「禁區」、客製 UI 注入到 framework 邊界外、用 CSS 控制視覺位置（absolute / margin / grid）。框架重渲染時、邊界外的客製 UI 不被 reconcile 清掉。

JS 操作的邊界穩定性（從穩到不穩）：reparent 整節點 > 改 inline style > 改 attribute > 改 textContent > 改 innerHTML > 改 framework 子節點。穩定性低的需要 MutationObserver 重做、或乾脆別碰。

外部組件客製的合作層次（穩定性梯度）：CSS variable / API > class hook > boundary DOM > 內部結構。離公共介面越近、升級越穩。

5. Reactive 監聽器的頻率盤點

MutationObserver 三維度：root（最窄）、options（最少）、debounce（最長可接受）。預設 observer.observe(scope, { childList: true })、不寫 subtree: true 除非有 case。

Polling（setTimeout / setInterval）有事件可監聽就替換成 MutationObserver — 0 latency / 0 idle CPU。Reactive perf debug 從 console.count(callbackName) 起、確認觸發頻率符合預期。

效能風險點四面向：iteration 成本（500 results × regex test）、reflow 成本（>16ms 觸發 jank）、listener 頻率（如上）、resource 載入時序（lazy chunk vs critical path）。

6. A11y 三道防線

鍵盤可達性：visible focus indicator、邏輯 tab 順序、modal 有 escape 路徑。三者缺一不可。 動態 a11y：JS reparent / hide 時保存並還原 focus；變動內容用 aria-live="polite" 廣播給 screen reader。 Native > ARIA：能用 <button> / <fieldset> / <dialog> 就不要自己組 ARIA role — native HTML 自帶 keyboard / focus / a11y tree、ARIA 是補強不是替代。

When to Consult This Skill（觸發路由）

每份 reference 自包含：以該情境為核心、把六大原則翻譯成可直接套用的協議步驟與範例。閱讀任一 reference 不需要回來看其他 reference。

Success Criteria（M1-M2 認知負擔類）

Directory Index

 1frontend-with-playwright/
 2├── SKILL.md                                    # 本檔：六大原則速查 + 觸發路由
 3└── references/
 4    ├── dom-topology-first.md                   # 情境 1：寫 CSS 前用 playwright/DevTools 量真實 DOM、selector 設計
 5    ├── css-js-boundary.md                      # 情境 2：CSS-only vs JS-assisted、class toggle、layers、variable 單一位置、檔案拆分
 6    ├── playwright-in-loop.md                   # 情境 3：playwright 三個位置（假設 / 行為 / 互動驗證）+ 寫成 layout test
 7    ├── framework-coexistence.md                # 情境 4：custom UI 留 framework 邊界外、外部組件四層合作、JS 操作邊界辨識
 8    ├── reactive-performance.md                 # 情境 5：observer scope、polling→observer、頻率盤點、iteration / regex / reflow
 9    ├── accessibility-and-focus.md              # 情境 6：focus on DOM move、keyboard 三要素、aria-live、native HTML > ARIA
10    └── data-flow-and-filter-composition.md     # 情境 7：Filter × Source 層錯位 + 五策略 + 跨領域（前端 / 後端 / 演算法 / DB）

Reading Order（建議閱讀順序）

1. 第一次接觸 → 從本 SKILL.md 的「三大支柱 + 六大原則」讀起
2. 進入實際情境 → 依觸發路由讀對應 reference（只讀一份）
3. 想驗證自己有沒有套用對 → 用該 reference 結尾的 self-check checklist 自評

跟 requirement-protocol 的關係

requirement-protocol 是上層的「對話協議」（澄清需求、失敗轉折、覆寫成本、工具切換時機）；本 skill 是下層的「前端執行協議」（DOM / CSS / JS / Playwright 的具體做法）。

當情境是「不確定該怎麼跟使用者溝通」 → 讀 requirement-protocol。 當情境是「知道要做什麼、不確定前端該怎麼實作驗證」 → 讀本 skill。 兩個 skill 的 playwright 段落互補：requirement-protocol/tool-switching-timing 講「何時切」、本 skill 的 playwright-in-loop 講「切了之後具體寫什麼 query」。

requirement-protocol/clarifying-ambiguous-instructions 的「類型 5：篩選類」跟本 skill 的 data-flow-and-filter-composition 互補：上層講「該怎麼澄清」、本層講「澄清完該怎麼實作」。

相關抽象層原則（在 content/report/）

本 skill 的協議建立在幾條抽象層原則上：

• #42 2 次門檻 — 第 1 次失敗是運氣、第 2 次是訊號（playwright 切換時機的根據）
• #43 最小必要範圍 — selector / observer / 操作邊界從窄起（DOM 設計、Reactive 效能的根據）
• #44 SSOT — 值的住址只能一處（CSS 變數、量測一致性的根據）
• #45 外部組件合作四層 — 離公共介面越近越穩（framework 共處的根據）
• #64 同層合成 — Stream 操作必須跟 materialization 同層（Filter × Source 的本質）
• #67 寫作便利度跟意圖對齊反相關 — 容易寫的位置通常是錯位的位置（meta-principle、解釋為什麼層錯位 / 寬 selector / inline style 等便利寫法都會出問題）
• #68 驗收的時間軸：四個 checkpoint — Layout test 屬 Ship 前 checkpoint 的具體做法
• #69 Test-First：先看到 RED 才相信 GREEN — Playwright 測試的驗證協議：寫完測試 + 第一次跑就 GREEN 是警訊、要先在 buggy code 上看到 RED 才相信測試 catch 到該 catch 的東西
• #70 URL 是 stateful UI 的儲存層 — 互動式 UI 的可分享 / 可恢復 / 可導航 state 該寫進 URL（搜尋 / filter / tab / sort / pagination 都該檢視）
• #71 Tab Order = DOM Order = Mental Model 三者對齊 — DOM 順序預設 = tab 順序、不對齊時優先重排 DOM、tabindex > 0 是反模式
• #72 高 ROI 無外部觸發的工作會被結構性跳過 — meta-原則：寫測試 / refactor / a11y review / Ship 前 case 設計都需要外部觸發（CI / pre-commit / PR template）、不是靠紀律
• #73 搜尋引擎的匹配模式跟使用者預期的對齊 — Search feature 的 capability 維度：prefix vs substring vs fuzzy vs semantic 各自取捨、預設多為 prefix（為 index size）、跟使用者預期不對齊 = silent 失敗
• #79 決策對話的五維度 — 設計取捨呈現給使用者時的 meta-框架（呈現 / 策略疊加 / 批次 / 時間 / 選項類型）— 「設計取捨段落」常用的五策略表 + 推薦 + 「先 ship X、Y 下輪」就是這五維度的展現
• #82 字面攔截 vs 行為精煉 — playwright 測試是字面驗證（input → output 比對）、抓不到「為什麼這個 selector 設計錯」這類行為錯誤、需要 multi-pass review 配合

Last Updated: 2026-04-26 Version: 0.4.0 — 接入 #79 決策對話五維度（對應 #74-#78 系列）；協助前端設計取捨段落的呈現格式對齊 user-facing 決策協議 Version: 0.3.0 — 接入 #69-#73：相關抽象層原則段補 Test-First (#69)、URL state (#70)、tab order (#71)、外部觸發 meta (#72)、search 匹配模式 (#73) Version: 0.2.0 — 接入 #55-#68 系列：新增第 7 份 reference data-flow-and-filter-composition（涵蓋 Filter × Source 層錯位 + 五策略 + 跨前端 / 後端 / 演算法 / DB 領域範例）；description 補跨領域 stream 操作觸發詞；SKILL.md 加「相關抽象層原則」段（#42-45 + #64 + #67-68）；強調「不只前端、stream 操作通用」 Version: 0.1.0 — 從 content/report/ 50+ 篇事後檢討萃取「前端網頁開發 + Playwright 驗證」這條主軸；六份 references 對應「DOM topology / CSS-JS 邊界 / Playwright 三位置 / framework 共處 / Reactive 效能 / A11y」六個情境

frontend-with-playwright 是一套前端開發協議 skill，原生位置在 .claude/skills/frontend-with-playwright/ 供 Claude runtime 呼叫；這份是同內容的文章版本，讓人類讀者也能直接在 blog 閱讀。

原則框架無關 — 適用 vanilla HTML/CSS/JS、Vue、React、jQuery — 因為核心是「DOM / CSS / JS 三者的本質行為」加上「Playwright 用 live DOM 量測驗證」、不依賴特定框架的渲染機制。源頭是 content/report/ 累積的 50+ 篇事後檢討、由本 skill 的六份 reference 萃取對應六個情境的協議步驟。

閱讀順序

場景 1：第一次接觸

場景 2：已熟悉協議、想直接解決當前任務

直接依觸發情境跳對應 reference：

每份 reference 自包含：讀任一份不需要回頭讀其他 reference。

跟 requirement-protocol 的關係

requirement-protocol 是上層的「對話協議」（澄清需求、失敗轉折、覆寫成本、工具切換時機）；本 skill 是下層的「前端執行協議」（DOM / CSS / JS / Playwright 的具體做法）。

兩個 skill 的 playwright 段落互補：requirement-protocol 講「何時切」、本 skill 講「切了之後具體寫什麼 query」。

與 blog 專案其他資料的關係

Last Updated

2026-04-26 — v0.2.0 接入 #55-#68 系列：新增第 7 份 reference data-flow-and-filter-composition（Filter × Source 層錯位 + 五策略 + 跨前端 / 後端 / 演算法 / DB 範例）；強調原則跨領域通用、不只前端。

歷史版本：

• 2026-04-26 — v0.1.0 初版：六份 references 對應「DOM topology / CSS-JS 邊界 / Playwright 三位置 / framework 共處 / Reactive 效能 / A11y」六個情境

適用：CSS / DOM debug、layout 驗收、互動行為驗證、寫 layout regression test。 不適用：純 unit test（function input/output、無 DOM）— 那用 Vitest / Jest 即可。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋三個位置的具體 query 範例、layout test 模板、最低門檻 setup。

何時參閱本文件

為什麼 playwright 是前端開發的核心驗證工具

CSS / DOM 的真實狀態 = 規則 + DOM tree + 樣式繼承 + 框架渲染的合成結果。靜態推理只能基於假設、視覺截圖只能傳達結果不傳達原因。

Playwright browser_evaluate 直接執行 JS 在 live page、返回 DOM tree / computed style / bounding rect — 把假設變成量測值。寫一個 evaluate fn ≈ 30 行 JS，比反覆推理快得多。

位置 1：假設驗證（寫 CSS 規則前）

量 ancestor chain

1async () => {
2  const el = document.querySelector('.target');
3  let chain = []; let n = el;
4  while (n && n !== document.body) {
5    chain.push(`${n.tagName}.${n.className}`);
6    n = n.parentElement;
7  }
8  return chain;
9}

量子節點與 sibling

1async () => {
2  const parent = document.querySelector('.pagefind-ui');
3  return Array.from(parent.children).map(c => `${c.tagName}.${c.className}`);
4}

量元素是否存在 / 數量

1async () => ({
2  count: document.querySelectorAll('.result').length,
3  first: document.querySelector('.result')?.outerHTML.slice(0, 200),
4})

寫 CSS 規則前 30 秒能省掉後續 30 分鐘推理。

位置 2：行為驗證（規則寫完後）

量 bounding rect

1async () => ({
2  form: document.querySelector('.pagefind-ui__form').getBoundingClientRect(),
3  scope: document.querySelector('.scope').getBoundingClientRect(),
4  results: document.querySelector('.results').getBoundingClientRect(),
5})

返回 {x, y, width, height, top, right, bottom, left} 的純物件、能直接 assert 順序與位置。

量 computed style

 1async () => {
 2  const el = document.querySelector('.target');
 3  const cs = getComputedStyle(el);
 4  return {
 5    display: cs.display,
 6    position: cs.position,
 7    gridRow: cs.gridRow,
 8    color: cs.color,
 9    zIndex: cs.zIndex,
10  };
11}

量「實際贏的 CSS rule」

1async () => {
2  const el = document.querySelector('.target');
3  // CSSOM 沒提供標準 getMatchedCSSRules；用 computed style 加 inspect
4  return getComputedStyle(el).cssText;  // 全部 computed properties
5}

或在 DevTools Computed panel 看 — 但 playwright 能寫成測試重跑。

位置 3：互動驗證（dispatch event 後讀 state）

模擬 input

1async () => {
2  const input = document.querySelector('.search-input');
3  input.value = 'pre';
4  input.dispatchEvent(new Event('input', { bubbles: true }));
5  await new Promise(r => setTimeout(r, 1000));  // 等 debounce / async render
6  return Array.from(document.querySelectorAll('.result'))
7    .filter(el => getComputedStyle(el).display !== 'none')
8    .map(el => el.textContent.slice(0, 50));
9}

模擬 click

1async () => {
2  document.querySelector('.scope-toggle button[data-scope="title"]').click();
3  await new Promise(r => setTimeout(r, 500));
4  return {
5    activeScope: document.querySelector('.scope-toggle [aria-pressed="true"]')?.dataset.scope,
6    visibleResults: document.querySelectorAll('.result:not([hidden])').length,
7  };
8}

模擬 viewport resize（透過 playwright API、不在 evaluate 內）

1await page.setViewportSize({ width: 375, height: 667 });
2const result = await page.evaluate(() => ({
3  layout: document.querySelector('.layout').getBoundingClientRect(),
4  sidebarVisible: getComputedStyle(document.querySelector('.sidebar')).display !== 'none',
5}));

第 2 次同個 bug → 寫成 layout 測試固化

第 1 次 debug 完成後、bug 修好。第 2 次同個版型問題（不同 commit / viewport / 內容狀態）再出現 → debug 完後把 query 寫成 playwright 測試。

 1import { test, expect } from '@playwright/test';
 2
 3test('search scope is between form and results', async ({ page }) => {
 4  await page.goto('/search/?q=pre');
 5  await page.waitForSelector('.result');
 6
 7  const formRect = await page.locator('.pagefind-ui__form').boundingBox();
 8  const scopeRect = await page.locator('.scope-toggle').boundingBox();
 9  const resultsRect = await page.locator('.results').boundingBox();
10
11  expect(scopeRect.y).toBeGreaterThan(formRect.y + formRect.height);
12  expect(resultsRect.y).toBeGreaterThan(scopeRect.y + scopeRect.height);
13});
14
15test('sidebar visible at 1400px+', async ({ page }) => {
16  await page.setViewportSize({ width: 1400, height: 800 });
17  await page.goto('/search/?q=pre');
18  await expect(page.locator('.sidebar')).toBeVisible();
19});
20
21test('sidebar hidden at < 1400px', async ({ page }) => {
22  await page.setViewportSize({ width: 1399, height: 800 });
23  await page.goto('/search/?q=pre');
24  await expect(page.locator('.sidebar')).toBeHidden();
25});

未來 layout 改動觸發 regression、CI 立刻發現。

寫 layout test 的優先順序

不要每個 layout 都寫測試 — 寫測試的 ROI 條件：

最低門檻 setup

Server

1# 任何方式起本地 server
2hugo server                                       # Hugo
3python3 -m http.server 8000 --directory public    # 純靜態
4npm run dev                                        # framework dev server

Playwright MCP（給 Claude 用）

Claude 透過 MCP 提供的 tool：

• browser_navigate(url) — 開頁
• browser_evaluate(fn) — 執行 JS 拿結果
• browser_take_screenshot() — 截圖
• browser_snapshot() — accessibility tree
• browser_click(selector) / browser_type(selector, text) — 互動

Playwright 測試（給 CI 用）

1npm i -D @playwright/test
2npx playwright install
3npx playwright test

playwright.config.ts 設 baseURL 指向 http://localhost:1313（Hugo 預設）或自訂 port。

Wrong vs Right 對照

範例 1：CSS 不生效

錯：靜態推理 + 截圖溝通 4 次失敗。

對：第 2 次失敗 → 切 playwright：

 1// 1. 確認 ancestor chain
 2async () => {
 3  const el = document.querySelector('.target');
 4  let chain = []; let n = el;
 5  while (n) { chain.push(`${n.tagName}.${n.className}`); n = n.parentElement; }
 6  return chain;
 7}
 8// → 看到目標元素是 form 的 child、不是 .pagefind-ui 的直接 child
 9
10// 2. 確認 computed style 誰贏
11async () => getComputedStyle(document.querySelector('.target')).color
12// → "rgb(0,0,255)" — vendor 的藍色贏了
13
14// 3. 換方向：用 @layer 把 vendor 包起來

範例 2：Layout 第 2 次出現一樣的 bug

錯：手動在不同 viewport 下視覺驗證、commit、過幾週又壞、又手動驗證。

對：第 2 次出現後寫成測試：

1test('layout golden path: form → scope → results', async ({ page }) => {
2  for (const width of [375, 768, 1024, 1400, 1920]) {
3    await page.setViewportSize({ width, height: 800 });
4    await page.goto('/search/?q=pre');
5    const form = await page.locator('.pagefind-ui__form').boundingBox();
6    const scope = await page.locator('.scope-toggle').boundingBox();
7    expect(scope.y, `at width=${width}`).toBeGreaterThanOrEqual(form.y + form.height);
8  }
9});

未來改 CSS、CI 直接告訴你哪個 viewport 壞了。

RED-GREEN 順序：先看到 RED 才相信 GREEN

寫完 playwright test 後、必須先在「buggy code」跑出 RED 才能相信「fixed code」的 GREEN。詳見 #69 Test-First：先看到 RED 才相信 GREEN。

修 bug 的順序：

1. 先寫測試 + 跑 → RED（在 buggy code 上 fail、證明測試會 catch + bug 真的存在）
2. 修 code
3. 跑測試 → GREEN（證明修對了 + 測試會抓回歸）

跳過 step 1 的 retrospective 補救（修完才補測試）：

 1# Stash 修復、checkout 修前 commit
 2git stash && git checkout <pre-fix-commit>
 3
 4# Cherry-pick 測試 commit、build、跑
 5git cherry-pick <test-commit>
 6make site && npm test
 7# 預期：RED
 8
 9# 切回修後版本
10git checkout main && git stash pop
11npm test
12# 預期：GREEN

兩個訊號都看到 + 順序對、測試才被驗證。

自檢清單（dogfooding）

debug / 驗證 layout 時：

• 寫 CSS 規則前、有沒有用 playwright 量過 ancestor chain？
• 規則寫完後、有沒有用 playwright 量過 bounding rect / computed style 確認？
• 互動行為（filter / click）有沒有用 playwright 模擬 + 量化驗證？
• 同個 layout bug 第 2 次出現時、有沒有寫成測試？
• 推理失敗 ≥ 2 次時、有沒有主動切換到 playwright（不等到第 5 次）？

延伸閱讀

對應的事後檢討（在 content/report/）：

• playwright-early-in-loop — 在開發循環裡早一點用 playwright 看真實結果
• layout-tests-with-playwright — 用前端測試把排版問題自動化
• verification-method-timing — 驗證方法的選擇時機

Last Updated: 2026-04-26 Version: 0.1.0

適用：CSS / DOM debug、layout 卡關、不確定該用哪個工具。 不適用：純邏輯 bug（這時 logging / debugger 比 layout 工具有用）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋四種工具的 ROI 對照、切換時機、最低門檻入口。

何時參閱本文件

為什麼工具切換要早、不該等到推理徹底失敗

CSS 行為由「規則 + DOM tree + 樣式繼承 + 框架渲染」四個變數共同決定。靜態推理只能基於假設的 DOM tree — 假設錯了、推理就錯。視覺截圖只能傳達「結果是什麼」、無法傳達「為什麼」。

Playwright 的 browser_evaluate 直接執行 JS 在 live page、返回真實的 DOM tree、computed style、bounding rect — 把四個變數全部變成已知。

門檻在第 2 次：第 1 次推理快（假設正確時一次到位）；第 2 次推理失敗 → 假設可能錯 → 繼續推理會在錯誤假設上累積。Playwright 起步成本中、但後續穩定。

四種工具的 ROI 對照

選擇順序：

Playwright 在開發循環的三個位置

位置 1：假設驗證（寫 CSS 規則前）

確認 DOM 結構符合假設。

1async () => {
2  const drawer = document.querySelector('.pagefind-ui__drawer');
3  let chain = []; let n = drawer;
4  while (n && n !== document.body) {
5    chain.push(`${n.tagName}.${n.className}`);
6    n = n.parentElement;
7  }
8  return chain;
9}

返回值對照假設、發現 drawer 是 form 的 child（不是 sibling）→ grid-row 控制無效、改方向。

位置 2：行為驗證（layout 規則寫完後）

驗證實際 layout 結果。

1async () => ({
2  rect: document.querySelector('.target').getBoundingClientRect(),
3  computedTop: getComputedStyle(document.querySelector('.target')).top,
4  computedDisplay: getComputedStyle(document.querySelector('.target')).display,
5})

位置 3：互動驗證（使用者操作後的狀態）

1async () => {
2  const input = document.querySelector('.search-input');
3  input.value = 'pre';
4  input.dispatchEvent(new Event('input', { bubbles: true }));
5  await new Promise(r => setTimeout(r, 1000));
6  return Array.from(document.querySelectorAll('.result'))
7    .filter(el => getComputedStyle(el).display !== 'none')
8    .map(el => el.textContent.slice(0, 50));
9}

第 2 次同個 bug → 寫成測試固化

第 1 次 debug 完、bug 修好。第 2 次同個版型問題（不同 commit / 不同 viewport）再出現 → debug 完後把 query 寫成 playwright 測試。

1test('search scope is between form and results', async ({ page }) => {
2  await page.goto('/search/?q=pre');
3  const formRect = await page.locator('.pagefind-ui__form').boundingBox();
4  const scopeRect = await page.locator('.scope-toggle').boundingBox();
5  const resultsRect = await page.locator('.results').boundingBox();
6  expect(scopeRect.y).toBeGreaterThan(formRect.y + formRect.height);
7  expect(resultsRect.y).toBeGreaterThan(scopeRect.y + scopeRect.height);
8});

未來 layout 改動觸發 regression、CI 立刻發現、不需要再人工 debug。

Playwright 引入的最低門檻

1# 起本地 server（任何方式）
2python3 -m http.server 8000 --directory public
3# 或 hugo server
4hugo server

Playwright MCP 提供的核心工具：

• browser_navigate(url) — 開頁
• browser_evaluate(fn) — 執行 JS 拿結果
• browser_take_screenshot() — 截圖
• browser_snapshot() — accessibility tree

寫一個 evaluate fn ≈ 30 行 JS。比反覆推理快得多。

主動切換訊號（不要等使用者打斷）

當以下任一觸發、執行者要主動提：「我推理 2 次失敗了、我們起 server、用 playwright 量 live DOM 確認假設」。不要等到第 5 次才切。

Wrong vs Right 對照

範例 1：CSS 不生效

錯：

1/* 改了 3 次 specificity、還是沒生效 */
2.target { color: red; }                    /* 失敗 */
3.parent .target { color: red; }            /* 失敗 */
4.parent .container .target { color: red; } /* 失敗 */
5.parent .container .target { color: red !important; } /* 失敗 */

對：

1.target { color: red; }

第 2 次失敗 → 切 playwright：

1async () => getComputedStyle(document.querySelector('.target')).color
2// 返回 "rgb(0, 0, 255)" — 不是我寫的紅色

1async () => {
2  const el = document.querySelector('.target');
3  return Array.from(getMatchedCSSRules?.(el) || [])
4    .map(r => r.cssText);
5}
6// 看到 vendor 的 .pagefind .target { color: blue !important } 在贏

→ 換方向：用 CSS Layers 把 vendor CSS 包進 layer、自家 unlayered 自動贏。

範例 2：Layout 在 mobile viewport 錯

錯：

反覆推理 + 在 DevTools 切 viewport 視覺確認 → 改 → 失敗 → 改 → 失敗。

對：

第 2 次推理失敗、切 playwright：

1async () => {
2  await page.setViewportSize({ width: 375, height: 667 });
3  return {
4    h1: document.querySelector('h1').getBoundingClientRect(),
5    form: document.querySelector('form').getBoundingClientRect(),
6    scope: document.querySelector('.scope').getBoundingClientRect(),
7  };
8}

量化資料 → 立刻看到「scope 的 top 比 form 的 bottom 小 12px」→ overlap → 改 form margin-bottom。

自檢清單（dogfooding）

debug 卡關時：

• 我推理失敗幾次了？≥ 2 次 → 該切換工具
• 我能說出「假設是什麼、用什麼工具能驗證」嗎？
• 切到 playwright 之前、有沒有試圖用更努力的推理多撐一次？（如果有 → 停）
• 第 2 次同個版型 bug 出現時、有沒有寫成測試固化？
• 對外回報切換工具的提案、有沒有寫得具體（要起哪個 server、量什麼）？

延伸閱讀

對應的事後檢討（在 content/report/）：

• playwright-early-in-loop — 在開發循環裡早一點用 playwright 看真實結果
• verification-method-timing — 驗證方法的選擇時機
• layout-tests-with-playwright — 用前端測試把排版問題自動化

Last Updated: 2026-04-26 Version: 0.1.0