cmd-pr-test-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Test Plan

PR测试计划

Generate a manual test plan for the changes in the current branch. The plan should give a reviewer everything they need to verify the PR -- copy-paste commands, clear pass/fail criteria, and logical grouping by change area.

为当前分支的变更生成手动测试计划。该计划应当为评审人员提供验证PR所需的全部内容：可直接复制粘贴的命令、清晰的通过/失败判定标准，以及按变更领域划分的逻辑分组。

Instructions

使用说明

Step 1: Detect base branch

步骤1：检测基础分支

Try these methods in order:

bash

BASE_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null)

bash

BASE_BRANCH=$(git remote show origin 2>/dev/null | grep "HEAD branch" | cut -d: -f2 | xargs)

If both fail, ask the user.

按顺序尝试以下方法：

bash

BASE_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null)

bash

BASE_BRANCH=$(git remote show origin 2>/dev/null | grep "HEAD branch" | cut -d: -f2 | xargs)

如果两种方法都执行失败，请询问用户。

Step 2: Gather change context

步骤2：收集变更上下文

Run all of these and capture the results:

bash

git diff $BASE_BRANCH...HEAD --name-only
git diff $BASE_BRANCH...HEAD --stat
git log $BASE_BRANCH..HEAD --oneline

执行以下所有命令并捕获结果：

bash

git diff $BASE_BRANCH...HEAD --name-only
git diff $BASE_BRANCH...HEAD --stat
git log $BASE_BRANCH..HEAD --oneline

Step 3: Detect project tooling

步骤3：检测项目工具链

Check what's available in the project so you can reference real commands (not generic guesses):

Makefile targets:

