如何在 Mac 上通过分步截图记录缺陷

只有他人无需再问任何问题，就能根据缺陷报告复现缺陷，这份报告才有用。分步截图可以消除大部分猜测：开发者会按顺序看到你看过的每一个画面。

本文说明可复现的缺陷报告需要包含哪些内容，以及如何使用 Temposhot Action Capture 在 Mac 上记录复现步骤。

下面的示例从头到尾使用同一个案例。某个 Web 应用有一个项目列表，重命名项目后，列表在页面重新加载之前不会更新。该案例使用测试账户，需要 7 个必要操作才能复现，5 次尝试中有 3 次出现缺陷。

先记录运行环境

许多缺陷只在特定版本、特定浏览器或特定账户类型下出现。复现之前先记下运行环境，趁还记得当时的设置时完成记录。

项目	示例
应用或站点版本	构建号，可在 About 窗口或页脚中查看
macOS 版本	来自 About This Mac
Mac 机型和芯片	来自 About This Mac
浏览器及版本	Web 应用从浏览器的 About 页面查看
账户类型或角色	Free、paid、admin、viewer
语言和地区	缺陷涉及文本、日期或货币时记录
日期和时间	附带时区，便于与日志匹配

以文本形式复制这些值。About 窗口的截图是有效证据，但开发者无法搜索图片中的内容。

记录会影响结果的值

并非每个细节对每个缺陷都重要。应记录的是那些一旦不同就可能改变结果的值。以重命名缺陷为例，浏览器版本和账户角色都有影响，因为查看者和编辑者的列表视图缓存方式不同。

快速测试可以找出哪些细节有影响。修改其中一个值（例如浏览器）后再次尝试。如果缺陷消失，将其记为结论，例如：“在桌面浏览器中可复现，在移动端应用中不可复现。”

环境信息放在报告首页

将环境信息块放在报告顶部，位于步骤之前。开发者在决定是否打开附件之前，会先浏览跟踪系统中的标题和开头几行。如果环境信息被埋在 PDF 的第 6 页，开发者可能会换一个浏览器尝试，然后报告“无法复现”。

以文本形式附上日志和控制台输出

对于 Web 应用，浏览器控制台通常会在故障发生时显示错误。将错误行以文本形式复制，粘贴到环境信息块下方。控制台截图可以作为补充，但开发者需要文本才能在代码库中搜索该错误信息。

只保留故障附近的几行。一份 400 行的控制台输出中只有一条相关错误时，读者需要自行查找。记下错误发生的时间，以便与尝试日志对应。

对于 Mac 应用，对应的内容是崩溃报告或错误对话框。原样复制对话框文本，包括错误代码，并在运行期间使用手动快捷键截取该对话框。

写明预期结果和实际结果

两句简短的描述即可概括整份报告：

• 预期结果： “选择 Save 后，列表中会出现新名称。”
• 实际结果： “选择 Save 后，列表仍显示旧名称。重新加载页面后，显示新名称。”

描述你观察到的现象，而不是你认为的原因。“列表没有刷新”是观察结果。“缓存坏了”是猜测。

只写观察结果，不写诊断

缺陷报告中的诊断会把开发者引向错误的位置。如果真正的原因是缺少事件而不是缓存，“缓存坏了”会浪费排查时间。观察结果是任何人都能在屏幕上核对的内容。

将变通方法作为事实记录，不作为严重程度的判断。严重程度由分诊该报告的团队决定。

从已知的起始状态开始复现

如果报告以“打开应用”开始，而你当时已处于一段会话的深处，报告就隐藏了真实的操作环境。应从任何人都能到达的状态开始：全新登录、新建项目或指定的 URL。

录制前至少复现两次。如果缺陷只是偶尔出现，记下出现的频率，例如“5 次尝试中有 3 次”。

搭建起始状态

对于重命名缺陷，起始状态是停留在登录页面的已退出登录的浏览器窗口。先退出登录可以清除之前的会话，使开发者与报告人从同一位置开始。

记录每次尝试

间歇性缺陷需要一份简短的尝试日志。记下每次尝试的时间以及是否失败，方便开发者将尝试与服务器日志对应。通常 5 次尝试即可得出出现频率。

将路径缩减到最少步骤

最先出现缺陷的路径通常不是最短的。录制前，每次删除一个操作，并检查缺陷是否仍会出现。在示例中，重命名之前打开项目详情是不必要的，因此路径从 9 个操作减少到 7 个。

较短的路径有两个好处。开发者在每次复现上花费的时间更少，操作越少，读者可能走错分支的地方也越少。当删除任何剩余操作都会导致缺陷消失时，停止缩减。

如果录制期间缺陷没有出现，仍保留录制。重复最后几个操作，在故障出现时按下手动快捷键。即使是通过的运行，只要能展示准确的路径，录制仍有价值。

为每个必要操作截取一张截图

