跳转至

组件测试充分性架构

{
  "scope": "global",
  "triggers": {
    "testing": [
      "INV1",
      "INV2",
      "INV3",
      "INV4",
      "INV5",
      "INV6",
      "INV7",
      "INV10",
      "INV11",
      "INV12"
    ]
  }
}

目的

Astryx 组件测试应当让维护者确信:当前承诺的行为在发生回归时会清晰地失败,而无需将每一种可能的输入组合或审计清点条目变成永久性测试。

本记录定义当前组件、模块、系列、架构、系统、设计和主题需求以及适用的客观标准如何转化为合理的可观察测试计划。它负责测试充分性和测试质量。它不创造产品行为。

系统模型

测试充分性始于适用的权威来源,而非每个组件必须实现的通用状态清单:

  1. 从所有适用的当前组件、模块、系列、架构、系统、设计和主题记录以及适用的客观标准中,汇集组件当前的公开行为。
  2. 识别那些一旦失败就会损害用户、消费者、无障碍路径、兼容性边界或易回归集成接缝的承诺。
  3. 按可观察行为与风险对输入、状态和边界进行分区。
  4. 检查现有证据是否已针对该特定承诺和分区发生失败。若已失败,引用该证据且不添加重复测试。
  5. 选择能够观察失败的证据层:编译期、单元/DOM、浏览器行为、渲染像素、无障碍树、真实辅助技术、文档/模式校验,或评审。
  6. 仅当该层尚无任何当前具备突变敏感性的证据覆盖此承诺时,才添加新的自动化测试。
  7. 在所属验证映射中记录该关系。

测试数量跟随不同行为与风险的数量。它不是固定目标,也不等于公开属性、源代码分支、审计行或清点条目的数量。

边界与不变量

  • INV1 — 权威与证据相互独立。 测试可以证明任何适用的当前组件、模块、系列、架构、系统、设计或主题权威所要求的行为,也可以证明适用的客观标准所要求的行为。在 spec:AST-029 允许观察性审计的情况下,测试也可以证明通过审计回执中记录的既有公开接口所暴露的行为。该证据可以支持测试充分性判定,但不得(MUST NOT)创造或裁定产品权威。缺失或仅处于草稿状态的权威仍作为单独报告的权威缺口。
  • INV2 — 关键承诺具有回归证据。 测试覆盖所属验证映射点名的每一项适用关键承诺和易回归接缝。关键承诺包括:其失败会破坏主任务、无障碍、公开回调或状态契约、兼容性、数据完整性、清理/生命周期,或某个文档化的组合边界——该边界若失败会破坏当前消费方结果或某个被点名的易回归集成接缝——的行为。
  • INV3 — 先前修复的行为缺陷仍受保护。 对当前可观察行为中缺陷的修复,须包含在具备相应能力的证据层提供的突变敏感回归证据,该证据在修复前复现被破坏的结果,并在修复后通过。若某文档修正未改变源代码、类型、行为和公开机器可读模式,则不算是行为缺陷修复。现有回归证据继续有效,除非权威移除了该承诺,或同等证据被证明已明确涵盖该情形。
  • INV4 — 分区遵循行为与风险。 输入、状态、平台和边界只有在当前证据表明它们走同一条可观察路径且无不同回归风险时,才可共享一个代表性用例。不同的行为、归属、平台语义、失败模式或已知回归历史,需要独立分区。
  • INV5 — 断言观察契约。 测试通过稳定接缝断言公开行为、属主可观察状态、渲染后的用户结果、无障碍语义、编译期消费方契约或外部系统效果。当当前权威明确将其视为契约性内容,或 AST-029 回执将其记录为本审计的既有公开接口时,类、属性、DOM 形态、生成类型或源代码产物即为有效证据。当承诺结果可以被更直接地观察时,测试不得(MUST NOT)仅依赖私有调用顺序、私有状态形态、内部协作者或附带结构。
  • INV6 — 证据具有突变敏感性。 被计入充分性的测试,在其承诺的行为被移除、反转、路由到错误属主或以其他方式被实质破坏时,必须(MUST)失败。重新计算实现、重复类型/源代码声明、用常量自比或快照无关输出的断言,不能证明该承诺。动效判定应持有并断言被判定动效本身(以其目标元素和动画属性来命名);仅凭持有效果次数无法证明该动效,因为其他动画也可能凑满次数。
  • INV7 — 覆盖保持有界且有意图。 测试数量必须具有明确命名的行为、证据层或风险理由。当多个证据层各自观察不同的必需契约边界(如编译期 API、DOM 语义、浏览器行为或辅助技术输出)时,它们不算重复。同一分区内的重复用例、宽泛的防御性矩阵、穷举式组合,以及缺乏额外行为信号的快照数量,不得(MUST NOT)被要求或被计为充分性。
  • INV8 — 验证映射持有持久的证据关系。 适用的当前组件、模块、系列、架构、系统、设计和主题记录中的验证映射,点名关键契约、代表性分区、证据接缝以及突变或失败信号。当不存在当前映射时,spec:AST-029 审计回执记录临时证据关系;缺失映射属于权威或可追溯性缺口,其本身不构成测试覆盖缺口。一个测试可以(MAY)证明多项需求,一项需求也可以(MAY)需要多个测试。不存在一行对应一个测试的规则。
  • INV9 — 审计整改遵循其流程属主。 审计撰写的行为测试整改遵循 spec:AST-029/DEC-4:确立当前或既有的公开接缝,在生产变更前演示新用例为红,并实现一个最小可观察的纵向切片。将该时间顺序存入拉取请求或审计运行的证据中。红/绿历史是变更证据;在变更落地后,它不属于常驻套件充分性的一部分。
  • INV10 — 缺口与加固相互区别。 只有当适用的关键承诺或已知易回归分区缺少突变敏感证据时,覆盖缺失才构成缺口。额外的等价输入、私有实现检查、推测性平台组合,以及无具名风险的防御性边界用例,均属于可选的加固,并不降低充分性判定。
  • INV11 — 新测试需要新的证明义务。 对变更的主张进行分类,而非对被编辑的文件进行分类。变更不得(MUST NOT)仅仅因为编辑了文档、私有样式源代码、私有或生成的类名、私有包装器或其他实现细节,就添加组件功能测试。当前公开类或目标契约不在该例外范围内,变更时需要聚焦的契约证据。只有当变更新增或修复了某个现有的、而现有证据无法在正确层面检测到的不同承诺或风险分区时,才需要新的自动化证据。否则,变更引用现有证据,或使用适用的非测试证明,如类型化文档校验、源代码评审或渲染后的浏览器证据。
  • INV12 — 触摸与滚动证据使用页面自身的滚动。 拉取请求为浏览器自身滚动物理特性(橡皮筋回弹、惯性、键盘自动显示、浏览器界面折叠、下拉或滑动手势)所提供的录制、测量和预览链接,必须在滚动文档的 apps/sandbox 页面上获取,而非在 Storybook 中或内部溢出容器内获取,除非被测组件本身就是滚动容器。这些物理特性正是证据所要展示的内容之一(DEC-1)。其他滚动证据(例如面板内滚动的布局轨迹)以及自动化测试,仍遵循 INV1–INV11 及各记录的验证映射。

