antijank - 動畫卡頓偵測工具 是做什麼的?
測量動畫,而非用眼睛觀察。一個探針在頁面中執行,在每次繪製幀後讀取每個監控元素的邊界框(box)、有效不透明度(effective opacity)和滾動位置(scroll position),並僅報告看起來異常的部分。您會獲得每次互動的數行文字報告,而非需要逐一檢查的幀畫面。
它報告的是事實(例如「在一幀內向下移動了 44px」),而非主觀品味。判斷動畫持續時間或緩動函數(easing)是否合適屬於另一項獨立的審查。缺陷(閃爍、跳動、推擠鄰居)會優先列出;而那些完全沒有過渡效果的變化(彈出、替換)則會分開列出,因為立即變更往往是最佳選擇。
選擇執行方式
<skill-dir> 指的是此技能資料夾的路徑(即此檔案所在的資料夾)。
A. 在您已有的瀏覽器中使用:無需安裝任何東西。 如果您有瀏覽器工具(Chrome DevTools MCP、Playwright MCP,或一個能執行 JavaScript 的瀏覽器面板或擴充功能),將探針載入到您正在測試的頁面即可。它會保留該瀏覽器的登入狀態,且不會對專案增加任何依賴。
| 您的工具 | 載入探針的方式 |
|---|---|
| Chrome DevTools MCP | 使用 evaluate_script,並設定 sourcePath: "<skill-dir>/scripts/probe.js" 和 format: "script" |
| Playwright MCP | 使用 browser_run_code(部分版本為 browser_run_code_unsafe):async (page) => { await page.addScriptTag({ path: '<skill-dir>/scripts/probe.js' }) } |
您自己腳本中的一個 Playwright page 物件 | await page.addScriptTag({ path: '<skill-dir>/scripts/probe.js' }) |
| 僅能評估 JavaScript 文字的工具 | 評估下方的 CDN 載入器。如果被阻擋,則改為評估 scripts/probe.min.js(42KB)的內容 |
此 CDN 載入器會取得這個確切的版本,且完整性雜湊值(integrity hash)會讓瀏覽器拒絕任何其他檔案:
await new Promise((ok, fail) => {
const s = document.createElement('script');
s.src = 'https://cdn.jsdelivr.net/npm/[email protected]/skills/antijank/scripts/probe.min.js';
s.integrity = 'sha384-gbt1FS2nRYbhwU3zqdkxuKbH6++BQeLIjkpVPLNNOwbu361o2lV0U6li+N879FDf';
s.crossOrigin = 'anonymous';
s.onload = ok;
s.onerror = () => fail(new Error('antijank: CDN 腳本被阻擋 (Content-Security-Policy 或離線)'));
document.head.append(s);
});
- 在相同頁面上重複載入是安全的,但在每次頁面導航後都需要重新載入。
- 嚴格的 Content-Security-Policy 會阻擋 script 標籤,因此 CDN 載入器和
addScriptTag在這些頁面上會失敗。透過 DevTools 評估檔案內容(使用evaluate_script搭配sourcePath,或直接貼上probe.min.js的內容)則不會被阻擋。 - 瀏覽器分頁必須是可見的。瀏覽器會暫停隱藏分頁或面板中的幀,屆時探針會拒絕記錄(
status: hidden)。 - 使用相同工具來降低 CPU 速度並開啟「減少動畫效果」模式。在 DevTools MCP 中,依序呼叫
emulate並設定cpuThrottlingRate: 4,然後再呼叫一次並設定prefersReducedMotion: "reduce";每次呼叫都會取代前一次,而不帶參數的呼叫則會重置。在 Playwright MCP 中,使用browser_emulate_media並設定reducedMotion: "reduce";對於 CPU 降速,則執行const s = await page.context().newCDPSession(page); await s.send('Emulation.setCPUThrottlingRate', { rate: 4 })。 - 要記錄頁面載入過程,探針必須在頁面本身的腳本執行之前執行。使用 Playwright 時,先加入兩個 init 腳本,然後載入頁面並等待結果:
其他工具:請使用 Runner (B),它預設會記錄頁面載入。await page.addInitScript({ path: '<skill-dir>/scripts/probe.js' }); await page.addInitScript(() => antijank.start({ root: 'main' })); await page.goto(url); const result = await page.evaluate(() => antijank.wait());
B. Runner:適用於 CI、頁面載入測試以及只需一個命令即可執行完整測試矩陣。 它需要一個 shell、Node 22+ 以及專案中的 Playwright,並會以無頭模式搭配自家的 Chromium 執行,因此具有可重複性。
node <skill-dir>/scripts/run.mjs http://localhost:3000/inbox --click "button[aria-label='Compose']" --root main
node <skill-dir>/scripts/run.mjs http://localhost:3000 --steps steps.json --matrix
node <skill-dir>/scripts/run.mjs http://localhost:3000/settings # 記錄頁面載入
此 Runner 僅支援 Chromium,並在 Node 上執行,無論專案使用何種技術棧。如果專案中沒有 Playwright,Runner 會提示。使用專案已有的套件管理器(檢查 lockfile)來安裝 Playwright,然後下載 Chromium:
| Lockfile | 安裝 Playwright | 下載 Chromium |
|---|---|---|
pnpm-lock.yaml | pnpm add -D playwright | pnpm exec playwright install chromium |
yarn.lock | yarn add -D playwright | yarn playwright install chromium |
bun.lock / bun.lockb | bun add -d playwright | bunx playwright install chromium |
deno.lock | deno add npm:playwright(需在 deno.json 中設定 "nodeModulesDir": "auto",以便 Node 能找到它) | deno run -A npm:playwright install chromium |
package-lock.json 或無 lockfile | npm i -D playwright | npx playwright install chromium |
在他人專案中新增依賴項前請先詢問;選項 A 不需任何依賴項。執行 node <skill-dir>/scripts/run.mjs --help 查看所有選項。Runner 會為其自身的瀏覽器關閉 Content-Security-Policy。
記錄
當操作可以在頁面內部執行時:
const result = await antijank.record(() => document.querySelector('#open').click(), { root: 'main' });
antijank.report(); // 文字報告
record 會等待動作的 Promise 完成後,才讓記錄過程趨於穩定,因此可以完整記錄一個包含多個步驟的非同步操作。
當您從頁面外部驅動操作時(透過工具進行真實的點擊和輸入),請保持記錄開啟直到操作完成:
antijank.start({ root: 'main', hold: true }); // 1. evaluate
// 2. click, type, wait: 互動所需的多個步驟
await antijank.release(); // 3. evaluate: 在最後一個步驟後趨於穩定,並以結果 resolve
antijank.report();
在點擊一個元素前先懸停在其上(DevTools MCP 使用 hover,Playwright MCP 使用 browser_hover),就像真人操作一樣,並在第一次輸入前至少一秒開始記錄。一個直接跳到元素上的點擊會在其按下時才開始觸發懸停效果;而一個會自行更新的元素(時鐘、即時計數器)需要這一秒的緩衝,才能被辨識為持續變化的狀態;否則兩者都可能被誤認為是點擊的反應。Runner 在每次點擊前都會先懸停。
如果不使用 hold,記錄會在沒有元素移動約 330ms 後自動結束,這可能發生在您的兩個步驟之間。一個從未釋放的「hold」會在 holdTimeout(預設 60 秒)後因錯誤而終止。antijank.wait() 會在記錄結束後以結果 resolve;antijank.stop() 則會立即結束記錄。
工作流程
- 決定要記錄什麼。 每次記錄一個互動:觸發動作、應該反應的頁面部份(
root),以及什麼算是「完成」。如果變化需要等待網路請求,請傳入waitFor參數並帶上一個選擇器,該選擇器在內容到達後才會存在,否則記錄可能會在一切發生前就趨於穩定。 - 盡可能使用 production build。 Dev 建置會重播效果(React StrictMode)且熱重載會引入停頓,因此動畫可能與正式發行的版本不同。如果必須使用 dev 模式,請在報告中說明。
- 記錄並閱讀報告。 嚴重程度(Severity)是一個起點:HIGH 幾乎總是可見的,LOW 通常沒問題。
- 判斷哪些結果是有意為之的。 無動畫的變化會與缺陷分開列出。對於頁籤、選單、工具提示以及任何頻繁觸發或鍵盤驅動的元素,立即變更是合理的選擇,因此不要僅為了清除一個發現就加入動畫。透過預期(Expectation)來鎖定預期的行為,或在元素上標記
data-antijank-ignore。 - 為應該發生的行為撰寫預期(Expectations)(如下所述),並重新執行。這能將「看起來沒問題」的主觀判斷轉換為 pass/fail 測試,同樣的規格文件稍後也能用於防止回歸錯誤。
- 修復缺陷,然後重新執行。 作為最終檢查,請在正常速度、CPU 降速 4 倍以及開啟「減少動畫效果」模式下分別記錄(Runner 使用
--matrix,選項 A 使用模擬呼叫),因為時序錯誤(幀率低時動畫吃掉第一幀、延遲的 transform)通常只在 CPU 緩慢時才會出現。 - 用數據報告結果,例如「composer 在 170ms 內從 245 移動到 562px,其他元素移動不超過 1px,三種條件下均無任何發現」。
發現類型及其常見原因
| 發現類型 | 含義 | 常見原因與修復 |
|---|---|---|
blip | 在錯誤位置停留了 1–3 幀,然後彈回正確位置 | FLIP transform 晚了一幀才應用(在 paint 之後)。在與佈局變更相同的幀內測量並設定反向 transform:使用 layout effect,而非 effect 或 rAF |
jump(開始) | 第一步移動很大,然後才平滑移動 | 動畫從錯誤的起點開始,或者第一幀在設定起始值之前就已繪製 |
jump(結束)/ snap | 平滑移動,然後在結束時突然彈回 | 目標值錯誤(過時的測量值),或者在佈局符合前就清除了 transform |
jump(中間) | 某一幀的移動遠大於其前後幀 | 動畫進行中佈局改變了(內容到達),或兩個動畫交接不順 |
shift | 靜止的元素在一幀內移動了 | 其上方有元素被插入、移除或調整大小,且沒有動畫。[cause: …] 標示出插入、移除或移動;[same frame: …] 標示出在同一幀中的大小調整,這可能是原因而非確鑿的證據。請為該大小變更添加動畫、預留空間,或改用疊加層 |
pop-in / pop-out | 以完全不透明(無動畫)的狀態出現或消失 | 如果立即變更是有意的,則沒問題。否則表示缺少進入或離開動畫,或者進入過渡效果從未執行,因為起始樣式從未被渲染(在同一個幀中新增的 class 又被移除) |
flash | 僅可見 1–2 幀 | 預留位置或過時狀態渲染了一幀;條件式渲染反覆切換 |
flicker | 不透明度下降後又恢復 | 重新掛載(key 變更)、狀態重置或離開動畫重新啟動 |
swap | 一個元素在原地被另一個取代,沒有交叉淡入效果(無動畫) | 對於頁籤和即時切換的視圖來說沒問題。否則表示缺少共享元素或 hero 過渡效果 |
reversal | 在移動途中方向反轉 | 兩個動畫驅動同一個值,或重新定位到一個舊的位置 |
oscillation | 方向逐幀反覆 | 兩個腳本衝突(滾動錨定對抗跟隨效果、ResizeObserver 迴圈) |
resettle | 停止後又移動 | 在延遲的測量後進行修正(字型、圖片、非同步內容) |
overshoot | 移動遠遠超過目標 | 彈簧反彈(spring bounce)高於預期。如果彈跳是刻意設計的,請忽略 |
stretch | 文字比例不均勻 | 對包含文字的元素進行 scale 動畫;對其子元素進行反向比例縮放,或者改用動畫尺寸(width/height) |
scroll-jump / scroll-fight | 滾動位置跳動或方向改變 | 無平滑滾動的程式化滾動、滾動錨定,或兩個追隨者衝突 |
slow-frame | 一幀花費了 50ms 或更多 | 動畫期間的主執行緒工作(會標示腳本名稱)。"Forced layout" 表示某腳本在修改樣式後立即讀取了佈局屬性(offsetHeight、getBoundingClientRect),通常發生在迴圈中:應先讀取所有值,再進行寫入 |
slow-response | 對點擊、Enter、Space 或 Escape 鍵,在 100ms 或更長時間內無任何反應 | 在工作或請求執行期間,沒有按下狀態(pressed state)或待定狀態(pending state)。請立即顯示一個。[cause: main thread busy …] 表示一個緩慢的處理器阻止了回應的繪製 |
layout-anim | 對 width、height、top、margin 等屬性進行動畫 | 每幀都會觸發佈局計算。對於小型手風琴元件還可接受;對於大型或頻繁的動畫,建議改用 transform |
運動相關的發現(Motion findings)會命名在該幀中驅動元素或其祖先的動畫名稱:[animation: transition transform 300ms ease-out]、[animation: animation slide-in 400ms ease on div.panel] 或 [animation: Web Animation of opacity, transform 200ms linear]。請先檢查該 CSS 規則或函式呼叫。如果沒有命名動畫,通常表示運動是由腳本驅動的(requestAnimationFrame、spring 函式庫)或根本沒有動畫。
Expectations(預期行為)
傳入 expect 參數(或 --expect 選項)可以獲得 pass/fail 輸出,並在失敗時以 exit code 1 結束:
{
"moves": { "[data-composer]": { "dy": 317, "tolerance": 2 } },
"still": "others",
"maxShift": 1,
"fadesIn": [".toast"],
"fadesOut": ["[role=dialog]"],
"noFindings": "medium"
}
moves:從第一幀到最後一幀的淨位移(單位為 px)。如果元素被重新掛載,它會追蹤螢幕上當前的副本。still:必須不能移動超過maxShift的元素。使用"others"表示整個記錄過程中都存在且未在其他地方指定的所有元素。一個未匹配任何元素的选择器會導致測試失敗。fadesIn:元素在其第一個可見幀時,不透明度必須低於 50%,並在結束時達到 90% 或以上。fadesOut:在其最後一個可見幀時,不透明度必須低於 50%。noFindings:不應存在任何達到或超過該嚴重程度的發現,包括無動畫的變化。- Runner 的
--fail-on <severity>參數會在有達到或超過該嚴重程度的缺陷時以 exit code 1 退出。無動畫的變化不計入;如果需要淡入/淡出效果,請改用fadesIn或fadesOut來要求。 - 任何未匹配到元素的選擇器都會導致該預期失敗,因此打字錯誤也不會被靜默忽略。
保持報告的實用性
- 使用
root將範圍限定在應該反應的區域。這樣更快也更安靜。在根區域外部添加的疊加層仍會被監控:任何直接新增到<body>的元素、固定定位的元素,以及對話框(dialog)、選單(menu)、彈出面板(popover)、工具提示(tooltip)和提示訊息(toast)(透過role、aria-modal、popover或<dialog>找到)。 - 如果指定的
root尚不存在,腳本會等待其出現。它以root出現時的內容作為基準線;因此要判斷一個面板如何出現,請使用一個在它之前就已存在的 root(或不指定 root)。 - 一個一次性插入(或移動到位,例如串流 HTML)的子樹,會作為一個發現被報告,並標示該子樹及其包含的元素數量。
- 只有那些會繪製某些內容的元素(文字、背景、邊框、陰影、背景濾鏡、
::before/::after內容、圖片、表單控制項)才能產生發現。透明的包裝元素會保持靜默,因此其內部有繪製內容的子元素會代替它們報告。 - 無限循環的 CSS 和 Web Animations(spinner、shimmer 效果)會自動被忽略。一個永不停止的 JavaScript 迴圈...