跳转至

组件可访问性测试迁移系统规范

意图

使用现有 Astryx 组件的用户应获得与新组件相同的、可追溯至标准的保护,而无需等待仓库级重写。Astryx 将可访问性断言逐步迁移为可复用的规范测试契约,锁定已通过的行为,并将每个现有失败作为有主的工作暴露出来,而不是将其隐藏在缺失或跳过的测试背后。

迁移将共享模式行为与组件特定行为分离。组件绑定声明其实现的模式与状态。可复用契约拥有共享的 WCAG 2.2/APG 结果;组件测试套件保留 API、组合以及实现特定的回归覆盖。

非目标

  • 定义可访问性规范测试的编写方式;这由 AST-020 负责。
  • 修复同一拉取请求中揭示的每个可访问性缺陷。
  • 仅因为测试涉及 ARIA 或键盘输入就删除组件特定测试。
  • 将已知失败、跳过的期望或高覆盖率视为通过的可访问性结果。
  • 在迁移开始前,以所有历史缺口阻止所有现有组件。
  • 将页面级、视觉或真实辅助技术需求迁移到无法证明它们的组件运行时契约中。

需求

迁移清单与工作单元

  • FR1 — 迁移依赖于编写契约。 在 AST-020 成为 current 之前,本规范 MUST NOT 成为 current。每个迁移的模式和绑定 MUST 满足 AST-020 的可追溯性、适用性、证据层、审查和可读拉取请求要求。
  • FR2 — 清单先于删除。 在更改组件测试之前,迁移 MUST 记录每个交互部件、其采用的模式、代表性状态、现有共享模式断言、组件特定断言、分配的证据层以及已知失败。具有多个交互部件的组件 MUST 分别映射每个部件。
  • FR3 — 迁移拉取请求保持有界。 一个拉取请求 SHOULD 添加或实质性地修订一个可复用模式契约及其首批代表性绑定,或将一组有界的绑定迁移到已经 current 的契约。它 MUST NOT 仅仅为了提高覆盖率而组合无关模式、大范围组件修复或视觉重新设计。
  • FR4 — 代表性状态是明确的。 每个绑定 MUST 覆盖可能改变所采用模式结果的每个组件状态。根据组件不同,这包括默认值和已更改值、受控和非受控、启用和禁用、可聚焦的禁用状态、必填或无效、打开和关闭、朝向、方向、加载、错误以及相关的组合部件。清单记录被省略的状态为何不能改变共享结果的原因。

移动与保留覆盖

  • FR5 — 仅移动等价的断言。 只有当现有测试的用户结果、适用性和证据层对每个绑定都相同时,它才能移入共享契约。针对回调载荷、公共 props、表单提交、组件自有的组合、样式或刻意组件例外情况的测试,即使它们也检查 ARIA 或键盘事件,也留在本地。
  • FR6 — 重复所有权在迁移拉取请求中结束。 一旦契约和绑定在相同或更强证据层上证明了现有共享结果,就必须删除或重写确切的本地断言,使其仅覆盖剩余的组件特定契约。临时重复需要一个具名的移除阻碍项;“额外覆盖”不是保留两个所有者的永久理由。
  • FR7 — 除非单独的更改授权,否则保留现有行为。 迁移拉取请求记录观察到的失败,但不会静默更改组件 API、交互、聚焦、语义、视觉或兼容性。一个小的前置修复可以先落地,或作为可单独审查的提交和拉取请求,纳入其所属的 current 记录之下。

已知失败与回归门禁

  • FR8 — 每个已知失败都精确且可操作。 已检入的已知失败记录 MUST 包含期望 id、组件绑定和状态、观察到的用户影响、标准引用、证据层、确切失败原因以及迁移不修复它的理由。禁止使用通配符、整体模式抑制和无主的文本理由。运营跟踪 MUST 为该确切的期望/绑定/状态元组保留一个持久、有主的缺口记录。该缺口记录 MUST 说明是现行权威还是客观标准决定了所需结果,抑或 API、行为、所有权、兼容性或设计方向仍是一个人为决策。记录缺口并不等于批准修复。方向未定时停止实现,并转交一个确切的所有者问题。私有跟踪器标识符或 URL MUST NOT 被复制到公共源代码、提交或拉取请求文本中;运营注册表维护该外部映射。
  • FR9 — 已知失败只改变其精确门禁结果。 具有已知失败的绑定仍运行期望并报告 known-failure,绝不报告 pass。只有该精确的预期结果停止阻止首次迁移。不同的错误、另一个状态、新的期望或更广泛的失败 MUST 失败。当期望开始通过时,CI MUST 报告意外通过,并要求移除过期记录,而不是继续将其计为技术债。
  • FR10 — 迁移锁定基线,但不将债务称为符合性。 对于该绑定,通过的必要期望立即进入门禁。记录在案的历史失败仍然是可见的失败债务,但不会阻止首次迁移。新组件和新支持的状态 MUST NOT 添加任何必需的已知失败。在基线之后添加或扩大已知失败需要明确的所有者决策和一个持久、有主的缺口记录;这不是常规测试更新。
  • FR11 — 报告呈现事实,而非单一质量分数。 覆盖输出 MUST 分别报告模式、绑定、适用期望、通过、已知失败、未运行层和豁免。它 MUST NOT 将这些状态合并成一个百分比或等级,作为组件可访问性或符合性来呈现。一个只有一项必需期望失败的模式并不“基本符合”。