合理分区

分区由一种差异定义,这种差异可能改变所承诺的结果或其风险。代表性维度包括:

  • 语义状态或转换;
  • 受控、非受控、乐观、拒绝或中断的所有权,且当前契约对它们有所区分;
  • 适用情况下的启用、禁用、只读、忙碌、必需或无效行为;
  • 当所有者或客观标准预测到不同行为时,输入模态、方向、浏览器能力或平台;
  • 当算法或用户结果改变时,零、一、多、空、溢出、边界或无效数据;
  • 当所有权或生命周期改变时,默认、组合、可替换部件、嵌套所有者、门户/顶层或拆除路径;以及
  • 恰好是先前曾经出错的输入和接缝。

只有当证据支持相同的可观察契约、结果、所有者和回归风险时,输入才是等价的。共享的实现路径可能支持这一判断,但它既非必要条件也非充分条件。当上述维度均未改变时,不同的字面值不需要单独用例。

何时无需新增测试

一个正确的变更可能不需要新增自动化测试。当现有证据已经能检测到受影响的承诺,或当自动化组件测试无法观察到变更后的声明时,审查者应停止添加测试。

变更 所需证据 不要添加
修正消费者文档中的说明文字或示例,使其与未变更的当前源码、类型和行为一致 适用的现有文档解析器/类型检查/模式验证(如适用),并对照权威源进行审查 重复该说明文字、prop 名称或示例的组件运行时测试
重复出现的确定性文档/源码关系缺少防护 在共享事实源边界上的一个通用验证器 每个被修正文档一个组件专属测试
视觉绘制或几何值发生变化,而状态集合、选择器、状态所有权、时序和公共结构保持不变 真实浏览器前后对照证据,以及适用的稳定视觉回归路径 断言私有类存在的 jsdom 断言,或无法观察像素的功能测试
私有类、包装器、StyleX 声明或 DOM 排列发生变化,但未改变当前结构契约 现有行为证据,以及外观发生变化时的渲染证据 固化新私有实现的断言
现有的变更敏感证据已覆盖相同的承诺和分区 链接现有证据,并说明其失败信号为何能覆盖此变更 具有等价设置和断言的第二个测试
重构保留所有可观察契约 运行适用的现有测试套件,并审查未变的公共接缝 唯一目的是复述重构新结构的测试
机器可读的公共模式、文档化的公共目标/类或编译期消费者契约发生变化 由该公共表面负责的聚焦契约/清单/类型证据 结构契约检查可直接检测失败时,范围更广的功能测试