make help 2>/dev/null || grep -E '^[a-z_-]+:.*##' Makefile makefiles/*.mk 2>/dev/null

Package manager: Look for
```
pyproject.toml
```
(uv/pip),
```
package.json
```
(npm/pnpm),
```
Cargo.toml
```
(cargo),
```
go.mod
```
(go)

Test runners: Look for

pytest.ini

pyproject.toml [tool.pytest]

jest.config.*

.mocharc.*

Project docs: Read
```
AGENTS.md
```
,
```
CLAUDE.md
```
,
```
CONTRIBUTING.md
```
, or
```
README.md
```
for project-specific test/build instructions
CI config: Check
```
.github/workflows/
```
,
```
Makefile
```
, or
```
Taskfile.yml
```
for existing test commands

Prefer project Makefile targets and documented commands over raw tool invocations. If the project has

make test_unit

, use that instead of

uv run pytest tests/unit/

检查项目中可用的工具，以便引用真实存在的命令（而非通用猜测）：

Makefile目标:

make help 2>/dev/null || grep -E '^[a-z_-]+:.*##' Makefile makefiles/*.mk 2>/dev/null

包管理器: 查找
```
pyproject.toml
```
(uv/pip)、
```
package.json
```
(npm/pnpm)、
```
Cargo.toml
```
(cargo)、
```
go.mod
```
(go)

测试运行器: 查找

pytest.ini

、

pyproject.toml [tool.pytest]

、

jest.config.*

、

.mocharc.*

项目文档: 读取
```
AGENTS.md
```
、
```
CLAUDE.md
```
、
```
CONTRIBUTING.md
```
或
```
README.md
```
获取项目特定的测试/构建说明
CI配置: 检查
```
.github/workflows/
```
、
```
Makefile
```
或
```
Taskfile.yml
```
获取现有测试命令

优先使用项目Makefile目标和已记录的命令，而非直接调用原始工具。 如果项目有

make test_unit

，就使用该命令而非

uv run pytest tests/unit/

。

Step 4: Categorize changes and confirm with user

步骤4：对变更分类并向用户确认

Group changed files into categories. Common categories (adapt based on actual changes):

Feature code -- new commands, API routes, services, UI components
Configuration / docs -- config files, markdown, schemas, manifests
Tests -- new or modified test files
Build / deploy -- Makefiles, CI, Dockerfiles, scripts
Deletions -- removed files or deprecated code

Present the detected categories to the user with a summary of what changed in each. Ask them to confirm or adjust before generating the full plan.

Example confirmation format:

I found 3 change areas in this branch:

1. CLI agent mode -- new --agent flag on setup command (cli/commands/setup.py, cli/cli.py)
2. Skills restructuring -- SKILL.md rewrite, new reference docs, deleted shell scripts
3. Test fixes -- E2E test stability improvements (4 test files)

Should I generate the test plan for all 3, or would you like to adjust?

将变更文件分组到不同类别中，常见类别（可根据实际变更调整）：

功能代码 -- 新命令、API路由、服务、UI组件
配置/文档 -- 配置文件、markdown文件、模式文件、清单文件
测试 -- 新增或修改的测试文件
构建/部署 -- Makefiles、CI配置、Dockerfiles、脚本
删除内容 -- 移除的文件或废弃代码

向用户展示检测到的分类，以及每个分类下的变更摘要。在生成完整计划前请用户确认或调整分类。

确认格式示例：

我在当前分支中发现3个变更领域：

1. CLI agent模式 -- setup命令新增--agent参数 (cli/commands/setup.py, cli/cli.py)
2. 技能重构 -- SKILL.md重写、新增参考文档、删除shell脚本
3. 测试修复 -- E2E测试稳定性优化（4个测试文件）

是否需要为这3个领域全部生成测试计划，还是您想调整范围？

Step 5: Generate the test plan

步骤5：生成测试计划

For each confirmed category, generate a test section following these rules:

针对每个确认的分类，按照以下规则生成测试章节：

Formatting rules

格式规则

Numbered sections with separator lines (
```
---
```
) between them
Numbered sub-steps within each section (1a, 1b, 1c...)
Each sub-step has a bold title describing what to test
Each sub-step has a copy-paste command in a fenced code block
Each sub-step has a "Verify:" line stating what success looks like
One command per code block -- never stack multiple commands in one block with comments between them
Use Makefile targets when available instead of raw tool commands

For commands requiring env vars, put them inline:

GROVE_API_URL=http://localhost:8000 make test_e2e_suite

编号章节之间用分隔线(
```
---
```
)分隔
每个章节下使用编号子步骤(1a, 1b, 1c...)
每个子步骤有一个粗体标题描述测试内容
每个子步骤有一个放在代码块中的可复制粘贴命令
每个子步骤有一行**"验证："**说明成功的判定标准
每个代码块仅放一条命令 -- 不要在一个代码块中堆叠多条命令或在命令间添加注释
可用时优先使用Makefile目标而非原始工具命令

对于需要环境变量的命令，将变量内联：

GROVE_API_URL=http://localhost:8000 make test_e2e_suite

What to include per category

每个分类需包含的内容

Feature code:

Happy path: the main thing the feature does, verified end-to-end
Edge cases: invalid inputs, missing arguments, boundary values
Help text / discoverability:
```
--help
```
output shows new flags/options
Error messages: meaningful output on failure, correct exit codes

Configuration / docs:

Validate file format (JSON parse, YAML lint, markdown render)
Verify expected files exist and unexpected files are gone
If publishable: serve locally and fetch to verify

Tests:

Run the relevant test suite(s) with the project's standard commands
Call out expected pass counts if known from prior runs
List individual test commands for spot-checking specific fixes

Build / deploy:

Dry-run build or deploy commands
Verify targets still work after changes

Deletions:

Confirm removed files are actually gone
Verify nothing references the deleted files (grep for imports/includes)

功能代码：

正常流程：功能的核心用途，端到端验证
边界场景：无效输入、缺失参数、边界值
帮助文本/可发现性：
```
--help
```
输出展示新增的参数/选项
错误信息：失败时输出有意义的提示、退出码正确

配置/文档：

验证文件格式（JSON解析、YAML lint、markdown渲染）
验证预期文件存在，非预期文件已删除
如果可发布：本地启动服务并拉取内容验证

测试：

使用项目标准命令运行相关测试套件
如果已知之前的运行结果，标注预期的通过用例数量
列出单独的测试命令用于抽查特定修复

构建/部署：

试运行构建或部署命令
验证变更后目标任务仍可正常运行

删除内容：

确认被删除的文件确实已移除
验证没有内容引用被删除的文件（grep查找导入/引用）

Quick smoke test section

快速冒烟测试章节

Always end with a "Quick Smoke Test" section -- the 2-3 commands a reviewer would run if they only have 60 seconds.

始终在末尾添加「快速冒烟测试」章节，包含评审人员只有60秒时间时会运行的2-3条命令。

Step 6: Write output

步骤6：输出结果

Write the plan to
```
TEST_PLAN.md
```
in the repo root
Print a summary to the terminal showing the section count and a one-liner per section

Terminal summary format:

Wrote TEST_PLAN.md with 4 sections:

  1. CLI Agent Mode -- 7 test steps (happy path, errors, help text)
  2. Skills Restructuring -- 6 test steps (validation, file checks, local serve)
  3. Automated Tests -- 4 test steps (unit, CLI, SDK, E2E suite)
  4. Quick Smoke Test -- 3 commands

Run `cat TEST_PLAN.md` to view the full plan.

将计划写入仓库根目录的
```
TEST_PLAN.md
```
文件
在终端打印摘要，展示章节数量和每个章节的简介

终端摘要格式：

已写入TEST_PLAN.md，包含4个章节：

  1. CLI Agent模式 -- 7个测试步骤（正常流程、错误场景、帮助文本）
  2. 技能重构 -- 6个测试步骤（验证、文件检查、本地启动）
  3. 自动化测试 -- 4个测试步骤（单元、CLI、SDK、E2E套件）
  4. 快速冒烟测试 -- 3条命令

运行`cat TEST_PLAN.md`查看完整计划。

Style Reference

风格参考

Follow the same style used in

cmd-pr-description

Bold the what, plain text the how
No fluff -- every step must verify something
Copy-paste ready -- a reviewer should never need to edit a command
Separate code blocks -- one command per block, bold header above it

遵循

cmd-pr-description

中使用的相同风格：

测试内容加粗，操作步骤使用普通文本
无冗余内容 -- 每个步骤都必须验证某项内容
可直接复制粘贴 -- 评审人员无需编辑命令
独立代码块 -- 每个块仅一条命令，上方加粗标注标题