仓库集成与审查

  • FR12 — 当前组件记录指向新所有者。 当迁移后的组件存在当前的组件或模块记录时,其 verified_by 元数据和验证映射 MUST 指明该绑定,并为共享契约不拥有的结果保留单独的证据。迁移不会仅为了满足此反向链接而创建组件记录。
  • FR13 — 新工作优先使用现有契约。 一旦模式契约成为现行契约,采用该模式的新组件或新添加的组件部分 MUST 从首次实现起即绑定到该契约。作者 MUST NOT 创建共享断言的并行临时副本。如果契约不完整,应在依赖本地测试之前扩展并审查该契约。
  • FR14 — 迁移拉取请求是可读的账本。 其描述 MUST 指明受影响的用户和模式、所绑定的组件部分和状态、被迁移的断言、保留的本地测试及其原因、确切的已知失败及其权威分类、已运行的证据层,以及变异或前后证据。描述 MUST 区分测试迁移与组件修复,并且 MUST NOT 暴露私有运维追踪器。
  • FR15 — 进度按用户影响力排序。 首次绑定仍是由原型证明的 Switch 参照实现。后续工作优先处理被广泛复用的交互模式、存在已知键盘/焦点/语义失败的组件,以及修正后可保护多个组件的共享原语。仓库顺序或易于产生高数量的做法 MUST NOT 凌驾于用户影响之上。

平台支持

  • 支持的功能/引擎下限:每个绑定遵循其组件当前的支持契约以及 AST-020 分配的证据层。
  • 不支持的行为:未运行的浏览器、视觉、手动或真实辅助技术(real-AT)层仍明确保持未运行状态;jsdom 成功并不能解除该状态。
  • 浏览器证据:可能影响浏览器所拥有的模式行为的组件更改,会运行相关的真实浏览器绑定。真实辅助技术(Real-AT)结果遵循 AST-009,作为带有持久凭证的推荐后续操作。

当前状态影响

当前的组件测试套件将共享可访问性结果与公共 API、实现、视觉和回归测试混合在一起。例如,Switch 目前在一个文件中测试角色(role)、可访问名称和描述、选中和禁用状态、激活、表单参与、加载和错误语义、禁用原因组合、强制颜色 CSS、回调负载以及布局细节。共享的 Switch 模式只能拥有源于标准的角色、名称、状态、可聚焦性和激活结果。表单数据、回调负载、工具提示组合和组件样式仍归 Switch 所有。

首次实现证明了现有组件可以在 jsdom 和 Chromium 中绑定到一个可复用契约。其预期失败机制仅在满足 FR8–FR10 的精确性时保留:已知失败是可见的技术债,绝不是通过或笼统跳过。

运维差距跟踪独立于公共契约来源。公共已知失败记录保持自包含且可审查,而项目配置的差距注册表将相同的期望、绑定和状态映射到其所有者、分诊和后续修复。迁移工作 MUST NOT 仅为了承载已知失败债务而创建公共 issue,私有追踪器引用 MUST NOT 进入此公共仓库。

渐进式推出

  1. 参照模式。 在当前的 AST-020 类型、自测试、证据边界和报告下重建 Switch 原型。绑定当前 Switch 状态而不改变行为。
  2. 简单控件。 迁移其他可干净隔离角色、名称、状态、禁用行为和键盘激活的单一控件模式。
  3. 复合组件。 迁移选择、导航、网格、树和菜单部件,包括朝向、方向、漫游焦点、输入即查找(typeahead)以及打开/关闭状态。
  4. 覆盖层与异步结果。 添加浏览器拥有的焦点、顶层(top-layer)、inert(惰性)和关闭检查,同时将公告和虚拟光标断言经由 AST-009 路由。

追踪器可以根据用户影响在这些阶段内重新排序组件。后续阶段 MUST NOT 为了提升吞吐量而削弱证据边界或已知失败规则。

