antithesis-feature-workload

为 Antithesis 构建功能工作负载

技能版本： 2026-10-15 84b188a

用途和目标

从一项具体功能出发，构建用于测试该功能的工作负载。 成功意味着：

• 对该功能的理解足以识别其可测试属性
• 属性具体明确——包括不变量、可达行为和故障模式，而非模糊目标
• 存在能够自主运行的工作负载，用于测试该功能的行为
• 触达声明触发，证明工作负载能够到达该功能的重要状态
• 使用正确的 SDK 类型编写断言，以检查功能不变量
• 可选：工作负载已在 Antithesis 中运行，且已验证测试结果

此技能是 Antithesis 工作流的并行入口。标准流程依次为研究 → 设置 → 工作负载（广泛覆盖），此技能则依次为功能分析 → 定向工作负载 → 迭代（聚焦功能）。

入口点

此技能支持两种起点：

• 功能已完成：源代码可用。预期进行完整分析、构建完整工作负载，且所有断言均通过。
• 功能正在开发中：可能已有部分代码，也可能只有规范或想法。工作负载包含 TDD 风格的存根——在功能完善之前，断言会失败。随着代码逐步落地，断言会转为通过。“为功能变更更新工作负载”工作流负责处理功能演进。

两种入口点都使用相同的工作流。不同之处在于首次运行时通过的断言数量。

前提条件

• 一项待测试的功能——可提供源代码、规范、描述或这些内容的组合
• 可访问 SUT 源代码
• 本地运行需要 Docker Compose v2 和容器引擎（Docker 或 Podman）
• 转为在 Antithesis 中运行时，需要安装 snouty CLI 0.8.0 或更高版本（仅在本地工作时不需要）

与其他技能的关系

• antithesis-research：功能工作负载会进行限定于功能范围的分析——采用相同的代码库探索技巧，但聚焦于“此功能可能出现什么问题”，而非“整个系统有哪些属性”。如果暂存手册中已有完整的研究成果，可将其用作背景，但并不要求必须具备这些成果。
• antithesis-workload：功能工作负载构建的是可自主运行的工作负载，而非 Test Composer 命令。断言模式、值菜单、容错设计和触达声明两者均适用——此技能包含经过调整、适用于限定功能范围工作的参考资料。
• antithesis-setup：功能工作负载不假设 Antithesis 基础设施已经设置或尚未设置。用户要转为在 Antithesis 中运行且需要基础设施时，应委派给 antithesis-setup。
• antithesis-launch：用于提交 Antithesis 运行任务。不要直接运行 snouty launch。
• antithesis-triage：每次 Antithesis 运行后都应使用，并聚焦于“是否正在测试该功能的属性？是否有失败？”，而非全面审查属性组合。
• antithesis-debug：当分诊发现需要深入调查的属性失败时使用——检查失败时刻的容器状态，并通过时间回溯了解事件顺序。

定义

• SUT： 被测系统。
• 功能属性： 关于功能应如何运行、应维护哪些不变量，或哪些行为应可达的具体、可测试主张。
• 触达声明： 一种 Sometimes 断言，用于验证工作负载确实测试了某种功能行为。未触发的触达声明意味着工作负载未能到达正确状态。
• 自主运行的工作负载： 一个驱动 SUT、检查不变量且无需外部编排即可运行的程序。不使用 Test Composer。
• 双模式： 设置 ANTITHESIS_OUTPUT_DIR 时（Antithesis），工作负载使用 SDK 断言；未设置时（本地），则使用等效的本地检查。

文档依据

使用 antithesis-documentation 技能访问 Antithesis 文档。

• SDK 参考：https://antithesis.com/docs/reference/sdk.md
• 属性和断言：https://antithesis.com/docs/concepts/properties_assertions/assertions.md
• 故障注入：https://antithesis.com/docs/product/fault_injection.md
• Docker Compose 设置：https://antithesis.com/docs/getting_started/setup_guide/docker_compose.md

参考文件

