| name | frontend-testing |
| description | 单前端闭环测试执行器（stack-agnostic / project-agnostic）。当一个前端 feature 收尾、需要补 superpowers/spec-kit 开发期覆盖不了的前端结构性测试缺口时使用：先读项目栈（package.json 或 等价清单）按栈实例化对应成熟工具，再针对实际命中的层 RED→GREEN 补测并固化为回归。与 backend-testing 的根本区别——后端缺口无现成工具需自建（"施工队"），前端成熟工具齐全，本 skill 不重新发明工具，只做 三件事：装 + 配 + 把项目的视觉/交互契约翻译成这些工具能跑的断言/规则（"装配工 + 监理"）。覆盖五层 前端结构性缺口——编译期 lint 门、L0/L1 单测（含 getComputedStyle 断言 token/深色/涨跌色）、a11y + 跨浏览器/响应式、前后端契约 mock、视觉回归。触发词：单前端测试 / 前端缺口补测 / frontend testing / 视觉回归 / a11y 测试 / 跨浏览器测试 / 响应式测试 / token 断言 / 前后端契约 mock / 前端回归补测。 常见地基为零：很多前端 [FE] 任务出参验证只写"手测"、测试运行器/RTL/Playwright 可能完全没装—— 本 skill 第一动作是"识栈→若无测试运行器先立地基"，不假设 L0/L1 已就绪。遵循 testing-system-blueprint 蓝本（风险分级 / 可追溯 / 发布门 / 三层节奏），受自愈护栏约束（只写测试不改产品码、断言不可弱化、禁伪造 修复、有界重试、产 PR 人审）。被 test-routing-advisor 在判定"单前端"时调用，也可直接触发。 |
frontend-testing · 单前端闭环测试执行器
这个 skill 解决什么
开发期 TDD（superpowers）和 spec/契约测试（spec-kit）覆盖的是"功能逻辑是否如规约工作"。
但前端有一类结构性缺口，它们不属于单个功能点、而属于界面在真实浏览器里的运行时性质——
视觉契约是否真的落到了像素（颜色/字号/间距是否走 token、深色是否覆盖、涨跌色是否符合目标市场惯例）、
可访问性是否达标、跨浏览器/多视口下布局是否不破、与后端的数据契约是否对得上、UI 改动有没有
悄悄造成视觉回归。这些缺口在开发期几乎不会被自然写到——尤其当 [FE] 任务的"出参验证"只写了
**"手测"**两个字时。
核心区别于 backend-testing（务必读懂）：后端那一类缺口（真库越权/并发/韧性）没有 pip/npm
即装即用的工具，backend-testing 是"施工队"——大量测试代码要自己写。
前端不是这样：每一层都有成熟、广泛采用的工具（lint 器、单测运行器 + Testing Library、
axe、Playwright、MSW、Chromatic…）。所以本 skill 不重新发明工具，它是"装配工 + 监理"——
只做三件事：装（把该栈对应的成熟工具装进项目）+ 配（接好配置/CI）+ 翻译（把
这个项目的视觉/交互契约，翻成这些工具能机械执行的断言与规则）。
skill 自己加的价值：通用工具 ↔ 项目视觉契约 的翻译 + 编排 + 闭环
成熟工具是通用的，但它们不懂你的项目：
- stylelint 能禁裸色值，但不知道你的 token 叫什么、值是多少、哪个属性必须走
var()。
- axe 能扫 a11y，但不知道哪些页面该跑、红了算不算发布门拦截、对比度阈值按哪套设计走。
- Playwright 能截图、能开多视口，但不知道你的"无横向滚动条"是硬约束、不知道你的涨跌色约定
（某些市场红涨绿跌、某些市场红跌绿涨——工具无从知晓哪种是"对"）。
- MSW 能 mock 后端，但不知道你的后端契约长什么样、字段改了它不会自己跟着改。
本 skill 干的，正是在通用工具 ↔ 项目视觉/交互契约/design token 之间做翻译 + 编排 + 闭环：
把"项目认可的成品长这样"翻成机器能反复跑的断言/规则，接进 CI，固化为回归。这是工具本身永远
不会替你做的部分，也是本 skill 的全部价值所在。
遵循 testing-system-blueprint 蓝本（按名引用即可）：风险分级排序、可追溯 ID、发布门、三层节奏。
两条绝对约束（先读，贯穿全程）
- stack-agnostic（栈无关）：五层缺口一律用"能力描述 + 按栈实例化 lookup"表达，绝不把某一
栈写死为唯一答案。本文与
references/gaps.md 里出现的 stylelint / Vitest / Playwright / MSW
等，都是 JS/TS 栈的示例实例——它们是"能力在该栈的实例"，不是唯一解。先读项目清单
（package.json 或等价物），再实例化该栈对应的工具。
- project-agnostic（项目无关）：不出现任何业务名词，也不绑定任何具体框架（不假设 Next.js / React /
某 UI 库）。所有项目专有的东西——设计规范文档、design token 名、token 值、涨跌色约定、必跑页面
——一律写成条件式："若项目存在视觉规范文档 / design token，则从中读取并据此生成断言"。
用作示例不作前提：没有视觉规范文档的项目，token 类断言自然不命中，只跑结构性/几何/a11y 层。
工作流（六步闭环）
步骤 0 · 识栈
读项目清单文件，确定前端栈与运行时，后续所有工具选择都基于此实例化：
| 栈线索文件 | 前端栈 | 后续工具来源 |
|---|
package.json（含 tsconfig.json） | JS / TS（含各类框架） | 见各层的 JS/TS 行（本 skill 主示例栈） |
pubspec.yaml | Dart / Flutter | 用"能力"反查该栈等价物（widget test / golden test / 多设备） |
*.csproj + Blazor | .NET 前端 | 反查该栈组件测试 + Playwright .NET |
| 其他 | 按需 | 用"能力"反查该栈生态等价物 |
找不到清单文件就停下来问，别假设。monorepo 则对被测前端目录就近识别。
步骤 1 · 立地基（前端特有，不可跳过）
这是本 skill 与 backend-testing 最大的流程差异：前端项目的测试地基常常为零——
很多 [FE] 任务的出参验证只写"手测"，项目里可能根本没装测试运行器 / 组件测试库 /
浏览器驱动。所以收尾补测不能假设 L0/L1 已就绪，必须先验地基、缺则先立：
- 检查清单文件，确认是否已有：① 测试运行器；② 组件/DOM 测试库；③ 浏览器驱动（端到端/截图）。
- 若无运行器：先装地基（JS/TS 栈示例：Vitest + Testing Library + Playwright），接好最小配置
与脚本，让"能跑一条最简单的测试并变绿"这件事先成立。地基没立起来，后面任何层都无从谈起。
- 若已有部分地基，只补缺的那部分，不重装、不替换已选定的工具（surgical）。
因此本 skill 的覆盖下沿是从立地基开始，不是"假设单测已就绪、只补 L2~L6"。
步骤 2 · 条件命中（防过度测）
不是五层全测，只对该 feature 实际命中的子集补。逐层判断（详见 references/gaps.md）：
| 层 | 命中条件 | 不命中示例 |
|---|
| ① 编译期 lint 门 | 项目有视觉规范 / token，需禁裸色值、禁第二 UI 库、禁任意值 | 无视觉契约、无组件库约束 |
| ② L0/L1 单测 | feature 含组件 / 渲染逻辑 / 主题 / 涨跌色等需断言的视觉行为 | 纯静态文案、无逻辑透传 |
| ③ a11y + 跨浏览器/响应式 | 有交互组件、表单、多视口/多浏览器要求、几何约束（如无横向滚动） | 纯后台无 UI |
| ④ 前后端契约 mock | feature 消费后端接口，需隔离后端独立测前端 | 无外部数据、纯静态 |
| ⑤ 视觉回归 | 有需要"长得对"且会演进的关键页面/组件 | 一次性内部页、视觉无契约 |
纯静态 / 无视觉契约的 feature 很可能只命中 1–2 层——这是正常的，不要硬凑。
步骤 3 · 按栈实例化工具（装 + 配）
对每个命中的层，按步骤 0 识别的栈，从 references/gaps.md 取对应行实例化成熟工具：
装上、接好配置、纳入 CI。不自己造工具（这是与 backend-testing 的根本不同）。
对每层标注闭环性：全自动（lint / 单测 / a11y / 跨浏览器 / 契约 mock）vs 需人审裁决（仅 L2 视觉基线）。
步骤 4 · lint 门 + RED→GREEN 补测
按"最便宜的层优先"顺序补：
- 先上 lint 门（①，最便宜、不写测试）：把项目视觉契约翻成 lint 规则（禁裸色值/只允许
var()、
禁第二 UI 库 import、禁任意值 hex class）。编译期就拦，连测试都不用写——性价比最高，先做。
- L0/L1/a11y/响应式/契约（②③④，全自动 RED→GREEN）：先写会失败的测试，确认它因真实缺口/未覆盖
而红（不是测试写错而红）→ 让它转绿。翻译动作在这里发生：例如把"涨跌色 token 值"翻成
getComputedStyle 断言、把"无横向滚动条"翻成 scrollWidth <= clientWidth 的几何不变量断言、
把后端 OpenAPI 翻成 MSW handlers。
- 视觉回归（⑤）的基线交人审：截图 diff 由机器产出，但"这个 diff 算不算回归"是语义判断——
机器只能给 diff，不能裁决。把基线裁决留给人（见下"人审节点"）。
具体工具与代码模式见 references/gaps.md，按步骤 0 识别的栈取对应行。
步骤 5 · 按蓝本归档 + 出 PR 人审
每个新增的 lint 规则 / 回归测试：
- 按
testing-system-blueprint 的风险分级排序（如越权式的视觉错误——涨跌色反了会误导决策——优先进发布门）。
- 挂可追溯 ID（关联 feature / AC / 命中的层）。
- 纳入发布门：明确哪些阻断发布（如涨跌色错、a11y 严重项、契约漂移），哪些告警级。
- 对齐三层节奏（lint/单测落快层；跨浏览器/视觉回归落较慢层）。
- 补测以 PR 形式交付，由人审核合并；PR 说明列出：命中层、跳过层及理由、每个新增回归对应的层与风险级别。
五层落地结构速览（详见 references/gaps.md）
逐层 = 一类缺口。所有工具列均为 JS/TS 栈示例，按栈实例化，不锁定。
| 层 | 成熟工具（JS/TS 示例，按栈实例化） | 闭环性 |
|---|
| ① 编译期 lint 门（最便宜，优先） | stylelint（禁裸色值/只允许 var()）、禁第二 UI 库 import、禁 Tailwind 任意值 hex class | 全自动，不写测试 |
| ② L0/L1 单测 | Vitest + Testing Library；含 getComputedStyle 断言 token 解析值 / 深色覆盖 / 涨跌色值 | 全自动 RED→GREEN |
| ③ a11y + 跨浏览器/响应式 | axe-core / @axe-core/playwright（自动检约 57% a11y，对比度占约 30%）；Playwright projects 多视口 + 几何不变量断言（无横向滚动 scrollWidth<=innerWidth） | 全自动 |
| ④ 前后端契约 mock | MSW + 从后端 OpenAPI 生成 handlers（消漂移），可选 Pact 双向契约 | 全自动进 CI |
| ⑤ 视觉回归 | Playwright 截图 / Chromatic，Docker 跑消平台 flake | 截图 diff 自动，基线裁决人审 |
人审节点：全套只有一个 = L2 视觉基线裁决
前端这套补测里，机器能完成的绝大部分都自动化了——lint、单测、a11y、跨浏览器、响应式几何、
契约 mock 全是确定性判断。真正需要人审的节点全套只有一个：L2 视觉回归的基线裁决。
- 为什么只有这一个需要人："这个截图 diff 算不算回归"是语义判断——可能是有意的设计改版
（应更新基线），也可能是意外破坏（应拦截）。机器只能算出"有 N 个像素变了"，不能裁决这变化是好是坏。
- 怎么把人审量压到最小：Docker 固定渲染环境消平台 flake（假阳性大头）+ 可选 AI 预过滤明显假阳性 +
做成 PR check 集中呈现 diff。但最终 approve 仍是人——这是不可自动化的本质，不要假装能消掉它。
另一类：机器永远断言不了、只能人审（明确不塞进自动化）
除了"基线裁决"，还有一类视觉/语义项根本无法写成机器断言，必须单列、明确不塞进自动化套件，
留给人审（典型如代码评审 / 设计走查）：
- 设计样本/参考的引用与还原度（"做得像不像那张认可的成品图"）；
- 装饰性克制（有没有多余的装饰、噪声）；
- 认知层级（重要信息是否在视觉上被正确强调）；
- 整体质感/品味（"看起来专不专业""有没有 AI 味"）。
强行给这些写断言只会产生脆弱、误导的测试。明确把它们划在自动化范围之外，是这套体系诚实的一部分。
自愈护栏（不可越过）
补测过程允许有界自动迭代（RED→GREEN），但受以下护栏约束（沿用 blueprint 的护栏）：
- 只写测试 / lint 规则，不改产品码——这是默认动作。本 skill 是"装配工 + 监理"，职责是装工具、
配规则、翻译断言，不修业务实现。
- 断言不可弱化——禁止为了让测试转绿而放松断言（如把涨跌色断言注释掉、把对比度阈值调低、
把"无横向滚动"几何断言删掉、给 a11y 违规加白名单豁免）。转绿必须靠正确产品码或正确测试，不靠降标准。
- 禁伪造修复——不得用
skip、强行更新视觉基线掩盖真实回归、mock 掉被测渲染本身等手段伪装通过。
- 有界重试升级——自动迭代有上限；连续失败达上限即停止并升级给人，不无限刷（视觉 flake 尤其要警惕被
误当成"再跑一次就好"）。
- 产 PR 人审——所有产物以 PR 交付，人工审核后合并。
- 发现真 bug 要 HALT，回交 superpowers TDD 修——本 skill 不自行改产品代码。补测过程中若 RED
暴露的是产品真实缺陷（不只是缺覆盖），停下来，把缺陷回交
superpowers:test-driven-development /
superpowers:systematic-debugging 走修复闭环，修完再回到本 skill 把回归固化。
护栏的目的：让闭环可以自动跑，但任何"看起来绿了其实没测到"或"越界改了产品码"的捷径都被堵死。
与上下游的关系
- 上游：
test-routing-advisor 判定"单前端"时调用本 skill（也可被用户直接触发）。
- 蓝本：所有归档/分级/发布门/节奏遵循
testing-system-blueprint（按名引用，不在此复制其内容）。
- 兄弟：
backend-testing 处理"单后端"；二者根本分工不同——后端自建测试代码（施工队），
前端装配成熟工具 + 翻译视觉契约（装配工 + 监理）。
- 方法论复用：发现真缺陷的修复与调试复用
superpowers:test-driven-development 和
superpowers:systematic-debugging（本 skill HALT 后回交它们）。
