Claude Skill

astravia-testing

为 OpenAstravia 的功能变更、Bug 修复、重构、公共合同和 UI 交互设计、编写或审查测试;在决定测试范围、补充回归测试、覆盖用户常见使用流程或评估测试质量时使用。纯文档或没有运行时行为变化的编辑不使用。

LLM Mart · 0 points · 2 views 59 listing impressions 0 install-command copies
Download maomaochong-ai-open-astravia-.agents_skills_astravia-testing-cf58759.zip · 4 KB

Install

skills CLI npx skills add https://github.com/maomaochong-ai/open-astravia/tree/main/.agents/skills/astravia-testing
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install maomaochong-ai-open-astravia@llmmart
Git git clone https://github.com/maomaochong-ai/open-astravia.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole maomaochong-ai/open-astravia collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

OpenAstravia 测试设计与编写

目标

编写能在真实回归发生时可靠失败、能说明哪项用户行为或稳定合同被破坏、且维护成本与风险相称的测试。不要以覆盖代码行、内部调用次数或大量快照代替行为证据。

开始前完整阅读目标目录适用的最近一级 AGENTS.md、相关包 README、现有测试和实现。测试命令与门禁以仓库根 AGENTS.md 和 docs/dev/quality-gates.md 为准;更近一级规则可以收紧本 Skill。

先定义要证明的行为

编码前列出:

  1. 本次会改变的用户可见行为或公共合同。
  2. 必须保持的不变量、兼容路径、事件顺序和副作用。
  3. 用户在受影响功能中最可能执行的常见使用操作路径或流程。
  4. 风险最高的边界、失败、取消、重试、恢复或持久化场景。

把每个场景写成 Given / When / Then:

  • Given:用户已有的状态、合理默认配置和必要前置条件。
  • When:用户从正常入口执行的连续操作,而不是直接调用本应隐藏的内部函数。
  • Then:用户可见结果、公开输出、持久化事实、外部副作用或明确错误。

只覆盖本次改动实际影响的连续步骤,不机械穷举全产品路径。若多个常用入口经过不同的状态、协议或持久化边界,且改动同时影响这些边界,应分别覆盖代表性流程。

按任务选择测试组合

  • Bug 修复:先建立能在旧实现失败的最小复现或明确基线,再写回归测试;修复后还要运行受影响的常见用户流程测试。
  • 新功能或行为变化:至少覆盖一条代表性常见用户流程,再为新增分支、关键边界及可恢复失败添加定向测试。
  • 内部重构:明确保持的不变量,使用已有测试、差分测试或合同测试证明外部行为、事件顺序和副作用未变。
  • 公共合同变更:检查生产者、消费者及兼容路径,覆盖 Schema、协议、序列化、错误和版本边界。
  • UI 交互变化:覆盖真实渲染、事件接线、用户输入、提交、焦点、可访问语义、加载和错误恢复;纯函数测试不能替代组件测试。
  • 权限、并发、取消、重试和生命周期:覆盖允许与拒绝、竞争顺序、清理、重复执行和恢复等会造成高后果的状态转换。

纯文档、无逻辑文案、类型转发或已由现有合同准确覆盖的机械改动可以不新增测试,但仍需运行适当验证并在交付中说明依据。

识别用户常见使用流程

“常见”指普通用户通过产品正常入口、在合理默认配置下完成目标,而不是测试专用入口、调试开关或罕见内部调用。根据功能实际支持的能力和本次改动选择流程,例如:

  • 会话与 Agent:新建或恢复会话 → 输入任务或添加上下文 → 发送 → 查看流式回复或工具结果 → 继续追问、取消或重试 → 重新打开后看到正确历史。
  • 工具与权限:触发需授权的操作 → 查看权限说明 → 批准或拒绝 → 操作继续或被阻止 → 收到明确结果和错误反馈。
  • Plugin、Skill 与 MCP:安装或导入 → 校验清单与确认权限 → 启用 → 在会话中调用 → 禁用、更新或卸载后状态正确。
  • 设置、Provider 与运行时:打开设置 → 修改并校验配置 → 保存 → 当前会话或重启后生效 → 配置无效或资源不可用时得到可恢复反馈。
  • Agent Team:选择或创建团队 → 发起任务 → 成员执行并展示进度 → 汇总结果 → 继续协作、结束或恢复团队会话。
  • 文件与项目:打开项目或选择文件 → 执行读取、编辑或生成操作 → 查看变更与状态 → 确认、重试或重新打开后结果一致。

这些是选路示例,不是要求每次修改都覆盖全部流程。优先从产品入口、用户文档、现有组件接线和生产调用链确认真实流程,不根据测试便利性发明产品行为。