参考文件	阅读时机
references/feature-analysis.md	首先阅读——了解系统、理解功能、发现属性
references/self-driving-workload.md	构建工作负载
references/assertions.md	为功能属性和可达性声明编写断言
references/interesting-values.md	选择能测试功能边界的值
references/faults.md	评估故障注入是否会影响此功能
references/iteration.md	可达性声明未触发或属性未得到测试时
references/verification.md	验证发现的问题是否真实

推荐工作流

设计并构建功能工作负载

1. 阅读 references/feature-analysis.md
2. 了解系统：如果 antithesis/scratchbook/ 中已有研究资料，请阅读；否则，围绕该功能所在区域进行轻量级了解，包括架构、数据流和并发模型
3. 理解功能——通过代码、规范、对话或组合方式了解。对于正在开发的功能，明确已构建的部分和计划中的部分
4. 发现功能属性——不变量、可达行为、故障模式。对于尚在开发的功能，未构建部分的属性将成为 TDD 风格的存根
5. 阅读 references/faults.md，评估哪些故障类型会影响此功能
6. 将发现记录到 antithesis/feature-workloads/<feature-slug>/analysis.md
7. 阅读 references/self-driving-workload.md
8. 阅读 references/assertions.md
9. 阅读 references/interesting-values.md
10. 根据功能代码路径中的边界值和已配置限制类别，构建值菜单
11. 设计并构建工作负载：具备双模式断言、容错能力、操作跟踪，以及针对功能关键行为的可达性声明的自驱动程序
12. 构建用于本地运行的 docker-compose（或使用现有设置）
13. 在本地运行。当可达性声明未触发或属性未得到测试时，阅读 references/iteration.md。迭代：先检查可达性声明，再根据证据调整工作负载、断言、SUT 配置或属性
    • 可达性声明未触发 → 调整工作负载或重新审视对功能的理解
    • 属性未得到测试 → 调整操作、值或断言
    • 对功能的理解似乎有误 → 返回第 3 步
14. 如果转到 Antithesis： a. 检查现有设置；如果需要基础设施，使用 antithesis-setup b. 使用 antithesis-launch 运行 c. 使用 antithesis-triage 进行分析（分析重点：“是否测试了该功能的属性？是否存在失败？”） d. 根据分诊结果：如果某项属性失败，转到第 15 步；如果可达性声明未触发，转到“运行后迭代”；如果机制不明确，使用 antithesis-debug 进行深入检查
15. 当某项属性失败时，阅读 references/verification.md。对发现的问题进行分类。测试功能时发现的任何真实错误都有价值。
16. 将发现记录到 antithesis/feature-workloads/<feature-slug>/analysis.md

运行后迭代

1. 阅读 references/iteration.md
2. 如果需要更改断言，阅读 references/assertions.md
3. 检查触达声明——是否触达了功能行为？
4. 根据观察结果选择迭代措施：调整工作负载、调整断言、更改 SUT 配置或修订属性
5. 更新 antithesis/feature-workloads/<feature-slug>/analysis.md，记录 更改内容、观察结果和下一步尝试

根据功能变更更新工作负载

当功能演进，需要让工作负载跟上时：

1. 重新阅读功能说明（代码或规范有哪些变化）
2. 检查哪些属性仍然成立、有哪些新增属性、哪些已过时
3. 更新工作负载、断言和触达声明——对于尚未实现的部分，采用 TDD 风格的桩；对于已实现且通过的部分，移除桩
4. 在本地重新验证——检查触达声明；如果结果显示存在缺口，则按照主工作流第 13 步进行迭代

通用指导