视觉实现与其私有类可能同时出错。例如,把 Button 改为红色并断言新的私有类名存在,既不能证明渲染颜色,也不能证明用户的视觉结果。只有当当前权威将该确切类作为公共兼容性契约时,类断言才有效;即便如此,它证明的也只是类的可达性,而非像素。

文档本身可以承载公共机器可读契约。在这种情况下,应在共享边界测试其解析后的模式或生成的投影。不要在组件测试中逐字固化普通说明文字,也不要重复源码声明。

如果文档修正暴露了一个未经测试的行为缺陷,则应改遵循行为规则:首先识别当前承诺和未覆盖的分区,然后为该行为添加最小的可观察回归测试——而不是为暴露该问题的措辞添加测试。

测试质量排除项

以下各项本身并不能证明测试的充分性:

  • 仅复制声明而未实际检验消费者编译期契约的类型测试;
  • 由与生产代码相同算法计算出的同义反复期望值;
  • 在新增私有类或 StyleX 声明旁边添加、仅断言该确切类或声明存在的测试;
  • 用作颜色、间距、对齐、裁剪或动效等视觉声明替代品的 DOM/类断言;
  • 固化普通文档说明文字,或重复已经由共享文档/类型流水线验证过的示例的测试;
  • 当公共行为可观察时,针对私有函数调用、hook 内部实现或实现顺序的断言;
  • 变更字节无法识别所承诺行为的快照;
  • 没有不同行为或风险的重复用例;
  • 在没有当前承诺、客观标准、先前缺陷或明确命名的失败假设的情况下生成的笛卡尔积或对抗性输入;
  • 仅证明渲染未抛错的测试,除非在该指定兼容性边界上无崩溃渲染正是所承诺的可观察结果;以及
  • 在修复后添加、却没有证据表明新用例能检测出原始缺陷的测试。

这些测试可能用于支持调试或可选加固。它们不会被认定为关键承诺的唯一证据。

缺失权威与缺失覆盖

审计者在推荐测试之前先界定边界:

  • 当前行为权威,证据充分: 无覆盖缺口。
  • 当前行为权威,证据缺失或不敏感: 测试覆盖缺口。
  • 无当前行为权威: 产品权威缺口;在规定预期输出之前,先转交至权威所有者处理。
  • 仅有草案权威: 私有所有者持有;测试可以保留当前事实,但无法使草案决定成为现行决定。
  • 客观标准独立适用: 测试所需的可观察标准结果,并链接标准所有者。
  • 现有证据已覆盖等效分区: 可选加固,而非缺口。

验证映射契约

验证行标识以下内容:

  • 当前需求或不可分割的需求组;
  • 稳定的可观察接缝与证据类型;
  • 代表性分区及其充分性理由;以及
  • 必须使证据失效的变异或失败。

验证映射并不逐一枚举每条审计清单行、源码分支、属性或测试文件。它们指向足以让持久承诺保持可评审性的证据层级。

未来审计规则迁移交接

本架构不拥有规则权重、评分计算、版本控制实现或 wiki 编辑。它定义了单独的规则激活所 MUST 使用的测试充分性权威。当本记录成为现行记录时,该经单独评审的激活将按如下方式取代 Component Audit Rubric 第 4 节的通用产品行为检查清单:

  • 将 B1–B16 作为产品行为规则 ID 退役;
  • 不要复用这些 ID,也不要对无关的稳定审计 ID 重新编号;
  • 保留加权 Behavior 评分位;
  • 从所有适用的现行组件、模块、家族、架构、系统、设计及主题行为需求,以及适用的客观标准,填充该评分位;
  • 根据观察到的对汇总后适用行为需求与客观标准的符合程度,对 Behavior 评分位打分;
  • 根据 INV1–INV8 与 INV10–INV11 的证据充分性和质量对 Testing 评分位打分,并保留 INV9 与 INV12 作为拉取请求或审计运行证据;
  • 排除不适用需求,并在无法获取所需证据时,保留规则中现有的显式不测量处理;
  • 保持一缺陷/一节的归属方式,避免同一缺失行为或测试被重复扣分;以及
  • 提升规则小版本号,因为替换 B1–B16 会改变评分方法与可比性。

未来的激活按如下方式映射原有行:

原有行 未来来源
B1–B11 所有适用的现行组件/模块/家族/架构/系统/设计/主题行为需求及客观标准;无通用替代行为
B12 已在规则 v1.16 中退役;保留该 ID 作为预留
B13 来自适用现行权威的命名风险分区与已记录的组装接缝;无开放式对抗矩阵
B14 适用于所属行为层的现行组件/模块/家族/架构/系统/设计/主题契约及客观标准
B15 INV2–INV4 下的现行关键承诺与易回归接缝;无通用潜在回归兜底
B16 从 Behavior 中退役;在 spec:AST-029/DEC-4 下保留仅限 PR 的红/绿义务以及 Testing/评审流程

