手动测试计划 是做什么的?
编写检查当前分支在运行应用中表现的测试计划。该计划覆盖自动化测试无法展示的内容:真实数据和真实流程下变更的外观和行为,以及用户可能达到的各种状态。
每个用例都分配给能够处理的对象:驱动浏览器的Agent、驱动iOS模拟器的Agent或人工。给Agent一切它能处理的内容。对于只能由人工处理的用例,先让Agent尝试预演,以便在人工花费时间之前发现明显问题,并让人工知道应该关注哪里。
在应用中运行用例成本高昂。执行同一检查时,Agent驱动浏览器消耗的代币是代码测试的许多倍,而人工则花费数分钟。因此计划应小而精,只包含最可能暴露关键Bug的用例,且不覆盖代码测试同样能处理的内容。一个好的计划应足够简短,以便能够完整执行。
同样出于成本考虑,应晚些编写和执行计划:在阅读代码的审查、由此产生的修复和重构以及代码测试到位之后再进行。然后在即将合并的代码上运行一次计划,之前的通过已经完成了成本低廉的检查。如果代码仍在变化,需在计划顶部说明。如果代码在计划执行后发生变化,需指定必须重新运行的用例:那些“捕获”行指向变更代码的用例。
本地注释。 如果存在名为LOCAL.md的文件,请先阅读它。它包含用户项目的默认设置(命令、主机、账户、路径),不属于发布的技能。如果它与当前项目相关,则视为项目指令的一部分;否则忽略。
收集变更
请求可能指定基础分支。如果未指定,按以下顺序选择:
- 分支拉取请求的基础分支(如果有):
gh pr view --json baseRefName --jq .baseRefName。 - 仓库的默认分支:
git symbolic-ref --short refs/remotes/origin/HEAD。 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可以读取其剪贴板的浏览器。
- Agent可以驱动的屏幕阅读器, 例如
记录本次会话中可用的工具;计划在其设置部分说明。
测试本地构建,而非部署的分支
每个用例都应针对工作树的本地构建。部署的特性或预览环境只包含已提交和推送的内容:它滞后于正在开发的代码,无法显示未提交的更改,并且在测试期间所做的修复需要提交并推送后才能在那里重新测试。本地构建显示当前的代码状态,修复后可以立即重新测试。
因此计划设置包括:
- 如何构建和启动本地应用, 使用项目文档中的确切命令、运行目录以及服务的URL。如果其他会话或工作树可能正在运行应用,请说明如何选择空闲端口。
- 本地构建连接的后端。 必须为暂存或测试后端,绝不能是生产环境。指向生产环境的本地构建会对真实客户系统运行每个用例,包括模拟的用例和订单。项目通常每个环境有一个命令(例如
stage和prod脚本):在计划中命名暂存环境的命令,并明确说明不得使用生产环境的命令。如果项目文档未明确说明哪个命令针对哪个后端,请从构建配置中查明;如果仍然不明确,请停止并向用户询问,不要猜测。 - 如何在第一个用例之前检查后端: 查看运行中的应用发送请求的位置(网络日志中API调用的主机或配置的API URL),并确认它是暂存主机。计划中需指定预期的主机。如果是生产主机,则停止:不登录,不运行任何用例。
- 如何确认构建是当前代码: 在最后一次更改后从工作树启动,并在任何进一步更改后重建或重新加载。如果应用显示版本或提交号,请检查。
- 如何停止它 当运行结束时。
仅在下述情况下使用部署环境:
- 与基础分支比较: 基础分支的部署与分支的本地构建并列,用于并排比较用例。
- 本地构建无法显示的内容: 关于部署本身的用例,例如构建产物、缓存或包裹部署站点的原生应用。在此类用例之前,请检查工作树是干净的且已推送,并且部署服务于该提交,并在用例中说明。
- 当无法本地构建应用时的备选方案。 在计划顶部说明原因,并说明部署服务的是哪个提交以及工作树中缺少的内容。
计划使用的任何部署环境同样适用此规则:暂存部署,绝不能是生产部署。如果分支同时有暂存和生产部署,计划中只提供暂存URL。
确定测试内容
-
列出用户可以看到或操作的不同之处。 将差异中的每个变更向外追踪到展示它的屏幕和流程。共享代码中的变更会影响到使用它的每个屏幕;搜索调用方并全部列出,包括分支不相关的调用方。
-
对每个不同之处,决定是否需要运行的应用。 询问代码测试是否可以确定它。如果已经有一个,则排除。如果可以轻松添加(纯函数、解码器、排序顺序、给定状态下的视图函数、状态转换),则从用例中排除,并将其放入待编写测试列表;这样该检查每次变更都会自动运行,而应用中的用例每次都需要付费。只保留代码测试无法达到或不可信的内容:来自真实后端的真实数据如何呈现、在真实浏览器中如何渲染和布局、分别测试的部分如何结合运行、真实请求的时序和顺序、真实导航后的应用状态,以及辅助技术提供的内容。
-
找出状态。 对每个屏幕,阅读代码中的分支:加载中、已加载、空、错误、丢失或部分数据、零和负值、非常长的值、单个项目和多个项目、每个改变显示的设置或模式、每个账户或用户类型。保留差异触及的状态。
-
确定如何达到每个状态。 命名导航路径,通过其形状描述所需数据(“在两个账户中持有的工具,其中一个没有购买成本”),而不是通过你未确认存在的账户。如果某个状态难以通过真实数据达到,说明如何生成(功能标记、重写响应、限速网络、设置),或标记为需要特定的测试账户。
当用例依赖于重写的响应时,计划必须使重写可重复;
reference/mocks.md说明了方法。为每个用例提供一种不依赖账户数据运气的方式。如果真实数据可能缺少该状态,请在应用中命名开启它的控件(设置、切换、另一个账户)
…
[为翻译截断]