antijank 是做什么的?
量化测量运动,而非肉眼观察。探针在页面中运行,每次绘制帧后读取每个被监视元素的边界框、有效不透明度和滚动位置,仅报告异常。每次交互只需几行文本,无需逐帧检查。
它报告事实(例如“一帧内向下移动 44px”),而非主观判断。判断持续时间或缓动函数是否合适属于另一项审查。缺陷(闪烁、跳跃、抖动、推动相邻元素)优先报告;单纯缺乏过渡的变化(弹出、替换)被单独列出,因为“瞬间”往往是正确的选择。
选择运行方式
<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 加载器获取此精确版本,完整性哈希使浏览器拒绝任何其他文件:
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 script blocked (Content-Security-Policy or offline)'));
document.head.append(s);
});
- 在同一页面上重复加载是安全的,但每次导航后都需要重新加载。
- 严格的内容安全策略(Content-Security-Policy)会阻止脚本标签,因此 CDN 加载器和
addScriptTag在这些页面上会失败。通过 DevTools(使用sourcePath的evaluate_script,或粘贴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,添加两个初始化脚本,然后加载页面并等待结果:
其他工具:使用运行器(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. 运行器:用于 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 # records the page load
运行器仅支持 Chromium,并在 Node 上运行,与项目使用的任何技术无关。如果项目没有 Playwright,运行器会告知。使用项目已有的包管理器(查看 lockfile)添加,然后下载 Chromium:
| 锁文件 | 添加 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 或无 | npm i -D playwright | npx playwright install chromium |
在向他人项目添加依赖前请先询问;选项 A 无需任何依赖。运行 node <skill-dir>/scripts/run.mjs --help 查看所有选项。运行器会为自己的浏览器关闭内容安全策略。
记录
当操作可以在页面内部运行时:
const result = await antijank.record(() => document.querySelector('#open').click(), { root: 'main' });
antijank.report(); // the text report
record 会等待操作的 Promise 完成后才让记录稳定,因此具有多个步骤的异步操作会被完整记录。
当您从页面外部驱动操作时(通过工具进行真实的点击和输入),保持记录开启直到完成:
antijank.start({ root: 'main', hold: true }); // 1. evaluate
// 2. click, type, wait: as many steps as the interaction needs
await antijank.release(); // 3. evaluate: settles after the last step, resolves with the result
antijank.report();
在点击元素前先悬停(DevTools MCP 的 hover,Playwright MCP 的 browser_hover),就像用户操作一样,并在第一次输入前至少一秒开始记录。直接跳转到元素上的点击会随按压开始其悬停效果,而自行更新的事物(时钟、实时计数器)需要那一秒被识别为已在变化;否则两者都可能被误认为是点击的响应。运行器在每次点击前都会悬停。
不使用 hold 时,记录会在没有任何移动约 330ms 后稳定,这可能会落在您的两个步骤之间。从未释放的 hold 会在 holdTimeout(默认 60s)后以错误结束。antijank.wait() 会在记录结束后解析结果;antijank.stop() 会立即结束它。
工作流程
- 决定要记录什么。 每次记录一个交互:触发器、应反应的页面部分(
root)以及“完成”的含义。如果变化等待网络请求,传入waitFor参数,使用一个在内容到达后才会存在的选择器,否则记录可能在事件发生前就稳定了。 - 尽可能使用生产构建。 开发构建会重放效应(React StrictMode),热重载会引入停滞,因此动效可能与发布版本不同。如果必须使用开发版本,请在报告时说明。
- 记录并阅读报告。 严重性是一个起点:HIGH 几乎总是可见,LOW 通常可以接受。
- 决定哪些发现是有意为之。 未动画的变化与缺陷分开列出。对于标签页、菜单、工具提示以及任何频繁或键盘驱动的元素,瞬间变化是有效的选择,不要为了清除发现而添加动画。使用期望(expectation)固定预期行为,或将元素标记为
data-antijank-ignore。 - 为预期行为编写期望(如下所示)并重新运行。这将“看起来不错”转换为通过/失败,并且相同的规范可以在以后防止回归。
- 修复缺陷,然后重新运行。 最终检查时,分别在正常速度、CPU 减速 4 倍和减少动效条件下记录(运行器使用
--matrix,或选项 A 中的模拟调用),因为时序错误(慢速第一帧吞掉动画、延迟变换)通常只在 CPU 慢时出现。 - 使用数字报告, 例如“composer 在 170ms 内从 245 移动到 562px,其他元素均未移动超过 1px,三种条件下均无发现”。
发现及其通常原因
| 发现 | 含义 | 通常原因和修复 |
|---|---|---|
blip | 在错误位置停留了 1–3 帧,然后弹回 | FLIP 变换延迟一帧应用(在绘制之后)。在同一帧内测量并设置逆变换作为布局变化:使用 layout effect,而非 effect 或 rAF |
jump (start) | 第一步很大,然后平滑移动 | 动画从错误原点开始,或第一帧在起始值设置之前绘制 |
jump (end) / snap | 平滑移动,然后在结尾处突然跳跃 | 错误的目标(过时的测量),或在布局匹配之前清除了变换 |
jump (mid) | 某一帧远大于其相邻帧 | 动画中途布局发生变化(内容到达),或两个动画交接 |
shift | 静止元素在一帧内移动 | 其上方有元素被插入、移除或调整大小且没有动画。[cause: …] 指定插入、移除或移动;[same frame: …] 指定同一帧内的调整大小,是可能的原因而非确证。对大小进行动画处理、预留空间或使用叠加 |
pop-in / pop-out | 以完全不透明度出现或消失(无动画) | 如果是有意的瞬间变化则正常。否则没有进入或退出动画,或进入过渡从未触发,因为起始样式从未渲染(在同一帧中添加了 class 又移除) |
flash | 仅可见 1–2 帧 | 占位符或陈旧状态渲染一帧;条件渲染反复切换 |
flicker | 不透明度下降后又恢复 | 重新挂载(key 变化)、状态重置或退出动画重新开始 |
swap | 一个元素被另一个元素原位替换,无交叉淡入(无动画) | 对于标签页和即时视图正常。否则缺少共享元素或英雄过渡 |
reversal | 在移动过程中部分转向 | 两个动画驱动同一个值,或重新定位到旧位置 |
oscillation | 方向逐帧翻转 | 两个脚本冲突(滚动锚定对抗跟踪、ResizeObserver 循环) |
resettle | 稳定后又再次移动 | 延迟测量(字体、图片、异步内容)后的修正 |
overshoot | 远远超过目标 | 弹簧回弹高于预期。如果是有意的弹跳则忽略它 |
stretch | 文本不均匀缩放 | 对包含文本的盒子进行缩放动画;对其子元素应用反向缩放或动画化大小 |
scroll-jump / scroll-fight | 滚动位置跳跃或改变方向 | 无平滑滚动的编程式滚动、滚动锚定或两个跟随者 |
slow-frame | 一帧耗时 50ms 或更多 | 动画期间的主线程工作(已命名脚本)。“Forced layout” 表示脚本在更改样式后立即读取布局(offsetHeight、getBoundingClientRect),通常在一个循环中:先全部读取,再全部写入 |
slow-response | 点击、回车、空格或 Escape 在 100ms 或更多时间内无反应 | 在工作或请求运行时没有按下或等待状态。立即显示一个。[cause: main thread busy …] 表示慢速处理程序阻止了响应的绘制 |
layout-anim | 对 width、height、top、margin 等进行动画 | 每帧触发布局。对于小手风琴可以接受;对于大型或频繁的动效,优先使用变换 |
动效发现会命名在那一帧正在移动元素的动画,或其祖先的动画:[animation: transition transform 300ms ease-out]、[animation: animation slide-in 400ms ease on div.panel] 或 [animation: Web Animation of opacity, transform 200ms linear]。首先转到该规则或调用。如果没有命名动画,通常意味着动效由脚本驱动(requestAnimationFrame、弹簧库)或根本没有动画。
期望
传入 expect(选项或 --expect)以获取通过/失败行,并在失败时退出码为 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:没有达到或高于该严重程度的发现,包括未动画的发现。- 运行器的
--fail-on <severity>在出现达到或高于该严重程度的缺陷时退出码为 1。未动画的变化不计入;应使用fadesIn或fadesOut要求淡入淡出。 - 任何匹配不到元素的选择器都会导致其期望失败,因此拼写错误不会静默通过。
保持报告有用
- 使用
root限定到应反应的区域。这样更快且更安静。仍然会监视在其外部添加的叠加层:直接添加到<body>的元素、固定定位元素,以及对话框、菜单、弹出窗口、工具提示和 toast(通过role、aria-modal、popover或<dialog>查找)。 - 一个尚不存在的
root会被等待。当它出现时其中包含的内容即为基线,因此要判断面板如何出现,请使用在其出现之前就已存在的 root(或省略)。 - 一次性插入(或移入,如流式 HTML)的子树会作为一个发现报告,包含子树名称及其包含的元素数量。
- 只有绘制某些内容(文本、背景、边框、阴影、背景滤镜、
::before/::after内容、图片、表单控件)的元素才能产生发现。透明包装器保持静默,因此它们绘制的子元素会进行报告。 - 无限 CSS 和 Web 动画(旋转器、闪烁)会被自动忽略。永不停歇的 JavaScript 循环会...
…(已截断用于翻译)