Community程式設計與開發github.com

antijank - 動畫卡頓偵測工具

捕捉螢幕截圖無法捕捉的一幀 UI 瑕疵。在真實瀏覽器中,記錄互動中每一幀每個元素的位置和不透明度,並以數行文字報告:哪些元素跳動、閃爍、未經淡入跳出、推擠鄰居、反向移動、閃爍、突然滾動或對點擊反應遲緩。可在您已有的瀏覽器(Chrome DevTools MCP、Playwright MCP)中無需安裝即可執行,或透過其 Runner 在無頭模式下執行。

antijank - 動畫卡頓偵測工具 是什麼?

antijank 是一個用於捕捉 UI 動畫中微妙的、單幀缺陷的工具,這些缺陷通常難以被肉眼或螢幕截圖發現。它透過在網頁中注入一個探針(probe),在每次繪製幀後讀取監控元素的邊界框(box)、有效不透明度(effective opacity)和滾動位置(scroll position),然後僅報告異常的變化。此工具會輸出事實性的報告(例如「在一幀內向下移動了 44px」),而非主觀判斷,能明確區分「缺陷」(如跳動、閃爍、推擠)和「無動畫的變化」(如無淡入效果的彈出),後者在某些情況下是可接受的。 antijank 支援三種執行模式:1) 直接注入到您正在使用的瀏覽器工具中(如 Chrome DevTools MCP 或 Playwright MCP),無需任何安裝;2) 透過其專用 Runner 在 CI/CD 環境中無頭執行,支援多種條件測試(如 CPU 降速、減少動畫效果);3) 透過 `antijank.record()` API 在您的 Playwright 腳本中程式化使用。它會產出一份結構化的報告,詳細列出多種缺陷類型(如 blip、jump、shift、pop-in、flash、flicker 等),並針對每種缺陷提供常見原因與修復建議。此外,它支援設定「預期行為」(Expectations),允許開發者定義元素應如何移動、停留或不透明度變化,從而將「看起來沒問題」的主觀判斷轉換為可重複的 pass/fail 測試,有效防止回歸錯誤。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/imomadjid/antijank/tree/main/skills/antijank

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 腳本,然後載入頁面並等待結果:
    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());
    
    其他工具:請使用 Runner (B),它預設會記錄頁面載入。

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.yamlpnpm add -D playwrightpnpm exec playwright install chromium
yarn.lockyarn add -D playwrightyarn playwright install chromium
bun.lock / bun.lockbbun add -d playwrightbunx playwright install chromium
deno.lockdeno add npm:playwright(需在 deno.json 中設定 "nodeModulesDir": "auto",以便 Node 能找到它)deno run -A npm:playwright install chromium
package-lock.json 或無 lockfilenpm i -D playwrightnpx 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() 則會立即結束記錄。

工作流程

  1. 決定要記錄什麼。 每次記錄一個互動:觸發動作、應該反應的頁面部份(root),以及什麼算是「完成」。如果變化需要等待網路請求,請傳入 waitFor 參數並帶上一個選擇器,該選擇器在內容到達後才會存在,否則記錄可能會在一切發生前就趨於穩定。
  2. 盡可能使用 production build。 Dev 建置會重播效果(React StrictMode)且熱重載會引入停頓,因此動畫可能與正式發行的版本不同。如果必須使用 dev 模式,請在報告中說明。
  3. 記錄並閱讀報告。 嚴重程度(Severity)是一個起點:HIGH 幾乎總是可見的,LOW 通常沒問題。
  4. 判斷哪些結果是有意為之的。 無動畫的變化會與缺陷分開列出。對於頁籤、選單、工具提示以及任何頻繁觸發或鍵盤驅動的元素,立即變更是合理的選擇,因此不要僅為了清除一個發現就加入動畫。透過預期(Expectation)來鎖定預期的行為,或在元素上標記 data-antijank-ignore。
  5. 為應該發生的行為撰寫預期(Expectations)(如下所述),並重新執行。這能將「看起來沒問題」的主觀判斷轉換為 pass/fail 測試,同樣的規格文件稍後也能用於防止回歸錯誤。
  6. 修復缺陷,然後重新執行。 作為最終檢查,請在正常速度、CPU 降速 4 倍以及開啟「減少動畫效果」模式下分別記錄(Runner 使用 --matrix,選項 A 使用模擬呼叫),因為時序錯誤(幀率低時動畫吃掉第一幀、延遲的 transform)通常只在 CPU 緩慢時才會出現。
  7. 用數據報告結果,例如「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 迴圈...

相關技能