本已接受的规范不改变任何组件测试、行为、包、公共 API 或 CI 门禁。这些更改将在由此记录管辖的实现工作中进行。

验证

契约 验证 代表性状态 变异或失败预期
FR1–FR4 迁移清单 schema 与审查 一个控件;带触发器和弹出层的组件;受控/禁用/错误/RTL 状态 迁移在没有适用当前契约的情况下开始、将整个组件视为一个部件,或遗漏改变语义的状态
FR5–FR7 前后断言所有权审查与未变化的组件测试套件 共享角色/状态检查;回调负载;表单数据;样式规则;发现的组件缺陷 共享断言仍被重复、组件专属证据被删除,或迁移静默改变行为
FR8–FR10 对确切已知失败、新失败和意外通过的运行器测试 一个历史差距;非预期报错;第二个状态;已修复的期望 通配符掩盖回归、过时差距仍保留,或新工作未经决策而增加债务
FR11 覆盖率报告快照和断言 通过;已知失败;豁免;未运行的浏览器层 单一百分比掩盖了必需的失败,或将未运行的层报告为通过
FR12–FR14 知识验证、组件验证映射和 PR 模板检查 当前组件记录;无记录的组件;首个新采用者 反向链接指向已删除的本地测试,出现并行的临时断言,或 PR 隐藏了迁移/修复范围
FR15 持久差距注册表审查 高使用率控件;已知键盘缺陷;简单低影响组件 工作仅按最大化迁移数量排序,创建重复的差距记录,或未决方向被视为自动修复
平台 现有单元/axe/浏览器检查以及 AST-009 分类 jsdom 行为;真实焦点;树暴露;语音播报 较低层将其无法观察到的浏览器像素或真实 AT 输出判为通过

完成标准

只有当以下条件全部满足时,模式迁移才算完成:

  • 其契约在 AST-020 下保持最新,并通过其正向和负向自测;
  • 每个受影响的组件部分和相关状态都有绑定,或有明确的归属理由说明其被排除;
  • 等效的共享断言由单一负责人负责,组件特定测试继续保留;
  • 每个历史失败都拥有精确的、可安全公开的已知失败记录,以及 FR8 要求的独立持久归属差距记录;
  • 必需的通过预期把关回归,意外通过移除过时债务;
  • 报告将通过、已知失败、豁免和未运行层分开呈现;
  • 当存在当前组件或模块记录时,这些记录指向新的绑定;以及
  • 拉取请求呈现 FR14 要求的可读迁移台账。

仓库迁移只有在以下情况下才算完成:每个已交付的交互式组件部分都映射到当前的模式契约,或明确记录为何没有可复用的模式适用,并且没有针对共享预期残留重复的临时测试。

决策日志

DEC-1 — 逐步迁移并保留精确的已知失败

Reference: spec:AST-021/DEC-1 Decider: cixzhang, 2026-09-03

一次对一个模式以及一组受限的绑定应用契约。将历史失败保留为精确、可运行的已知失败债务,同时立即把关已经通过的结果。这立即提供了保护,而无需假装现有缺陷合规,也不必等待仓库范围的修复。

已否决:全有或全无的迁移、静默跳过,以及启用一个无法阻止回归的宽泛只报告套件。

DEC-2 — 为共享测试保留单一负责人并精确保留历史失败

Reference: spec:AST-021/DEC-2 Decider: cixzhang, 2026-09-03

保持测试迁移与组件修复相互分离。只将可复用的、源自标准的结果移入模式契约;将组件特定的 API、组合、表单、样式和回调测试保留在组件中。现有缺陷保持为精确、可运行的 known-failure 结果,关联到单一预期、单一绑定和单一状态,并附有独立的持久归属差距记录。它们绝不计为通过,不能掩盖不同或更广泛的失败,并且在修复后变为意外通过,从而移除过时债务。将通过、已知失败、豁免和未运行层作为独立事实分别报告,而不是将它们平均成一个可访问性分数。

已否决:在迁移工作中更改组件行为、删除组件自有测试、广泛跳过,以及可能使必需失败看起来合规的百分比。

DEC-3 — 差距跟踪不会把每个不匹配都变成已批准的修复

Reference: spec:AST-021/DEC-3 Decider: cixzhang, 2026-09-08

保持签入的已知失败记录可安全公开且自包含。在项目的持久差距注册表中单独跟踪其运营归属。差距记录当前的权威结果:客观要求可能决定结果,而新的 API、行为、归属、兼容性或设计选择仍属于人的决策。记录不匹配并不授权修复。

已否决:仅为承载测试债务而创建公开 issue、在公开仓库中暴露私有跟踪器标识符,以及将每个可访问性发现都当作明显的 bug 修复。

未决问题

无。

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