Community编程与开发github.com

手动测试计划

为当前分支在运行中的应用编写测试计划,包括前提条件、步骤和精确预期结果,分为Agent可执行的(浏览器或iOS模拟器)和需要人工完成的(如屏幕阅读器测试),并让Agent通过无障碍树预演每个人工用例。

手动测试计划 是什么?

该技能旨在生成针对当前代码分支的手动测试计划,专注于自动化测试无法覆盖的方面:真实数据下的外观、行为和用户流程。它会分析代码变更、拉取请求评论、相关问题以及对话历史,从而确定最有可能暴露重要Bug的测试用例。计划将每个用例分配给能够处理的对象:驱动浏览器或iOS模拟器的Agent,或需要人工完成的任务(如屏幕阅读器测试)。对于人工用例,Agent会先通过无障碍树进行预演,在人工投入时间前发现明显问题。该技能支持Claude Code等Agent平台,并强调在代码审查和自动化测试后,在本地构建(而非部署环境)上运行计划,以确保测试反映当前代码状态。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MagnusBrogie/agent-skills/tree/HEAD/manual-test-plan

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

手动测试计划 是做什么的?

编写检查当前分支在运行应用中表现的测试计划。该计划覆盖自动化测试无法展示的内容:真实数据和真实流程下变更的外观和行为,以及用户可能达到的各种状态。

每个用例都分配给能够处理的对象:驱动浏览器的Agent、驱动iOS模拟器的Agent或人工。给Agent一切它能处理的内容。对于只能由人工处理的用例,先让Agent尝试预演,以便在人工花费时间之前发现明显问题,并让人工知道应该关注哪里。

在应用中运行用例成本高昂。执行同一检查时,Agent驱动浏览器消耗的代币是代码测试的许多倍,而人工则花费数分钟。因此计划应小而精,只包含最可能暴露关键Bug的用例,且不覆盖代码测试同样能处理的内容。一个好的计划应足够简短,以便能够完整执行。

同样出于成本考虑,应晚些编写和执行计划:在阅读代码的审查、由此产生的修复和重构以及代码测试到位之后再进行。然后在即将合并的代码上运行一次计划,之前的通过已经完成了成本低廉的检查。如果代码仍在变化,需在计划顶部说明。如果代码在计划执行后发生变化,需指定必须重新运行的用例:那些“捕获”行指向变更代码的用例。

本地注释。 如果存在名为LOCAL.md的文件,请先阅读它。它包含用户项目的默认设置(命令、主机、账户、路径),不属于发布的技能。如果它与当前项目相关,则视为项目指令的一部分;否则忽略。

收集变更

请求可能指定基础分支。如果未指定,按以下顺序选择:

  1. 分支拉取请求的基础分支(如果有):gh pr view --json baseRefName --jq .baseRefName。
  2. 仓库的默认分支:git symbolic-ref --short refs/remotes/origin/HEAD。
  3. origin/main,然后是main。

优先使用远程跟踪引用(origin/<branch>)而不是同名本地分支。包括尚未提交的工作:

base=$(git merge-base <base> HEAD)
git diff --stat "$base"          # 已提交 + 暂存 + 未暂存
git diff "$base"
git status --short               # 未跟踪文件不在差异中;需读取它们
git log --oneline "$base"..HEAD

阅读差异未包含的三个信息来源

差异显示的是变更内容,但没有显示变更的目的、人们已经发现的问题,或本次对话中的决策。在选择任何用例之前,必须先阅读这三者。它们是必需的输入,而非背景;计划需报告阅读了哪些内容,并展示每个来源如何影响计划。

1. 拉取请求及其评论