选择最低但充分的测试层级

  • 单元测试:纯计算、解析、选择、校验和状态转换。
  • 组件测试:UI 渲染、输入、提交、焦点、可访问语义和异步反馈。
  • 合同测试:公共 API、IPC/RPC、Tool/Prompt Schema、事件、序列化和跨包边界。
  • 集成测试:跨模块流程、真实内部装配、持久化以及多个状态转换。
  • E2E:只有真实浏览器、Electron、进程、文件系统、打包布局或网络边界无法由低层测试证明时使用。

用户流程测试从用户可触达入口或最接近该入口的组件、服务公共接口进入,尽量使用真实内部装配。能够由组件、合同或集成测试证明时,不要机械升级为 E2E。只有用户在当前任务中明确要求时才运行 verify:ui:*。

写出稳定且有诊断力的测试

  • 测试名称描述用户行为或稳定合同及预期结果,例如“用户拒绝工具授权后不执行操作并看到已取消状态”。
  • 使用 Arrange / Act / Assert 或 Given / When / Then,使前置状态、动作和结果清晰分离。
  • 断言用户可见结果、公开返回值、持久化事实和必要副作用;不要锁定私有字段、脆弱 DOM 层级或偶然调用次数。
  • 一个测试表达一个清晰场景,但允许验证同一用户流程中的连续状态,不要把流程拆成只能按顺序运行的多个测试。
  • 对纯逻辑的多组边界输入优先使用表驱动测试;对用户流程保留可读的独立场景。
  • 时间、随机数、并发和重试使用可控时钟、固定输入或显式同步点;不要用任意 sleep 等待。
  • 每个测试独立建立和清理状态,释放计时器、订阅、进程、临时文件和数据库连接,不依赖执行顺序。
  • 快照只用于稳定且整体形状本身就是合同的输出;不要用大面积快照掩盖关键断言。

Mock 与测试替身

只在真实外部边界使用 Mock,例如 Provider、网络、操作系统、外部进程或不可控时间。内部协作者优先使用真实实现、内存存储或行为明确的 Fake。

不要把被测模块内部全部 Mock 后只验证调用:

expect(sendMessage).toHaveBeenCalledOnce();

应优先证明用户目标或稳定事实成立:

expect(screen.getByText("分析完成")).toBeVisible();
expect(await conversationStore.load(sessionId)).toContainEqual(
	expect.objectContaining({ text: "分析完成" }),
);

只有当“调用某个外部边界”本身就是公开合同或必要副作用时,才断言其参数和次数。

审查测试质量

审查新增或现有测试时逐项判断:

  1. 若实现出现目标回归,这个测试是否真的会失败?
  2. 是否覆盖了本次改动影响的代表性用户常见操作流程,而不只是孤立函数或异常分支?
  3. 断言是否面向可观察行为和稳定合同?
  4. Mock 是否只位于真实外部边界,是否意外绕过了关键生产接线?
  5. 异步、时间、并发和资源清理是否确定且无任意等待?
  6. 测试层级是否足够,又没有不必要地升级为缓慢 E2E?
  7. 失败信息能否直接指出被破坏的行为?

发现缺口时,优先补能捕获真实回归的最低层测试,不重复相同断言,也不为了覆盖率数字制造低价值用例。

运行与交付

使用仓库统一入口,不使用裸 bun test、bunx vitest、npx vitest 或直接 vitest:

bun scripts/quality/run-vitest.mjs --run <test-file>
bun run test:pkg <name>
bun run test:changed
bun run check:quick
bun run check

选择与改动相称的最小充分范围:先跑定向测试,一轮编辑后针对任务文件跑 check:quick,涉及多个包或范围不明确时跑 test:changed。代码任务完成后确认影响范围内的测试、lint、守卫和必要的类型检查通过,不默认扫描全仓,也不重复已通过且未再修改的检查。全量核查使用显式的 check:full / check:lint:full;Biome 或 EditorConfig 配置变更按配置影响扩大 lint 范围。check 不运行测试,不能替代行为测试。

交付时说明覆盖了哪些用户流程或合同、实际运行了哪些测试与检查、哪些未运行及原因、剩余风险和兼容性影响。不得声称未执行的验证已经通过。

Skill 维护

.agents/skills/astravia-testing/SKILL.md 是事实源。.claude/skills 为指向 ../.agents/skills 的 Git 符号链接(Windows 可能检出为目标路径文本);修改时核对这一指向,不创建独立副本。