本规格 PR 不编辑 wiki 规则、评分代码、审计提示词、测试或工具。该替换仅在本记录成为现行记录,且经单独评审的规则小版本变更落地之后才会激活。

变更耦合

当变更满足以下情况时,将触发聚焦式测试充分性评审:

  • 新增或移除现行行为承诺;
  • 更改验证映射或其关联证据;
  • 修复缺陷或填补审计覆盖缺口;
  • 声称多个输入/状态是等效的;
  • 新增宽泛矩阵、快照族、实现耦合的测试层,或为仅涉及文档/视觉/私有实现的变更新增测试;或
  • 改变适用的客观标准或平台区分。

评审评估被变更的需求以及有代表性的未变更分区;它不要求无关的完整套件扩充。

所属代码

  • 适用的现行组件、模块、家族、架构、系统、设计及主题验证映射——承诺、代表性分区、证据与失败预期。
  • 同地测试与已检入的浏览器/无障碍绑定——由这些映射链接的可执行证据。
  • 本记录——共享的充分性、分区、断言质量与缺口分类规则。

决策规格

spec:AST-029 继续拥有审计回填、证据收据、模式与 Night Watch 运维;它明确不拥有通用组件测试质量规则。适用的现行组件、模块、家族、架构、系统、设计及主题契约,加上客观标准,仍然是预期行为的来源。

DEC-1 — 触摸与滚动证据使用页面自身的滚动

参考: architecture:component-test-sufficiency/DEC-1 决策者: cixzhang,2026-11-07

触摸和滚动证据是在滚动文档的 apps/sandbox 页面上获取的(INV12)。嵌入查看器 chrome 或内部滚动器中的页面会改变 iOS 的弹跳、动量和 URL 栏行为,因此它无法展示真实应用的实际行为。

验证

不变量 证据 突变或失败预期
INV1、INV10–INV11 权威性与覆盖率、已建立的公共接口以及不新增测试的决策固件 缺失的产品权威性被隐藏,已建立的公共接口证据被拒绝给予充分性结果,可选加固阻止验收,仅文档/仅视觉价值/仅私有的变更收到重复或不观察的组件测试,或者当前的公共类/目标变更被当作私有实现细节而豁免
INV2–INV3 关键承诺、行为缺陷、文档更正和历史回归固件 主要、可访问性、回调、兼容性、组合或先前已修复的行为缺陷失去了其唯一的突变敏感证据但仍通过,或者未更改的纯散文文档更正被要求添加回归测试
INV4 理性分区固件 已被证明等价的值需要重复测试,需要私有实现身份来建立等价性,或者行为上不同的状态合并为一个用例
INV5 公共/运行时/编译时接缝替换固件 附带私有断言通过而承诺的用户或消费者结果被破坏,契约性的 DOM/类型/类/目标证据被错误拒绝,DOM/类断言因无法观察的像素而获得信用,或者选择器/状态行为被错误分类为仅视觉价值的更改
INV6 同义反复、声明复制、快照噪音和行为突变;持有的集合缺少指定运动 不敏感的断言获得信用,有意义的行为突变使已获信用的测试保持绿色,或者运动判断因无关动画而通过
INV7 同分区重复、合理多层证据、穷举笛卡尔积和广泛防御矩阵固件 不同的必需证据层被折叠为重复,或者未指定不同风险的数量被当作充分性
INV8 验证映射关系固件 每个审计行机械地变成一个测试,证据无法追溯到权威来源,或者一个测试无法满足不可分离的需求
INV9 拉取请求和审计运行红/绿追踪固件 审计编写的补救措施缺少变更前失败用例,生产补救先于新用例,或水平测试生成取代了一个可观察的垂直切片
INV12 审查检查:拉取请求提供的用于橡皮筋、动量、键盘弹出、浏览器界面折叠或下拉/滑动手势的录制、测量和预览链接,均指向一个文档会滚动的应用/沙盒路由 这些滚动物理效果的证据来自 Storybook、嵌入式查看器或内部溢出容器,而被测组件本身不是滚动容器;或者 INV12 被应用于其他滚动证据或自动化测试
B1–B16 迁移 规则版本、段落所有权和 Behavior 槽位的迁移夹具 通用 B 规则仍作为产品权威,B12 被重新激活或复用,测试证据在 Behavior 和 Testing 中重复计分,B16 仍是 Behavior 检查,无关 ID 被重新编号,Behavior 权重消失,或评分发生变更但没有伴随次版本号递增

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx