RomanFedytskyi/TickBenchCLI
GitHub: RomanFedytskyi/TickBenchCLI
在无头 Chromium 中对实时数据网格组件重放确定性市场数据流，逐帧测量延迟、丢帧、金额格式、XSS 和 WCAG 合规性的 CLI 基准测试工具。
Stars: 0 | Forks: 0
# TickBench
[](https://github.com/RomanFedytskyi/TickBench/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/tick-bench-cli)
[](https://www.npmjs.com/package/tick-bench-cli)
[](https://bundlephobia.com/package/tick-bench-cli)
[](https://www.npmjs.com/package/tick-bench-cli)
[](https://www.npmjs.com/package/tick-bench-cli)
[](#benchmark-your-own-component)
[](LICENSE)
[](docs/task-authoring.md)
[](https://doi.org/10.5281/zenodo.21272054)
[](https://github.com/RomanFedytskyi/TickBench)
TickBench 会在无头（headless）Chromium 浏览器中，针对你的数据网格或仪表盘组件重放**已设置种子且可重现的市场数据 tick 流（market-data tick streams）**，并告诉你用户实际会看到什么：
**显示延迟（display staleness）**、更新延迟百分位（update latency percentiles）、丢帧（dropped frames）、更新丢失（lost updates）、损坏的金额格式、实时的 XSS 注入点以及 WCAG 违规情况——只需一条命令、一份 JSON 报告、一个通过/失败结论。
## 这是什么？
**TickBench 就像是 Lighthouse，不过它是专为实时数据表格设计的。** Lighthouse 会加载你的页面并进行评分。对于一种特定且高风险的 UI——即显示快速变化数字（价格、头寸、风险、指标）的表格，TickBench 走得更远，它会在每秒流入数千次更新的情况下，评估用户实际看到的效果。
你的单元测试检查的是逻辑。你的视觉测试检查的是静止状态下的像素。**如今你所运行的任何测试，都无法检查此时屏幕上的数字是否正是 400 毫秒前到达的数字**——也无法检查你的表格是否在默默丢弃更新、卡顿、格式化金额出错、执行了恶意字符串，亦或在负载下丧失了其无障碍（accessible）结构。TickBench 正是为此而生，它在一个真实的（无头）Chrome 中进行检查，并为每个实现提供一个 PASS/FAIL（通过/失败）的结论。
**在以下情况使用它：**
- 构建任何带有实时数字的仪表盘——交易、加密货币、风险、车队、分析、后台管理；
- 正在选择表格/网格（grid）库，且不想轻信供应商的营销基准测试时；
- 让 AI 编程工具编写前端代码，且在合并前需要一个客观的检验关卡时；
- 想要一个 CI 检查来证明重构没有导致表格变慢或出现错误时。
## 工作原理（60 秒读懂）
**步骤 1 —— 你编写一个小文件**（一个 adapter）。重点：你的应用永远不会导入 TickBench，而且 `applyTick` 也不是从任何地方导入的——**由你来定义它，而 TickBench 负责调用它**。TickBench 会导入*你的*文件，调用你的 `createGrid` 挂载表格一次，然后一边以每秒数以千计的速度调用你的 `applyTick` 模拟市场更新，一边逐帧录制最终结果。
```
// my-adapter.mjs — the whole contract
export function createGrid(container, symbols, cols) {
// mount YOUR table into `container` (any framework; relative imports work)
// each rendered cell needs data-sym / data-col attributes so TickBench can watch it
return {
applyTick(tick) {
// TickBench calls this with { sym, col, v } for every update.
// Route it into your table the same way your app would (setState, setCell, ...).
}
};
}
```
**步骤 2 —— 从你的项目文件夹中运行它**：
```
npx tick-bench-cli bench --impl ./my-adapter.mjs --name my-table
```
**步骤 3 —— 查看结论。** 每次运行都会输出三种结果：控制台表格、一个适配浏览器的 **HTML 报告**（`./tickbench-results/report-stream-grid.html`），以及用于 CI 的 JSON：
包含真实组件文件的完整可运行示例：[`examples/walkthrough/`](examples/walkthrough/)。
框架指南（React, AG Grid）：[`docs/connect-your-table.md`](docs/connect-your-table.md)。
## 如何测试实时数据网格？
如果你曾搜索过*如何测试实时数据网格*、*测量显示延迟*、*React 表格流式更新基准测试*、*虚拟化网格丢弃更新*、*验证 AI 生成的前端代码*，或者*我的仪表盘在负载下显示过时价格*——那么这就是为你量身定制的工具。
## 为什么会有这个工具
每一个交易、风险、借贷和分析类的 UI 都是一个由数据流驱动的网格。在突发负载下，各种实现都会以现有工具无法测量的方式发生失败：
- DOM 显示了一个**不再真实的 price**（延迟）；
- **最新**的更新被默默地从未渲染（更新丢失）；
- 主线程停滞了数百毫秒（帧稳定性）；
- `1234567.5` 美分变成了 `12345.68` 而不是 `12,345.68`（金额格式化）；
- 插值的符号名变成了一个 **XSS payload**；
- 网格丧失了其无障碍结构（WCAG）。
网格供应商会发布营销性质的基准测试；js-framework-benchmark 测试的是静态行。TickBench 测试的是**你的实现，在你的工作负载下，并依照可执行的验收标准**——这甚至包括在你让 AI 编程代理接触生产环境之前，对其编写的代码进行测试。
## 快速开始（本仓库）
```
git clone https://github.com/RomanFedytskyi/TickBench.git && cd TickBench
npm ci
npx playwright-core install chromium-headless-shell # one-time browser download
npm test # unit tests
npm run validate # oracle validation: reference passes, mutants are caught
npm run bench # score all bundled submissions for tasks/stream-grid
```
```
reference claude-fable-5 naive-baseline
catch-up latency p50 (ms) 24.3 24.1 8.1
catch-up latency p95 (ms) 31.8 32.1 37.3
stale cell-frames (%) 17.41 17.44 0
long frames >33ms (%) 0 0.2 2.49
worst frame (ms) 16.8 49.9 516.7
final format errors 0 0 157
XSS triggered (dynamic) false false true
security findings (high) 0 0 1
axe violations 0 0 1
REGULATED-GRADE PASS true true false
```
本仓库内置了三个提交版本：一个人工**参考实现**，一个纯粹由 AI 单次生成的**提交版本**（`claude-fable-5`，附有来源文档说明，为未经编辑的模型输出），以及一个手写的、用于验证预言机的**朴素基准（naive-baseline）**。请注意这些数字所暴露的权衡：未进行批量处理的基准在中位数上*绘制得更快*，但在最坏情况下会卡顿半秒钟——而使用 rAF 批处理的实现则以单帧的延迟换取了稳定性。这个边界效应在你进行测量之前是无法察觉的。
## 测量内容
正式定义位于 [`docs/metrics.md`](docs/metrics.md)：
| 维度 | Oracle | 指标 |
|---|---|---|
| 更新正确性 | runtime, 帧采样 | 显示延迟、追平延迟 p50/p95/p99、丢失更新 |
| 渲染性能 | runtime | 长帧率、最差帧 |
| 金额显示 | 终态扫描 | 数值错误、区域设置/格式错误 |
| 安全性 | 静态 sink 扫描 + 动态金丝雀检测 | 注入发现、XSS 执行 |
| 无障碍 | axe-core | WCAG 2.1 A/AA 违规 |
阈值是每个任务 `oracle.config.json` 的一部分——验收标准是版本化的数据，而不是测试框架的代码。每一个关卡都经过了验证：内置的 `naive-baseline` 提交版本是一个故意写错的实现，`tickbench validate` 证明了每个 oracle 都能捕获它。
## 真实工作负载
合成 trace 是设置了种子且具备确定性的（`tickbench gen --seed …`）。你也可以将真实的 feed（例如公共交易所的 WebSocket 流，或你自己的生产环境 feed）录制到相同的 schema 中——只需设置 `"synthetic": false` 并附带一份来源说明文件。请参阅 [`docs/task-authoring.md`](docs/task-authoring.md)。
## CLI
```
tick-bench-cli bench --impl ./my-adapter.mjs [--name LABEL] benchmark YOUR component (any directory)
tick-bench-cli bench [--task DIR] [--submission NAME] benchmark a task's reference + submissions
tick-bench-cli gen [--seed N] [--duration MS] [--symbols N] [--out FILE]
tick-bench-cli validate [--task DIR]
tick-bench-cli new-submission
[--task DIR] scaffold a submission for model output
```
常用选项：`--trace FILE`（自定义工作负载），`--out DIR`（默认为 `./tickbench-results`），`--no-reference`（跳过内置的比较基准）。
## 引用
如果 TickBench 对你的工作有所帮助，请通过 [`CITATION.cff`](CITATION.cff) 引用它。
## License
代码：MIT © 2026 Roman Fedytskyi。内置及录制的 trace 数据（`traces/`）：CC BY 4.0。标签：MITM代理, Web可访问性, 前端性能测试, 数据表格, 文档结构分析, 无头浏览器, 暗色界面, 特征检测, 自定义脚本