Files (open-astravia)
  • SKILL.md 8.8 KB
    ---
    name: astravia-testing
    description: 为 OpenAstravia 的功能变更、Bug 修复、重构、公共合同和 UI 交互设计、编写或审查测试;在决定测试范围、补充回归测试、覆盖用户常见使用流程或评估测试质量时使用。纯文档或没有运行时行为变化的编辑不使用。
    ---
    
    # OpenAstravia 测试设计与编写
    
    ## 目标
    
    编写能在真实回归发生时可靠失败、能说明哪项用户行为或稳定合同被破坏、且维护成本与风险相称的测试。不要以覆盖代码行、内部调用次数或大量快照代替行为证据。
    
    开始前完整阅读目标目录适用的最近一级 `AGENTS.md`、相关包 README、现有测试和实现。测试命令与门禁以仓库根 `AGENTS.md` 和 `docs/dev/quality-gates.md` 为准;更近一级规则可以收紧本 Skill。
    
    ## 先定义要证明的行为
    
    编码前列出:
    
    1. 本次会改变的用户可见行为或公共合同。
    2. 必须保持的不变量、兼容路径、事件顺序和副作用。
    3. 用户在受影响功能中最可能执行的常见使用操作路径或流程。
    4. 风险最高的边界、失败、取消、重试、恢复或持久化场景。
    
    把每个场景写成 `Given / When / Then`:
    
    - `Given`:用户已有的状态、合理默认配置和必要前置条件。
    - `When`:用户从正常入口执行的连续操作,而不是直接调用本应隐藏的内部函数。
    - `Then`:用户可见结果、公开输出、持久化事实、外部副作用或明确错误。
    
    只覆盖本次改动实际影响的连续步骤,不机械穷举全产品路径。若多个常用入口经过不同的状态、协议或持久化边界,且改动同时影响这些边界,应分别覆盖代表性流程。
    
    ## 按任务选择测试组合
    
    - Bug 修复:先建立能在旧实现失败的最小复现或明确基线,再写回归测试;修复后还要运行受影响的常见用户流程测试。
    - 新功能或行为变化:至少覆盖一条代表性常见用户流程,再为新增分支、关键边界及可恢复失败添加定向测试。
    - 内部重构:明确保持的不变量,使用已有测试、差分测试或合同测试证明外部行为、事件顺序和副作用未变。
    - 公共合同变更:检查生产者、消费者及兼容路径,覆盖 Schema、协议、序列化、错误和版本边界。
    - UI 交互变化:覆盖真实渲染、事件接线、用户输入、提交、焦点、可访问语义、加载和错误恢复;纯函数测试不能替代组件测试。
    - 权限、并发、取消、重试和生命周期:覆盖允许与拒绝、竞争顺序、清理、重复执行和恢复等会造成高后果的状态转换。
    
    纯文档、无逻辑文案、类型转发或已由现有合同准确覆盖的机械改动可以不新增测试,但仍需运行适当验证并在交付中说明依据。
    
    ## 识别用户常见使用流程
    
    “常见”指普通用户通过产品正常入口、在合理默认配置下完成目标,而不是测试专用入口、调试开关或罕见内部调用。根据功能实际支持的能力和本次改动选择流程,例如:
    
    - 会话与 Agent:新建或恢复会话 → 输入任务或添加上下文 → 发送 → 查看流式回复或工具结果 → 继续追问、取消或重试 → 重新打开后看到正确历史。
    - 工具与权限:触发需授权的操作 → 查看权限说明 → 批准或拒绝 → 操作继续或被阻止 → 收到明确结果和错误反馈。
    - Plugin、Skill 与 MCP:安装或导入 → 校验清单与确认权限 → 启用 → 在会话中调用 → 禁用、更新或卸载后状态正确。
    - 设置、Provider 与运行时:打开设置 → 修改并校验配置 → 保存 → 当前会话或重启后生效 → 配置无效或资源不可用时得到可恢复反馈。
    - Agent Team:选择或创建团队 → 发起任务 → 成员执行并展示进度 → 汇总结果 → 继续协作、结束或恢复团队会话。
    - 文件与项目:打开项目或选择文件 → 执行读取、编辑或生成操作 → 查看变更与状态 → 确认、重试或重新打开后结果一致。
    
    这些是选路示例,不是要求每次修改都覆盖全部流程。优先从产品入口、用户文档、现有组件接线和生产调用链确认真实流程,不根据测试便利性发明产品行为。
    
    ## 选择最低但充分的测试层级
    
    - 单元测试:纯计算、解析、选择、校验和状态转换。
    - 组件测试:UI 渲染、输入、提交、焦点、可访问语义和异步反馈。
    - 合同测试:公共 API、IPC/RPC、Tool/Prompt Schema、事件、序列化和跨包边界。
    - 集成测试:跨模块流程、真实内部装配、持久化以及多个状态转换。
    - E2E:只有真实浏览器、Electron、进程、文件系统、打包布局或网络边界无法由低层测试证明时使用。
    
    用户流程测试从用户可触达入口或最接近该入口的组件、服务公共接口进入,尽量使用真实内部装配。能够由组件、合同或集成测试证明时,不要机械升级为 E2E。只有用户在当前任务中明确要求时才运行 `verify:ui:*`。
    
    ## 写出稳定且有诊断力的测试
    
    - 测试名称描述用户行为或稳定合同及预期结果,例如“用户拒绝工具授权后不执行操作并看到已取消状态”。
    - 使用 Arrange / Act / Assert 或 Given / When / Then,使前置状态、动作和结果清晰分离。
    - 断言用户可见结果、公开返回值、持久化事实和必要副作用;不要锁定私有字段、脆弱 DOM 层级或偶然调用次数。
    - 一个测试表达一个清晰场景,但允许验证同一用户流程中的连续状态,不要把流程拆成只能按顺序运行的多个测试。
    - 对纯逻辑的多组边界输入优先使用表驱动测试;对用户流程保留可读的独立场景。
    - 时间、随机数、并发和重试使用可控时钟、固定输入或显式同步点;不要用任意 `sleep` 等待。
    - 每个测试独立建立和清理状态,释放计时器、订阅、进程、临时文件和数据库连接,不依赖执行顺序。
    - 快照只用于稳定且整体形状本身就是合同的输出;不要用大面积快照掩盖关键断言。
    
    ## Mock 与测试替身
    
    只在真实外部边界使用 Mock,例如 Provider、网络、操作系统、外部进程或不可控时间。内部协作者优先使用真实实现、内存存储或行为明确的 Fake。
    
    不要把被测模块内部全部 Mock 后只验证调用:
    
    ```ts
    expect(sendMessage).toHaveBeenCalledOnce();
    ```
    
    应优先证明用户目标或稳定事实成立:
    
    ```ts
    expect(screen.getByText("分析完成")).toBeVisible();
    expect(await conversationStore.load(sessionId)).toContainEqual(
    	expect.objectContaining({ text: "分析完成" }),
    );
    ```
    
    只有当“调用某个外部边界”本身就是公开合同或必要副作用时,才断言其参数和次数。
    
    ## 审查测试质量
    
    审查新增或现有测试时逐项判断:
    
    1. 若实现出现目标回归,这个测试是否真的会失败?
    2. 是否覆盖了本次改动影响的代表性用户常见操作流程,而不只是孤立函数或异常分支?
    3. 断言是否面向可观察行为和稳定合同?
    4. Mock 是否只位于真实外部边界,是否意外绕过了关键生产接线?
    5. 异步、时间、并发和资源清理是否确定且无任意等待?
    6. 测试层级是否足够,又没有不必要地升级为缓慢 E2E?
    7. 失败信息能否直接指出被破坏的行为?
    
    发现缺口时,优先补能捕获真实回归的最低层测试,不重复相同断言,也不为了覆盖率数字制造低价值用例。
    
    ## 运行与交付
    
    使用仓库统一入口,不使用裸 `bun test`、`bunx vitest`、`npx vitest` 或直接 `vitest`:
    
    ```bash
    bun scripts/quality/run-vitest.mjs --run <test-file>
    bun run test:pkg <name>
    bun run test:changed
    bun run check:quick
    bun run check
    ```
    
    选择与改动相称的最小充分范围:先跑定向测试,一轮编辑后针对任务文件跑 `check:quick`,涉及多个包或范围不明确时跑 `test:changed`。代码任务完成后确认影响范围内的测试、lint、守卫和必要的类型检查通过,不默认扫描全仓,也不重复已通过且未再修改的检查。全量核查使用显式的 `check:full` / `check:lint:full`;Biome 或 EditorConfig 配置变更按配置影响扩大 lint 范围。`check` 不运行测试,不能替代行为测试。
    
    交付时说明覆盖了哪些用户流程或合同、实际运行了哪些测试与检查、哪些未运行及原因、剩余风险和兼容性影响。不得声称未执行的验证已经通过。
    
    ## Skill 维护
    
    `.agents/skills/astravia-testing/SKILL.md` 是事实源。`.claude/skills` 为指向 `../.agents/skills` 的 Git 符号链接(Windows 可能检出为目标路径文本);修改时核对这一指向,不创建独立副本。
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.