测试与质量门禁
框架无关的组件库最常见的问题是各适配器逐渐偏离。行为写在同一个内核中不代表各端表现一致：写入属性的时机、事件的派发形态、焦点的落点都可能不同。
XiHan.UI 的测试体系首先针对这一点。
三套判据
| 入口 | 回答的问题 | 运行环境 |
|---|---|---|
@xihan-ui/testing | 适配器的实现是否符合规格 | jsdom |
@xihan-ui/testing/a11y | 渲染结果是否存在无障碍违规 | 真实 Chromium |
@xihan-ui/testing/position | 浮层最终是否落在屏幕上正确的位置 | 真实 Chromium |
后两套必须在真实浏览器中运行：jsdom 没有布局，无法验证对比度、目标尺寸、翻面与避让。
pnpm test # 第一套
pnpm test:browser # 后两套（先 pnpm exec playwright install chromium）在 Windows / macOS 宿主上，pnpm test:browser 固定有一条失败：像素基线文件受字体守卫拦截，整文件判失败、40 条用例全部 skipped。这是预期结果，不是环境故障；本地验证像素改动的方式见下文「像素基线」。
按分类运行浏览器态
pnpm test:browser 由 ui/tooling/scripts/test-browser.mjs 执行：先构建各包的依赖，再逐包串行运行（Vue → React → Web Components → 其余），每个包的 worker 数缺省为 min(8, 核数 - 1)。每个包各起一套 Chromium，同时运行多个包会在多核机器上拉起上百个页面，占满内存与 CPU。
pnpm test:browser # 全部包、全部用例
pnpm test:browser form overlay # 只跑这几类（跨包）
pnpm test:browser --list # 各分类在每个包里的用例数
pnpm test:browser --pkg=vue,react # 只跑点名的包
pnpm test:browser --workers=4 # 调整每个包的 worker 数
pnpm test:browser --no-build # 跳过依赖构建
pnpm test:browser overlay -- -t Esc # -- 之后的参数原样交给 vitest分类与组件总览一致（ui/scripts/component-docs.manifest.json）：general、layout、navigation、form、data-display、feedback、overlay、ai。用例文件名以某个组件名开头（取最长匹配）即归入该组件的分类；浮层主题的跨组件用例（overlay-*、各类 Portal、position 引擎）归 overlay；其余跨组件用例（全量无障碍、计算样式快照、像素基线、焦点环对账等）归 shared。某个包失败不中断其余包，全部跑完后汇总。
Vue 浏览器态的三个项目
同一个 worker 里的用例文件共用一张页面，仿真状态会从上一个文件带到下一个文件。vitest.browser.config.ts 因此把 Vue 浏览器态分成三个项目，按 sequence.groupOrder 先后运行：
| 项目 | 收哪些文件 | 为什么单独放 |
|---|---|---|
vue-browser | 其余全部 | 并行主池 |
vue-browser-touch | 调用过 Emulation.setTouchEmulationEnabled 或 coarsePointer() 的文件，配置加载时自动扫出 | Linux 无头 Chromium 上，一张页面只要关过一次触屏仿真，(pointer) 与 (hover) 就永久变为 none，没有 CDP 入口改回来。挂在 @media (hover: hover) 下的悬停规则随之失效，同一 worker 里后续文件的悬停断言与像素基线会随机判红。Windows 上不走这条恢复路径，本机复现不出来 |
vue-browser-serial | overlay-open-budget.spec.ts | 量主线程耗时，与整套并行时量到的是别的用例抢走的 CPU，放到最后单独串行 |
媒介仿真（print、forced-colors 等）由 tests/browser/setup.ts 在每个文件开跑前复位；触屏仿真不能这样复位，复位本身就会让页面失去悬停能力。
一致性：一份规格驱动各适配器
规格（ConformanceSuite）声明组件的解剖部件、键盘表与用例；适配器各实现一个 AdapterHarness（挂载 fixture 树、获取事件、卸载）。运行器把同一份规格交给不同的 harness，逐帧采集归一化后的 DomSnapshot 并断言。
fixture 是框架无关的树：
interface FixtureNode {
part?: string; // 解剖 part 名，与 data-part 逐字相同
tag?: string;
text?: string;
attrs?: Record<string, string>; // 业务属性，不含 aria- / data-scope / data-part
children?: FixtureNode[];
}快照也是归一化的：
interface DomSnapshot {
parts: Record<string, PartSnapshot[]>; // part 名 → 全部实例（文档序）
order: string[]; // 文档序，集合项带下标：['trigger', 'content', 'item[0]']
activeElement: ActiveElementRef | null; // 焦点落在哪个 part、是否恰为该元素本身
events: AdapterEvent[]; // 自上一帧起适配器对外派发的事件
strayParts: string[]; // 带 data-scope 却不属于任何声明 part 的元素
}五条契约不变量
这套判据依赖五条约束：
- 规格零框架：套件只从
@xihan-ui/core/@xihan-ui/headless取纯数据（解剖、键盘表、类型），不 import 任何框架； - 只断言归一化快照：断言对象只能是
DomSnapshot，不接触组件实例、内部 ref、shadowRoot； - 快照适配器无关：id 的具体值、
data-v-*等适配器痕迹在采集阶段抹除，IDREF 属性翻译为@part(...)。无法抹除的差异即抽象泄漏； - 单实例文档：同一时刻文档内只有一个 harness 的一个挂载实例，卸载后该 scope 不得残留节点；
- 状态断言归纯逻辑层：harness 不暴露当前状态机状态，
settle只等待可观察的 DOM 事实。
第 3 条是关键：适配器之间的差异无法在归一化中抹除，说明抽象存在泄漏，应修改的是库而不是测试。
分母外化
键盘规格表是可达性的分母。用例通过 covers 字段反查行 id，缺一行即套件失败。
键盘测试只能通过补充用例通过，不能修改分母。
无障碍
把一致性套件的 fixture 挂载到真实 Chromium，对初始态与各用例终态运行 axe，终态按形态签名去重。
存量违规登记在 tooling/testing/src/a11y/known.ts：命中已登记的规则不判失败，但一条都不再命中时判定登记过期：修复后必须从表中删除，不保留已不成立的豁免。当前登记的清单见无障碍与键盘规格。
浮层定位
runPositionEngine(engine, hooks, name) 是一份引擎无关的契约：判据只认浮层最终出现在屏幕的位置，两个矩形都取视口坐标，因此不关心包含块关系与中间的 transform 层数。更换定位引擎实现后同样适用。
覆盖：十二种 placement 的贴边与对齐、offset、翻面与交叉轴避让（各配一条关闭后应当溢出的对照）、虚拟锚点、缩放与 transform 容器、文档滚动、容器滚动跟随、裁剪后的 hidden、尺寸变化重算、静置不空转、停止跟随后不再回调。
像素基线
计算样式不一致会被令牌快照拦截，结构错位会被一致性套件拦截，但值全部正确、外观仍然不同这一档没有其他判据覆盖：层叠顺序、私有槽的覆盖时机、两条规则的先后，只在最终位图上显现。像素基线负责这一档。
受管范围是母组件 button / text-field / select / menu / popover / dialog / drawer / toast，每件在五组轴上各出一张：light×comfortable、dark×comfortable、light×compact、dark×compact、dark×more。前四格是主题与密度的笛卡尔积；第五格是层叠最脆弱的一格：两块 contrast 取值块必须排在两个 mode 块之后，顺序错误即静默回归。motion=reduce 不在其中：静止帧与默认档没有差别，该轴由令牌快照与 check-infinite-motion 承担。
基线文件在 packages/adapters/vue/tests/browser/__screenshots__/ 下，具体数量以该目录为准。
必须在容器中生成的原因
基线比对的是逐像素的位图。字体、字形栅格化与子像素平滑在 Windows 与 Linux 上不同，同一份 CSS 在两边渲染出的位图不同：在开发机上生成的基线，CI 上无法匹配。
字体是最大的不确定性：全库皮肤写的是 font-family: inherit，没有 sans 字体令牌，字体最终取文档根上的值。截图用例因此把根上的字体族按名字固定为 DejaVu Sans，不交给环境默认的 sans-serif 解析。因此基线的成立条件不止 Linux，还包括 DejaVu Sans 这个名字可以解析到，即安装了 fonts-dejavu-core：CI 的 browser job 中有一步专门安装它，删除该步骤基线会整体判红。
反过来，环境中多安装字体不影响基线：字体族按名字确定，默认 sans-serif 落到 Noto Sans 或其他字体，画面不变。核对字体时核对的是这个名字（fc-match 'DejaVu Sans'），不是默认 sans-serif。
pnpm visual:baseline # 校验：与库里的基线逐像素比对
pnpm visual:baseline --update # 生成 / 更新基线并写回库里两条都在 mcr.microsoft.com/playwright:v1.62.0-noble 中运行，与 CI 使用同一套渲染栈。首次运行前先 docker pull 该镜像；镜像版本必须与 pnpm-workspace.yaml 中 playwright 的版本一致，浏览器二进制才配套。
运行器把仓库同步到容器内的工作副本再安装依赖，不使用宿主的 node_modules：宿主安装的是 win32-x64 原生二进制，容器内无法运行，而在容器内安装会覆盖宿主的副本。pnpm store 与工作副本都落在一个命名卷上，重复运行不重复安装。
校验模式下基线目录不挂载进容器，容器无法写入。修改基线只能显式使用 --update。
比对失败时，实际截图与差异图输出到 packages/adapters/vue/.vitest-attachments/（不入库）。CI 上同一批文件作为 visual-diffs artifact 输出，可下载逐张查看。
本地运行方式与固定失败项
pnpm visual:baseline 是本地唯一有效的入口，不使用宿主的渲染栈：源码同步进容器、依赖在容器内安装、用例在容器内运行，因此 Windows 与 macOS 上的结果与 CI 逐像素一致。前置条件只有 docker pull。
直接运行 pnpm test:browser 时，像素基线文件整文件判红：字体守卫在 beforeAll 中抛错，40 条用例全部 skipped，不生成任何位图，也不会在 __screenshots__/ 下留下带 -win32 后缀的文件。在宿主上安装 DejaVu 无法解决：字体只是差异之一，字形栅格化与子像素平滑仍与 Linux 不同，比对结果没有意义。这条失败是预期结果，同一批浏览器态用例中的无障碍与浮层定位在宿主上照常通过。
修改皮肤的工作方式：
- 本地
pnpm visual:baseline查看本次改动影响的截图，差异图在.vitest-attachments/下逐张打开； - PR 的判据是 CI 的
browserjob，本地pnpm test:browser的固定失败项可以忽略； - CI 失败时先下载
visual-diffsartifact 查看，确认是有意的视觉改动，再pnpm visual:baseline --update重新生成基线并提交。
字体族名、安装它的 apt 包、容器镜像与运行命令分散在用例、容器脚本、CI 与本页中，任何一处不一致都只表现为四十张整体判红。check-visual-baseline-env 把四处对齐，并核对镜像版本与 pnpm-workspace.yaml 中 playwright 的版本一致、CI 的 browser job 中安装字体的步骤排在运行用例之前。
基线变更必须经人工审阅
基线的更新是无声的：git diff 只显示二进制文件变化，看不出变成了什么。任何人都可以 --update，把一次真实的视觉回归记录为新基线。
因此规则是：PR 中凡有 __screenshots__/ 下的改动，作者必须逐张说明变更原因，审阅者必须打开图片查看。改动张数与改动理由不一致的 PR 不合并。
基线文件名带浏览器与平台后缀（…-chromium-linux.png），入库的只有 linux 一套。带其他平台后缀的文件不应出现（字体守卫会在生成之前拦截用例），出现时直接删除，不提交。
视觉样板性能预算
pnpm visual:performance 在与像素基线相同的 Playwright Linux 镜像中运行真实 Chromium，并把报告写到 ui/packages/adapters/vue/.vitest-attachments/visual-performance.json。这条用例不另建展示页：它直接复用 visual-baseline.spec.ts 的 Dialog variant="blur" 夹具与 800×520 视口，在对话框后方逐帧移动固定渐变背景， 让 backdrop-filter 参与真实合成。默认透明与 data-transparency="reduce" 交替采样，避免先后顺序把机器热态集中到某一档。
设备档固定为 mcr.microsoft.com/playwright:v1.62.0-noble、Chromium、800×520@1x、2 CPU、2 GiB， 并通过 CDP 对渲染进程施加 4× CPU throttle。每档先预热 30 帧，再采 120 帧，重复三轮。预算真源是 tooling/scripts/visual-performance-budget.json；容器镜像版本继续与 pnpm-workspace.yaml 的 Playwright catalog 对齐。
报告与门禁包含：
requestAnimationFrame相邻回调的 p50 / p95 / 最大间隔；每帧都会改变背景绘制位置，这个间隔包含该帧排队、样式、绘制与合成对下一帧的影响，不把纯 JS 计时冒充 GPU 时间；- W3C Long Tasks
PerformanceObserver给出的长任务数量、最大值与合计时长； - 每个可见且计算样式含
blur(...)的backdrop-filter元素，在视口内裁切后的面积之和。重叠材质逐层计数，因为每一层都要独立取样；reduce档必须严格为 0； - 10 次交替挂载/卸载后，强制 GC 前后的 CDP
Memory.getDOMCounters差值，作为 documents / DOM nodes / JS listeners 的资源留存代理。
这里不输出伪内存数。浏览器目前没有稳定的标准轨页面内存 API；候选 measureUserAgentSpecificMemory() 仍是 WICG 草案，且要求跨源隔离。测试页不为获取一个数字而伪造隔离条件， 报告如实记录候选 API 与 crossOriginIsolated 状态，并用上述 DOM 资源留存代理监测泄漏。长任务定义见 W3C Long Tasks，内存候选 API 的标准状态见 WICG Measure Memory。
第一次建立或有意重定预算时，必须先运行：
pnpm visual:performance --record--record 只写真实报告、不判断 limits。至少检查一份完整报告后，才按实测值与明确余量修改预算真源；常规 pnpm visual:performance 执行红线。CI 运行后者。像素基线仍由 pnpm visual:baseline 守护，本项不自动更新任何 PNG。
包体积不在性能 JSON 里复制数字：JavaScript / 发布产物继续由 .size-limit.json 与 pnpm size 守护，逐皮肤 CSS 继续由 .size-limit.css.json 与 check-skin-size 守护。性能预算门禁反查这两份真源；修改本项不得提高既有阈值。
结构门禁
结构检查按职责分成十个模块，脚本放在 ui/tooling/scripts/<模块>/ 下，执行顺序由 ui/tooling/scripts/gate.modules.mjs 决定。每一步都是独立子进程，串行执行：
pnpm gate # 全部模块，遇到第一处失败即停（CI 运行这一条）
pnpm gate overlay motion # 只跑点名的模块
pnpm gate --list # 列出模块、中文名与步数
pnpm gate --keep-going # 失败不停，跑完汇总失败的步骤；可与模块名同用| 模块 | 管什么 |
|---|---|
package | 运行时依赖、版本锁步、包清单与角色、子路径导出、发布产物 |
tokens | 令牌产物、令牌引用、字面量与兜底、语气层、层序与层号 |
skin | 皮肤入口与标记、解剖对齐、收起态、视觉轴、打印 / 高对比 / 安全区等环境档 |
visual | 形状、间距、描边、字号、海拔、交互阶梯、控件与面板尺寸、字形、家族配方与按压反馈 |
overlay | 浮层坐标系、可用空间、定位层、遮罩、箭头、落点与自绘滚动条 |
motion | 关键帧、时长与缓动、幅度、减弱动效、动效覆盖面 |
a11y | 聚焦环、焦点复位与上报、ARIA 写法、按键重复与键盘套件 |
adapter | 部件接线、状态与部件词汇、插槽与翻译、全局配置、三端计算样式一致、组件落点 |
docs | 示例的多框架对齐、令牌与动效、文档数字与导入、组件总览 |
repo | changeset、提交 scope、发版标签、PR 模板、类型检查覆盖面、文件头、脚本接线 |
改了哪一块先跑对应模块，提交前再跑一次全量。
pnpm gate 运行 128 项结构检查，它们检查的是判据无法覆盖的问题：静默失效、悬空承诺、未被命名的决策：
| 门禁 | 拦截内容 |
|---|---|
check-runtime-deps | 库包的运行时依赖引入了未登记的第三方 |
check-exact-pins | 库包依赖内联了版本号（只允许 catalog: / workspace:） |
check-tokens-dist | 令牌产物未入库 |
check-overlay-strategy | 浮层坐标系在机器 / connect / 皮肤三处不一致 |
check-token-refs | 皮肤引用了不存在的令牌名（整条声明会静默失效） |
check-tone-tokens | 语气轴对外的 --xh-tone-* 没声明在语气层的 [data-tone] 上，或与私有槽的取值分叉 |
check-chart-palette | 图表数据色在亮色或暗色下不过色板检查：分类色的明度带、对比度、相邻与任意两色的色差、色觉障碍分离、色相分散与离开告警色，以及有序、顺序、发散、涨跌色阶的结构 |
check-shared-slots | 同一字面量在多个组件中作为默认值，却未建立语义令牌 |
check-motion-easing | 皮肤的缓动下探到 --xh-ease-* 原语、手写 cubic-bezier()，或使用了未登记的字面曲线 |
check-motion-amplitude | 位移与缩放的幅度写成字面量（减弱动效档把 --xh-motion-distance-* 压成 0px、--xh-motion-scale-* 压成 1，写死的位置无法压缩）；居中用的百分比与 0 / 1 是几何，不在此列 |
check-disabled-contrast | 禁用态前景色令牌上叠加 opacity，对比度被压到无法阅读 |
check-color-literals | 颜色写死在 background 简写、box-shadow 颜色位或 --xh-* 槽赋值中：stylelint 的六个长属性白名单不覆盖这些位置 |
check-print-surface | 浮层定位层 / 遮罩 / 滚动条 / 固定在视口上的节点在打印时未收起，或投影未由令牌层取消 |
check-placeholder-fg | 占位文字两条通道（::placeholder 与 [data-placeholder]）取了不同的默认前景，或用 opacity 表达深浅 |
check-autofill | 渲染原生表单控件的输入框未写自动填充规则，或两种手段 / 两个引擎的选择器缺一 |
check-part-wiring | 解剖声明、connect 产出、适配器却未接线的部件 |
check-dead-state-attr | connect 发出的 data-* 在本组件的作用域中没有任何规则消费：其他组件的同名规则不计入，该规则永远无法选中它。信息钩子逐条登记，登记项过期同样判失败 |
check-skin-parts | 皮肤选择器中的 [data-part] 不在所属 scope 的解剖中：部件退役后遗留的规则永远无法选中节点，surface:update 还会把它的覆盖槽收回公开面。scope 按选择器计算（逐分支、逐复合：写在 [data-part] 前后的 [data-scope] 都约束这一节，未写的沿用左侧最近一节，:is() / :where() 中一致的 scope 带回外层，:not() / :has() 中各自计算），解剖外的名字逐条登记，登记项过期同样判失败；data-scope / data-part 的属性选择器无法读取的（转义、匹配符不是全等）同样判失败 |
check-breakpoints | 皮肤 @media 中的断点字面量不在令牌清单中（自定义属性在媒体条件中不生效，只能写字面量）；查询用了 max-width / max-height 上界写法：它在断点值上与 min-width 同时成立，窄档专属规则写补集 not all and (min-width: …) |
check-focus-ring | 聚焦环的粗细、颜色、偏移写了字面量而不是令牌，主题与全局调整对它无效 |
check-focus-ring-surface | 可聚焦部件的面与环的对比度不足 3:1（按计算结果，不按形态推断），该档却未把 --xh-_ring-color 设为 currentColor：键盘焦点在该面上等于未绘制。currentColor 覆盖到非实心档、:focus-visible 中关闭环（outline: none / outline-width: 0）却未登记环由谁绘制、绘制实心面却不接焦点也未登记的部件，同样判红；聚焦规则把环色写成透明的直接判红，没有登记表 |
check-focus-outline-reset | 皮肤在 :focus:not(:focus-visible) 下复位 outline（含 outline-style / outline-width / outline-color）。UA 只在 :focus-visible 绘制环，这条复位是死代码，而 outline 简写会把 outline-color 复位成 currentColor，描边色一旦进过渡，焦点离开时就闪出一圈近黑描边 |
check-exports | 已实现却未从包级入口导出，包外无法获取，而构建与类型检查照常通过 |
check-package-roles | 包所在的角色组与其 package.json 中的依赖声明不一致 |
check-public-surface | 公开面基线中有而当前没有的名字：被删除或改名 |
check-visual-performance-budget | 固定设备、默认/reduce 场景、真实浏览器入口与既有 JS/CSS 体积真源任一脱节 |
check-material-scope | liquid 落在没登记的部件上：连接层投影 data-xh-liquid 的部件、皮肤里与 [data-xh-liquid] 写在同一个复合选择器上的部件，都必须是登记过的导航层（浮动钮、媒体控制、悬浮栏），每条写明它浮在什么之上；过期的登记同样判失败 |
check-changeset-packages | changeset 头部写了 .changeset/config.json ignore 表里的私有包（如 @xihan-ui/testing）或不在工作区的包：前者与发布包混写时 changeset version 直接报 Mixed changesets，只写它时整份被丢掉、正文进不了 CHANGELOG；后者报 not in the workspace。不依赖 git 基线，头部读不成「包名: 档位」也判红 |
check-surface-edge / check-selection-marker / check-state-ladder / check-text-role 与扩展后的 check-elevation-role / check-shape-scale / check-press-feedback / check-family-parity | 七条家族门禁：根面边界三选一、选中与当前态按语义分类、交互态按承载面阶梯、排版与图标按角色、raised 逐部件登记且必带描边、形状身份表、按压几何与换底、同族同值。尚未迁移的存量登在 tooling/scripts/family-backlog.json，每条必须真被放行过一次（登记了却没命中判过期），check-family-backlog（gate:family 里的 family-backlog.spec.mjs）把每段条目数钉在快照与 CEILING 上、键集合只许是快照的子集——表只减不增 |
另有分层依赖检查与十二项单独的门禁：
pnpm boundaries # 分层依赖 + 禁循环 + styles 不依赖 JS + 库包不引入第三方
pnpm gate:tokens # 重新运行令牌生成后比对，修改源文件未运行生成会被拦截
pnpm gate:styled # 重新生成皮肤的无层版产物后比对
pnpm gate:cem # 重新生成自定义元素清单后比对
pnpm gate:docs # 重新生成组件文档页后比对
pnpm gate:exports # 重新生成子路径导出后比对 package.json
pnpm gate:surface # 公开面基线：基线中有而当前没有的名字判失败
pnpm gate:demos # 在真实 Chromium 中运行文档站的自定义元素示例
pnpm gate:demo-types # 文档站 React 示例逐份类型检查（读 icons 的 dist，先 build）
pnpm gate:publish # 逐包运行 publint 与 attw，校验 exports 条件与类型解析
pnpm gate:llms # 文档站的机读资产：页数、组件数、令牌数与库对账，示例不得保留站点标签
pnpm gate:family # 逐家族豁免表只减不增（条目数快照 + 键集合子集），并用临时夹具证七条家族门禁会红gate:llms 读取文档站的构建产物，运行前先在 docs/ 下运行一次 pnpm build。
文档站是独立工作区，lint 也独立，在 docs/ 下运行 pnpm lint。示例语料的引号与分号与库源码相反，规则固定在 docs/eslint.config.js 中：示例供使用者复制，不跟随库源码的写法。
gate:publish 按包声明的支持面校验：ESM-only、engines.node >= 18，不提供 CJS，也不承诺 node10 的旧式解析。
体积棘轮
pnpm size40 条产物各有上限（gzip 后），超出即失败。预算一律按实测留一成余量。逐条限额的真源是 ui/.size-limit.json，具体数字以该文件为准。