pr=$(gh pr view --json number --jq .number)
gh pr view --json title,body,baseRefName
for kind in "issues/$pr/comments" "pulls/$pr/reviews" "pulls/$pr/comments"; do
  gh api "repos/{owner}/{repo}/$kind" --paginate --jq '.[]
    | select(.user.type != "Bot" and (.body // "") != "")
    | {id, reply_to: .in_reply_to_id, user: .user.login, path, line: (.line // .original_line), body}'
done

这三个列表是对话评论、审查摘要和差异行内评论,已排除机器人输出。但部署链接通常来自机器人,因此需单独查找。部署环境不是计划执行的地方(见下面的“测试本地构建”);链接仅用于比较和作为备选:

gh api "repos/{owner}/{repo}/issues/$pr/comments" --paginate \
  --jq '.[] | select(.user.type == "Bot") | .body' | grep -oE 'https?://[^ )|>"]+' | sort -u

阅读描述、每个人工评论以及作者的回复。描述中的报告等同于评论中的报告。从中获取:

  • 任何人在应用中看到的内容: 错误的值、永不结束的状态、失败的流程、截图。每个都成为一个重新测试该报告的用例,无论代码是否已更改。然后询问同一故障可能在哪些地方出现(兄弟屏幕、以其他方式达到的相同状态)并考虑增加用例。
  • 审查中提出的行为疑虑(例如“顺序可能与显示的不一致”):每个都是候选用例,评级较高,因为代码的读者已经怀疑它。
  • 描述中的测试说明: 作者声称已测试的内容和未测试的内容。根据提交日志(git log --format='%h %ad %s' --date=short "$base"..HEAD)标注说明日期:在后续提交触及相同代码之后测试的内容,其当前形式未经测试。上次人工测试后的提交应该是计划首要关注的目标。
  • 部署环境链接: 分支自身的部署和基础分支的部署,用于并排比较。
  • 线程中关于行为应如何表现的决策。 这些确定了预期结果。

2. 问题

从分支名称、提交主题、拉取请求标题或描述,或跟踪器机器人的评论中查找问题标识符。使用项目指令中指定的跟踪器以及可用的工具进行查找。阅读描述、验收标准、讨论以及任何附带的截图或重现步骤。从中获取:

  • 原始报告。 如果问题描述了一个Bug,其重现步骤成为计划中的第一个用例:按照报告的步骤,预期结果为修复后的行为。如果问题只是一个标题,或指向无法读取的线程或附件,需说明,从标题和拉取请求描述中重建用例,并标记为重建。
  • 每个验收标准。 每个都必须归入以下三个位置之一:计划中的用例、覆盖它的命名代码测试、或排除项列表(附有理由)。
  • 问题中提到的受影响用户、数据和平台, 这些说明了要使用的数据形状和测试设备。
  • 链接的相关问题, 其中描述了同一区域以其他方式失败的情况。

3. 本次对话

在编写之前,先回溯本次对话。从中获取:

  • 审查发现: 首先针对当前代码树检查每个发现,因为它可能已在上次之后得到修复。需要运行应用才能确认的发现成为一个用例:一个确认修复的用例,或一个显示遗留故障的用例。可以通过代码测试确定的发现应放在待编写测试列表中,而不是用例中。
  • 来自早期审查通过的“未验证”列表和手动验证步骤。 这些是为了在应用中检查而编写的,是最直接的输入。
  • 用户对变更的说法: 他们担心的部分、提到的状态、已经手动测试的内容,以及要求不要花时间的内容。一个明确的担忧会提高用例的评级;“我已经检查过了”则移除它。
  • 对话中关于行为的决策, 这些确定了仅凭代码可能留有开放空间的预期结果。
  • 对话期间代码发生的变化。 在此会话中编写或重写的代码测试最少。

如果对话中没有相关内容,需在计划中说明,不要假装有。

当无法读取某个来源时

如果缺少gh或未登录、分支没有拉取请求、没有链接的问题或无法访问跟踪器,则使用现有内容继续。在计划顶部列出未读取的每个来源,并说明计划可能遗漏了其内容。不要将仅基于差异构建的计划呈现为完整计划。

阅读其他影响计划的内容

  • 如何本地运行应用: 项目文档中记载的本地构建命令、其连接的后端以及使用的端口。阅读项目中关于测试环境、测试账户和功能标记的说明,以及应用支持的平台(Web、iOS、Android)。
  • 自动化测试覆盖的内容: 阅读差异中的测试,使计划不会在测试已经确定的内容上浪费任何人的时间。
  • Agent在此处有哪些工具: 它可以驱动的浏览器和设备模拟器。在Orca中,这些是嵌入式浏览器(orca-cli技能)和iOS模拟器(orca-emulator技能;Android对应orca-emulator-android)。还需查找:
    • Agent可以驱动的屏幕阅读器, 例如voiceover技能,它针对页面运行真实的macOS VoiceOver并返回其内容。
    • 脚本化浏览器(已安装浏览器的Playwright),用于嵌入式浏览器无法完成的任务。例如,嵌入式浏览器可能无法将内容复制到系统剪贴板,因此检查复制的内容需要一个Agent可以读取其剪贴板的浏览器。

记录本次会话中可用的工具;计划在其设置部分说明。

测试本地构建,而非部署的分支

每个用例都应针对工作树的本地构建。部署的特性或预览环境只包含已提交和推送的内容:它滞后于正在开发的代码,无法显示未提交的更改,并且在测试期间所做的修复需要提交并推送后才能在那里重新测试。本地构建显示当前的代码状态,修复后可以立即重新测试。

因此计划设置包括:

  • 如何构建和启动本地应用, 使用项目文档中的确切命令、运行目录以及服务的URL。如果其他会话或工作树可能正在运行应用,请说明如何选择空闲端口。
  • 本地构建连接的后端。 必须为暂存或测试后端,绝不能是生产环境。指向生产环境的本地构建会对真实客户系统运行每个用例,包括模拟的用例和订单。项目通常每个环境有一个命令(例如stage和prod脚本):在计划中命名暂存环境的命令,并明确说明不得使用生产环境的命令。如果项目文档未明确说明哪个命令针对哪个后端,请从构建配置中查明;如果仍然不明确,请停止并向用户询问,不要猜测。
  • 如何在第一个用例之前检查后端: 查看运行中的应用发送请求的位置(网络日志中API调用的主机或配置的API URL),并确认它是暂存主机。计划中需指定预期的主机。如果是生产主机,则停止:不登录,不运行任何用例。
  • 如何确认构建是当前代码: 在最后一次更改后从工作树启动,并在任何进一步更改后重建或重新加载。如果应用显示版本或提交号,请检查。
  • 如何停止它 当运行结束时。

仅在下述情况下使用部署环境:

  • 与基础分支比较: 基础分支的部署与分支的本地构建并列,用于并排比较用例。
  • 本地构建无法显示的内容: 关于部署本身的用例,例如构建产物、缓存或包裹部署站点的原生应用。在此类用例之前,请检查工作树是干净的且已推送,并且部署服务于该提交,并在用例中说明。
  • 当无法本地构建应用时的备选方案。 在计划顶部说明原因,并说明部署服务的是哪个提交以及工作树中缺少的内容。

计划使用的任何部署环境同样适用此规则:暂存部署,绝不能是生产部署。如果分支同时有暂存和生产部署,计划中只提供暂存URL。

确定测试内容

  1. 列出用户可以看到或操作的不同之处。 将差异中的每个变更向外追踪到展示它的屏幕和流程。共享代码中的变更会影响到使用它的每个屏幕;搜索调用方并全部列出,包括分支不相关的调用方。

  2. 对每个不同之处,决定是否需要运行的应用。 询问代码测试是否可以确定它。如果已经有一个,则排除。如果可以轻松添加(纯函数、解码器、排序顺序、给定状态下的视图函数、状态转换),则从用例中排除,并将其放入待编写测试列表;这样该检查每次变更都会自动运行,而应用中的用例每次都需要付费。只保留代码测试无法达到或不可信的内容:来自真实后端的真实数据如何呈现、在真实浏览器中如何渲染和布局、分别测试的部分如何结合运行、真实请求的时序和顺序、真实导航后的应用状态,以及辅助技术提供的内容。

  3. 找出状态。 对每个屏幕,阅读代码中的分支:加载中、已加载、空、错误、丢失或部分数据、零和负值、非常长的值、单个项目和多个项目、每个改变显示的设置或模式、每个账户或用户类型。保留差异触及的状态。

  4. 确定如何达到每个状态。 命名导航路径,通过其形状描述所需数据(“在两个账户中持有的工具,其中一个没有购买成本”),而不是通过你未确认存在的账户。如果某个状态难以通过真实数据达到,说明如何生成(功能标记、重写响应、限速网络、设置),或标记为需要特定的测试账户。

    当用例依赖于重写的响应时,计划必须使重写可重复;reference/mocks.md说明了方法。

    为每个用例提供一种不依赖账户数据运气的方式。如果真实数据可能缺少该状态,请在应用中命名开启它的控件(设置、切换、另一个账户)

…

[为翻译截断]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能