frontend-testing

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、发布门、三层节奏。

---

两条绝对约束（先读，贯穿全程）

1. stack-agnostic（栈无关）：五层缺口一律用"能力描述 + 按栈实例化 lookup"表达，绝不把某一 栈写死为唯一答案。本文与 references/gaps.md 里出现的 stylelint / Vitest / Playwright / MSW 等，都是 JS/TS 栈的示例实例——它们是"能力在该栈的实例"，不是唯一解。先读项目清单 （package.json 或等价物），再实例化该栈对应的工具。
2. 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 已就绪，必须先验地基、缺则先立：

1. 检查清单文件，确认是否已有：① 测试运行器；② 组件/DOM 测试库；③ 浏览器驱动（端到端/截图）。
2. 若无运行器：先装地基（JS/TS 栈示例：Vitest + Testing Library + Playwright），接好最小配置 与脚本，让"能跑一条最简单的测试并变绿"这件事先成立。地基没立起来，后面任何层都无从谈起。
3. 若已有部分地基，只补缺的那部分，不重装、不替换已选定的工具（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 补测

按"最便宜的层优先"顺序补：

1. 先上 lint 门（①，最便宜、不写测试）：把项目视觉契约翻成 lint 规则（禁裸色值/只允许 var()、 禁第二 UI 库 import、禁任意值 hex class）。编译期就拦，连测试都不用写——性价比最高，先做。
2. L0/L1/a11y/响应式/契约（②③④，全自动 RED→GREEN）：先写会失败的测试，确认它因真实缺口/未覆盖 而红（不是测试写错而红）→ 让它转绿。翻译动作在这里发生：例如把"涨跌色 token 值"翻成 getComputedStyle 断言、把"无横向滚动条"翻成 scrollWidth <= clientWidth 的几何不变量断言、 把后端 OpenAPI 翻成 MSW handlers。
3. 视觉回归（⑤）的基线交人审：截图 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 后回交它们）。