观察真实浏览器，修复失败的 E2E 测试

## 测试前先定好浏览器中可见的成功状态 运行端到端测试之前，将所要求的行为转化为可在真实浏览器中观察的条件。记录起始 URL 或路由、所需的账户或夹具状态、相关情况下的视口、用户操作，以及构成成功的准确可见结果。如果无障碍状态、导航、持久化状态和由网络提供的内容属于该行为的一部分，也应将其纳入条件。 - 相比样式类或 DOM 位置，优先使用稳定的用户可见角色、标签和专用测试标识符。 - 区分测试运行器界面与被测应用；一方的证据不会自动说明另一方的状态。 - 同时定义肯定证据和否定证据，例如可见的确认提示或数值变化，以及没有出现错误横幅。 - 用可观察的就绪条件说明时序预期，不要使用任意设定的延迟时间。 不得仅为让测试通过而弱化断言。如果预期行为存在歧义，应停止工作，并在修改测试代码或产品代码前澄清验收契约。 ## 在真实浏览器中运行测试，保存截图和日志 通过应用的正常路径，在实际受支持的浏览器中启动范围最小且相关的 E2E 场景。应明确配置、夹具数据、身份验证状态、视口和功能开关，使运行过程足以复现。当视觉状态或浏览器交互很重要，且有界面模式或调试模式可用时，应使用相应模式。 发生失败时，在编辑任何内容之前收集以下证据： - 失败的场景以及准确的断言或命令； - 失败时的浏览器屏幕截图或快照； - 目标元素周围的应用 DOM，包括无障碍名称和状态； - 相关的浏览器控制台错误，以及失败或非预期的网络请求； - 当前 URL、重定向、加载指示器和应用中可见的错误消息； - 可用时，用于关联服务器日志的时间戳或运行标识符。 进行有针对性的检查，不要倾倒无关状态。需要区分稳定失败与暂时失败时，可在相同条件下复现一次，但不得启动没有上限的重试循环。 ## 把失败原因归为测试、代码或环境 将观察到的失败分类为测试原因、实现原因或环境原因。分类必须有浏览器证据支持，并在必要时通过检查最小范围的相关源代码或日志来补充证据。 - 测试原因：产品按照验收契约运行，但测试使用了过时的选择器、错误的断言、无效夹具、错误的操作顺序或不充分的就绪条件。 - 实现原因：用户可见行为违反验收契约，例如控件无响应、状态或导航错误、无障碍能力退化，或者产品代码导致应用请求失败。 - 环境原因：测试和实现可能都是正确的，但某项前置条件缺失或不正常，例如服务不可用、凭据无效、浏览器不兼容、初始数据缺失、配置错误或资源耗尽。 证据相互矛盾时，写出彼此竞争的假设，并一次只执行一项能够区分假设的检查。不要把每次超时都归为测试问题，也不要仅因为测试失败就修改产品代码。在证据排除最接近的其他可能性之前，分类应保持为暂定结论。 ## 不放宽断言，按原因做最小的修复 选择能够处理已分类原因且无需大范围重构的修正方案。保留验收契约，并维持失败路径以外的现有用户行为。 - 如果是测试原因，只更新与所观察浏览器状态相矛盾的选择器、断言、夹具、操作顺序或就绪条件。 - 如果是实现原因，在可行时添加或保留一个会失败的回归测试，然后仅修改恢复指定行为所需的最小范围产品逻辑。 - 如果是环境原因，修复或记录缺失的前置条件；不得使用更长的等待时间、停用断言或无条件重试来掩盖问题。 - 相比固定时长的休眠，优先使用可见就绪、请求完成或状态稳定等确定性信号。 - 保持可测试性改动对用户行为中立：添加稳定标识符或无障碍标签，不要让测试依赖偶然的布局。 编辑受保护资源、生成资源、生产资源、破坏性资源或包含凭据的资源之前，应停止工作并取得必要授权。绝不得在测试、日志、屏幕截图、夹具或报告中暴露秘密信息。 ## 重跑同一场景，连续失败就停下 修正后，在相同浏览器条件和验收契约下重新运行原本失败的场景。只有当浏览器明显到达已定义的成功状态，且测试运行器未报告隐藏失败时，才算通过。如果控制台或网络证据参与了诊断，还应确认其中不再出现导致失败的错误。 随后运行直接受影响的最小回归范围，例如相邻场景、功能文件或紧密关联的测试组。除非改动具有广泛影响，或用户明确要求，否则不得扩大到无关的完整测试套件。如果重新运行以不同方式失败，应回到证据收集和原因分类，不要继续叠加推测性改动。 限制重复尝试。采用相同方法进行两次无效修正后，应重新评估诊断并选择另一项区分性检查。连续失败三次且没有新证据后，应停止继续改动代码库并报告阻碍因素。 ## 带上证据，先报告通过、失败还是受阻 只有当最初可在浏览器中观察的验收契约通过、直接受影响的回归范围通过，并且相关致因错误均已消失时，才能以成功状态结束。当继续推进需要尚未取得的权限、凭据、不可用的基础设施、破坏性操作，或无法安全推断的产品决策时，也应停止。 报告结果时应提供足够的证据，使其他人能够验证： - 使用的场景和浏览器条件； - 观察到的失败及其分类； - 支持该分类的证据； - 已完成的最小改动，或尚未解决的前置条件； - 实际执行的准确重试内容及其结果； - 剩余风险、跳过的更广范围检查，以及下一项必要行动。 首先说明通过、失败或受阻。成功条件依赖真实浏览器时，不得仅凭代码检查、单元测试通过或模拟 DOM 就声称任务完成。