run-smoke-tests

运行冒烟测试

针对真实构建执行完整的用户旅程，并留下足够的证据，供他人审查判断。启动产品或操作其状态之前，先了解宿主项目。

操作约定

• 将 Markdown 视为运行时指令，而不是要编译成代码的源文件。
• 通过受支持的面向用户界面进行测试：Web UI、API、CLI、桌面端、移动端，或有文档说明的组合。
• 将执行与修复分开。运行期间不要修改产品、测试或用户旅程。完成报告后，再开始任何要求的修复。
• 默认使用本地、测试、预览或暂存环境。未经明确授权，绝不更改生产环境、花费资金、发送真实邀请或修改真实用户数据。
• 每项通过或失败的结论都必须有可追溯的证据。
• 保留首次失败的运行记录。不要通过反复重试直至全绿来抹除证据。

工作流

1. 通过仓库理解门槛

阅读最近的仓库说明、产品 README、运行手册、贡献指南、清单文件、启动脚本、现有冒烟测试或端到端测试，以及最相关且范围最小的产品文档。搜索身份验证设置、种子数据、测试账号、功能开关、可观测性、制品约定和清理命令。梳理用户旅程涉及的 UI、服务、状态和外部系统边界，以便将故障归因到产品的正确部分。

启动任何内容之前，必须能够说明：

product and user surface:
authoritative journey source:
relevant architecture and system boundaries:
build and start commands:
target environment and data boundary:
interaction driver or available tools:
authentication and human checkpoints:
evidence capture capabilities:
safe cleanup path:
known abort conditions:

不要猜测缺失的命令、URL、凭据或权限。如果缺少的内容会阻碍安全执行，请将其报告为预检阻塞项。

2. 验证用户旅程约定

阅读 references/smoke-format.md。规范化提供的描述，不要默默添加产品行为。

确认用户旅程：

• 体现一个连贯的用户目标；
• 说明环境和允许的更改；
• 定义关键和非关键判定标准；
• 标明身份验证、支付、安全或破坏性操作检查点；
• 包含清理或隔离方案；
• 说明必须立即中止的条件。

将小型、确定性的行为移至场景测试中。保留冒烟测试对较长路径及系统间衔接点的覆盖。

3. 预检，不改变产品行为

使用有文档说明的命令构建或启动产品。确认健康状态、测试数据可用性、驱动程序连接、录制支持，以及制品所需的存储空间。

优先使用仓库现有的制品目录。否则，如果 .context 已存在，则使用 .context/smoke-runs/；如果不存在，则创建临时目录并报告其绝对路径。除非用户要求，否则不要将生成的证据加入版本控制。

创建运行清单，其中包含：

journey ID and source path
commit or build identifier
environment and base URL or executable
start time and executor
human checkpoints
recording and log sources

如果构建状态不健康、环境不正确、账号或数据边界不安全，或关键判定标准所需的证据捕获不可用，请在步骤一开始前中止。

4. 解读并执行 Markdown

按照用户旅程的顺序，通过真实产品界面逐步执行。每个步骤都记录：

timestamp
instruction
action taken
observable result
evidence path or log reference
provisional judgment
deviation, latency, or uncertainty

使用常规的用户操作方式。除非用户旅程明确测试 API，或仅使用设置 API 创建隔离的测试数据，否则不要调用内部 API 来绕过 UI 步骤。

在声明的人工检查点暂停。说明需要执行的确切操作，并在人工完成后从相同状态继续。绝不要要求用户在聊天中粘贴机密信息。

如果驱动程序支持视频，则录制完整运行，并根据步骤时间线生成字幕或带时间戳的转录。否则，捕获屏幕截图、终端输出、结构化日志和状态快照。如果环境无法生成视频，不要声称有视频。

5. 仅判断一次，谨慎重试

指定一个主要结果：

• PASS：已观察到所有关键判定依据，且未发生任何中止条件；
• FAIL：关键判定依据未满足，或意外的产品错误阻止了目标达成；
• BLOCKED：外部前提、权限、环境或人工检查点阻止了有效判断。

当相同构建版本和输入产生不一致结果时，添加 FLAKY 标记。

不要将缺失的证据视为通过。只有当报告单独指出非关键问题时，才可在存在此类问题的情况下保留通过结果。

最多重试一次，且只有当证据表明问题源于环境或驱动程序故障，而非产品故障时才可重试。保留两次运行的记录，并说明允许重试的原因。

6. 清理并交接

仅执行旅程授权的清理操作。如果清理失败，应隔离测试数据、记录标识符并报告残留内容。不要用通过的产品判断掩盖清理失败。

编写报告，包含：

1. 结果、置信度、构建版本、环境和持续时间；
2. 带时间戳的步骤表；
3. 关键判定依据的结果及证据链接；
4. 人工检查点和偏差；
5. 控制台、网络、日志、屏幕截图和录制文件的位置；
6. 清理结果和残留数据；
7. 本次运行发现的候选确定性测试。

最终用户消息必须区分产品故障、测试环境故障和不确定的判断。

演示示例

• SaaS 团队入职，包含身份验证检查点和一份 示例审计报告。
• 开发者 CLI 首次运行，涵盖 安装、身份验证、从无效配置中恢复，以及在隔离项目中进行清理。

使用这些示例演示运行时的判读。将所有命令、URL、账户和预期结果替换为来自宿主仓库的证据。

故障处理

• 产品无法启动：捕获构建和启动输出，标记为 BLOCKED，不要擅自改用其他环境。
• 无法进行身份验证：在检查点暂停，或标记为 BLOCKED；绝不要使用未经批准的凭据绕过检查。
• 产品行为与 Markdown 不符：保留证据并标记为 FAIL，除非行为来源确实相互矛盾。
• 运行中途证据捕获失败：如果影响关键判定依据，则中止；否则继续，但必须明确说明这一限制。
• 发现缺陷：先完成报告。仅在用户另行提出请求时进行诊断或修复。