1. 打开 Action Capture

   按下 Command+3，然后选择 Start Action Capture。如果步骤只涉及一个应用，选择 Specific Window；如果步骤跨越多个应用，选择 Active Window。

2. 执行步骤

   每次有效点击都会在点击前保存窗口，因此每个页面都会在你操作之前显示对应的控件。

3. 捕获故障

   出现错误结果时，按下 Shift+Command+2，或选择浮动工具栏中的 Capture now。故障画面通常无需点击即可出现。

4. 结束捕获

   选择 Finish capture。文档会在编辑器中打开，每个步骤对应一页。

开启 Parse clicked elements 后，页面标题会以 Click "[[element-name]]" 开头。在 Visual Annotations 下开启 Show cursor on click captures 和 Mark clicked area，使每个页面显示点击位置。如果缺陷出现在 Temposhot 自身，开启 Include toolbar in captures，使浮动工具栏出现在步骤截图中。

一次性配置运行设置

在 Configure Action Capture 中的设置会保存在 Mac 上，并在之后的运行中重复使用。为缺陷报告配置的设置会保留到下一次报告。

对于单个浏览器窗口内的缺陷，选择 Specific Window。此时发生在其他窗口的点击会被忽略，除非开启了 Capture outside clicks。当复现过程在应用之间切换时，例如从邮件链接跳转到浏览器，选择 Active Window。

将运行控制在步骤上限内

免费版每次 Action Capture 运行的步骤上限为 5 步。重命名缺陷需要 7 个必要操作加上故障画面，因此免费版运行会在第 5 步后暂停。已保存的步骤会保留在本次运行中。

有两种处理方法。在自然断点处（例如登录之后）将复现拆分为两次运行，并将第二次运行添加到同一个文档中。或者激活 Temposhot Pro，取消该限制，使一次运行即可覆盖所有步骤。

运行期间使用键盘

在复现过程中保持双手在键盘上，可以避免额外的点击产生多余的页面。下表列出运行过程和之后编辑所用的快捷键。

Temposhot 会忽略间隔过近的连续点击。双击列表项只生成一个步骤，而不是两个。

运行漏掉点击时

保存的步骤少于预期时，常见原因有以下几种。重新录制前，按此顺序逐一检查。

• 浮动工具栏显示 Paused。选择 Resume capture。暂停期间的点击不会被保存。
• 目标为 Specific Window，而点击落在了另一个窗口中。在目标窗口内点击，或开启 Capture outside clicks。
• Mouse click capture 设置为需要或跳过按住某个键的模式。为缺陷报告，将其改回 Capture every mouse click。
• 缺少辅助功能权限。Permissions Required 中的 Screen Recording 和 Accessibility 必须都显示 Granted。

如果解析出的标题全部为 Click here，说明目标应用几乎不向辅助功能接口提供控件数据。步骤仍会被保存，只是标题需要手动改写。

添加说明状态变化的文字

截图展示的是画面，但不一定展示画面之间发生了什么变化。使用 Page description 说明这一点，例如：“这里计数器应显示 4，实际显示 3。”

在故障页面上，用 Rectangle（R）围绕错误的值，并用 Text（T）添加标注预期值的文字标签。删除因误点产生的页面，使序列中只包含必要操作。将标题改写为简单的步骤，例如“选择 Save”。编辑器指南列出了所有工具和快捷键。

清理示例运行

重命名运行录制的结果为 9 个页面。其中一页来自点击列表中的空白区域，另一页来自点击浏览器地址栏。这两页被删除，保留了通过手动快捷键拍摄的故障页面，最终得到 7 个操作页面和 1 个故障页面。

解析出的标题只是起点。Click "Rename" 应改写为“在项目菜单中选择 Rename”，这样也说明了控件的位置。解析器无法获取名称的页面会显示 Click here，这些页面必须改写。

状态变化的描述模式

三种简短的句式可以覆盖缺陷报告中的大多数页面描述。“此步骤之前，列表显示 12 个项目”记录起始值。“输入后等待 2 秒”记录截图无法体现的时序信息。“此处列表应显示 Q3 Budget”记录故障页面上的预期状态。

每段描述控制在一到两句。描述过长会把截图推到 PDF 的下方。当描述设置为 Before image 时，读者会先看到文字。

标注故障页面

故障页面承载的信息最多，因此标注也最多。通常在旧名称周围画一个矩形，并添加一个标注新名称的文字标签即可。单个页面上的标注超过 3 处，会使错误的值更难找到。

当大窗口中的列表较小时，可在故障页面上使用 Framing，级别选择 Close（级别 4）。源图像保持不变。如果开发者需要完整上下文，Show full image 可以恢复完整图像。

保护隐私信息

缺陷报告会被复制到跟踪系统、聊天线程和供应商工单中。应将每张截图视为组织内部公开的内容。

• 尽可能使用测试账户和示例数据复现。
• 使用 Framing（F）和 Custom 裁掉侧边栏、浏览器标签页和通知。
• 使用 Blur（B，Pro）模糊名称、电子邮件地址、令牌和 ID。
• 粘贴任何 URL 或日志文本前，删除其中的会话令牌和 API 密钥。