• 一次只处理一个功能。 不要尝试同时为多个功能构建工作负载。每个功能都应有自己的分析、工作负载和迭代周期。
• 工作负载由属性驱动。 每项操作、断言和值的选择都应关联到已发现的功能属性。如果某项工作与属性无关，就发现一个新属性，否则停止。
• 触达声明是指南针。 未触发的触达声明说明工作负载没有覆盖功能的关键行为。每次迭代都先检查它们——在调整其他内容之前，确保工作负载触达了正确的状态。
• 默认从本地开始。 除非功能属性明确要求 Antithesis 能力（故障注入、调度控制），否则从本地开始。本地迭代更快，反馈循环也更紧密。
• 宣布成功前先验证。 属性失败只是候选问题，并非已确认的 Bug。阅读反例，理解执行序列，确认问题机制。测试框架 Bug、断言 Bug 和工作负载 Bug 也会导致属性失败。
• 记录一切。 feature-workloads 目录记录了从“我们有一个功能”到“我们有一个可用工作负载”的过程。后续读者需要了解发现了哪些属性、测试了什么，以及发现了什么。
• 设计具备容错能力的工作负载。 在 Antithesis 故障注入下，瞬时错误是意料之中的。工作负载必须能在故障中继续推进——采用退避策略重试、断开连接时重新连接，并跟踪已尝试与已确认的操作。
• 不要让仅用于 Antithesis 的代码进入生产路径。 如果必须为断言修改共享代码，请确保改动精准。SDK 断言在 Antithesis 之外不会执行任何操作，因此对生产环境的开销可以忽略不计。
• 使用项目所用的语言编写工作负载代码，以便复用项目的客户端、辅助工具和库。
• 工作负载随功能一同成长。 对于正在开发的功能，使用 TDD 风格的桩，为尚未实现的部分构建完整工作负载。随着代码落地，断言会逐步通过。不要等到功能完成后才开始测试。

输出

• antithesis/feature-workloads/<feature-slug>/analysis.md — 功能属性、代码库调查结果、故障评估、迭代历史
• 工作负载代码（带双模式断言的自驱动程序）
• 本地运行所用的 docker-compose.yml（除非已有配置足够）
• 针对功能不变量的断言，以及覆盖功能行为的触达声明

自我审查

在宣布此技能已完成之前，请根据以下标准审查你的工作。 如果你的 Agent 支持子 Agent，请创建一位使用全新上下文的审查者。

审查标准：

• 已完成系统概览——充分了解架构、数据流和并发模型，以便掌握此功能相关的代码范围（或已使用现有研究成果）
• 已在 analysis.md 中记录功能属性，并通过代码库中的证据将其关联到具体代码路径（或关联到开发中功能的计划行为）
• 每项属性都具体且可测试——不是“测试此功能”这类模糊目标，而是明确的不变量、可达行为或故障模式
• 工作负载覆盖了此功能的关键行为（由实际触发的可达性声明验证；对于开发中的功能，已构建部分的可达性声明会触发，而未构建部分的存根会明确标记）
• 断言根据其语义使用了正确的 SDK 类型（不变量使用 Always / AlwaysOrUnreachable，可达性声明使用 Sometimes，路径可达性使用 Reachable）——参见 references/assertions.md
• Sometimes(true, ...) 断言应改写为 Reachable(...)
• 工作负载是具有单一入口点的自驱动程序，而不是 Test Composer 命令
• 工作负载具备容错能力——会重试瞬时错误，在遇到故障时仍能继续推进，不会在首个错误时退出
• 工作负载会跟踪已尝试与已确认的操作，以便断言检查范围，而非精确值
• 工作负载支持双模式——设置 ANTITHESIS_OUTPUT_DIR 时使用 SDK 断言，否则执行本地检查
• 可达性声明断言前置条件，而不是违反条件——系统正确时会触发
• 同一位置的可达性声明不是 Always 或 AlwaysOrUnreachable 的否定
• 值的选择采用功能代码路径中的边界值和配置限制值系列，而非任意范围——参见 references/interesting-values.md
• 断言属性名称是内联常量字符串字面值，在整个项目中唯一——绝不在运行时构造
• 工作负载中的随机性通过 SDK 的随机模块实现，以支持确定性重放（本地模式则使用标准库随机模块）
• 随机性的形式会因运行而异（swarm 测试）——概率和操作权重在每次运行开始时抽取，而不是硬编码
• 对于罕见、危险或对时序敏感的内部状态，如果在 SUT 中添加精简断言能显著提升搜索指引，则未使用仅限工作负载的插桩
• 断言位于工作负载代码或经过精简的 SUT 位置，而非散布在生产代码路径中
• 如果迁移到 Antithesis：已使用 antithesis-setup 技能配置基础设施，而非临时配置
• 如果故障类型与功能属性相关：已确认这些故障已为租户启用——参见 references/faults.md
• feature-workloads 目录记录了分析内容、发现的属性、测试内容以及每轮迭代的发现