按导出尺寸检查每一页

在 50% 缩放比例下，画布上看不清的模糊内容，在完整尺寸下可能仍然可读。在 Object Inspector 中，将 Blur strength 设置为文字无法辨认的值。默认值为 12，取值范围为 2 至 80。然后在发送前逐页检查导出预览。

浏览器地址栏中的 URL 是常见的泄露来源。分享链接或重置令牌出现在地址栏中时，会出现在基于浏览器的复现的每一页上，因此应使用取景裁剪或模糊处理每一页上的地址栏。

使用此缺陷报告结构

1. 标题： 什么功能失败，在哪里失败。例如“重命名后的条目在列表视图中未更新。”
2. 环境： 上文表格中的各项值。
3. 复现步骤： 按编号列出，从已知状态开始。
4. 预期结果和实际结果。
5. 频率： 始终出现，或说明出现的频率。
6. 证据： 导出的截图指南，以及以文本形式提供的日志或控制台错误。
7. 变通方法： 如果存在。

在文档中点击 Export PDF 可导出单个附件，点击 More export formats 可导出跟踪系统中可直接内嵌显示的 PNG 页面。图片文件名跟随页面标题。导出指南列出了所有格式。

根据跟踪系统选择导出格式

不同的跟踪系统显示附件的方式不同。当跟踪系统在问题正文中预览图片时，内嵌的 PNG 页面有效，开发者无需打开文件即可阅读步骤。当跟踪系统只列出附件，或报告需要发送给外部供应商时，单个 PDF 更合适。

ZIP package 格式将渲染后的 PNG 页面和一个 document.json 文件保存在同一个压缩包中。它适用于只接受一个文件、并且同时需要图片和页面文本的供应商工单。

填写完成的示例

重命名缺陷报告在跟踪系统中的内容如下。标题为“重命名后的项目在页面重新加载前，在项目列表中保留旧名称。”环境块列出构建号、macOS 版本、浏览器版本、角色 editor，以及 14:02 至 14:20 之间的尝试时间。

步骤为 7 行编号列表，从“以 qa-editor 身份登录”到“关闭重命名对话框”。预期结果和实际结果与前文的两句相同，频率为“5 次尝试中有 3 次”。证据是一份 8 页的 PDF，变通方法为“重新加载页面”。

该 PDF 使用默认导出设置：纸张为 A4、横向，开启封面页、步骤编号和页码，描述位于图片之前。自定义这些设置需要 Temposhot Pro。默认设置已适用于缺陷报告。

同时以文本形式写出步骤

即使 PDF 中已包含步骤，也应将编号步骤以文本形式粘贴到问题正文中。文本步骤可以搜索、在评论中引用，也可以复制到测试用例中。此时截图是每个步骤的证据，而不是唯一的记录。

发送前测试报告

从头到尾阅读报告，假设自己从未见过这个缺陷。更好的做法是请同事在他的 Mac 上按照报告操作。如果同事无需提问即可复现缺陷，说明报告已经可用。

试运行中发现的常见缺漏

同事的试运行通常会发现以下三类缺漏之一。第一类是缺少起始状态，例如必须已经存在的项目。第二类是某个步骤没有点击却发生了，例如键盘快捷键，因而没有对应页面。第三类是故障依赖于时序，例如在输入后不到 2 秒选择 Save。

在第一步中补充缺失的状态，为使用手动快捷键的键盘操作添加页面，并在页面描述中写明时序。然后重新进行试运行。

保留源文档

导出后，文档仍可编辑。如果开发者需要再加一张截图，打开文档，使用 Capture new images… 添加页面，然后重新导出。已导出的文件不会自动更新。

常见问题

缺陷报告应包含视频还是截图？

截图适用于大多数缺陷，便于浏览和标注。视频适用于时序问题和动画。参见分步截图指南与屏幕录制的对比。

缺陷报告需要多少张截图？

每个必要操作一张，外加一张故障画面。删除不会改变结果的页面。

发送报告后，截图保存在哪里？

文档保存在你的 Mac 上。Temposhot 没有托管链接，因此需要将导出的文件附加到问题跟踪系统或工单中。

免费版复现需要超过 5 个步骤时怎么办？

运行会在步骤上限处暂停，并保留已保存的步骤。将复现拆分为两次运行，并将两次运行都添加到同一个文档中；或使用 Temposhot Pro 录制超出上限的步骤。

无需点击即可出现的缺陷能否捕获？

可以。错误状态出现时，按下手动捕获快捷键，默认为 Shift+Command+2。该步骤会在无点击的情况下保存。如果已配置点击标记设置，则会应用该设置。

将点击转换为清晰的分步指南

Action Capture 会在你执行复现步骤时记录这些步骤，并附带点击标记和草稿标题。下载 Temposhot，然后将下一份缺陷报告作为有序指南附上。