Actual Budget Bug 修复 PR 浏览器验证手册edge 复现 预览环境确认的闭环流程【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual导读本文基于 Actual Budget 仓库中 review-actual-pr 技能 的配套测试手册系统讲解如何对bug 修复类 Pull Request进行可验证的浏览器测试。核心方法是双环境证据闭环先在线上构建edge.actualbudget.org上复现 bug再在 PR 对应的 Netlify 预览环境中用同一套步骤确认修复生效最终用真值表给出明确结论。读完本文你将掌握从 PR 推导复现计划、使用playwright-cli驱动浏览器取证、处理预览环境失效与 demo 数据不足等边界情况以及在代码审查报告中规范陈述测试结论的完整实战方案。为什么 bug 修复 PR 需要双份证据对于 bug 类 PR测试阶段必须产出两类证据缺一不可修复前 bug 确实存在在edge.actualbudget.org线上 edge 构建上按 PR 描述复现问题修复后 bug 不再出现在 PR 的 Netlify 预览构建上执行同样的复现步骤确认行为已改变。原手册对此给出了两个非常犀利的理由一个看起来正确但实际不改变运行时行为的修复是潜在的回归隐患一个在 edge 上根本复现不出来的 bug说明修复可能是在解决一个幽灵问题。也就是说只看代码 diff 无法证明修复真实有效只复现 bug 也无法证明修复已生效。两者互为印证才能让测试结论具备证据力。这一思路与仓库中 AGENTS.md 所倡导的减少 mock、优先真实实现的测试哲学一脉相承——浏览器测试尽可能在真实构建、真实数据上运行而不是在理想化的测试桩里自说自话。工作流总览与关键常量整套流程分为四步推导复现计划 → edge 复现 → 预览验证 → 结论判定。测试前先固定三个常量常量值说明EDGE_URLhttps://edge.actualbudget.org/线上 edge 构建代表当前主干代码的实际运行行为PREVIEW_URLhttps://deploy-preview-num.demo.actualbudget.org/PR 对应的 Netlify 预览num替换为 PR 编号输出目录~/Downloads/pr-review-num/一次评审的所有截图、元数据、diff 与报告集中存放输出目录与 SKILL.md 中的工作目录约定一致一次完整的 PR 评审会在这个目录下沉淀pr.jsongh pr view元数据、diff.patchgh pr diff、review.md评审报告、before-edge.png与after-preview.pngbug PR 的成对证据截图以及可选的findings.json结构化发现。Step 1 — 从 PR 推导复现计划测试的第一步不是打开浏览器而是先回答一个问题这个 bug 到底怎么触发从 PR 的标题、正文以及关联 issue 中整理出一份有序、具体的操作步骤列表。原手册给出的示例值得借鉴打开 Reports → 点击 Cash Flow → 设置日期范围为上月 → 预期出现图表实际观察到空白画布。对比一下具体与模糊的差别❌ 模糊检查现金流水报表是否正常✅ 具体打开报表 → 点击现金流水 → 设置日期范围为上月 → 预期图表观察空白画布步骤必须具体到可以在真实 UI 中逐步执行。如果 PR 正文提供的信息不足以推导出复现路径则需要抓取关联 issue 的正文# 从 Fixes #1234 / Closes #1234 中提取 issue 编号 ISSUE_NUM... gh issue view $ISSUE_NUM --repo actualbudget/actual --json title,body,labels硬性红线读完整理完关联 issue 后仍然无法得出清晰的复现步骤必须停止测试阶段并告知用户绝不凭空编造一个复现路径。这条禁止伪造复现的规则是整套技能的最高优先级约束之一理由很简单——部分证据比没有证据更糟糕一个编造的复现会让整个评审结论失真。Step 2 — 在 edge 上复现 bug确定复现计划后先在线上 edge 构建上打开应用playwright-cli open $EDGE_URL playwright-cli snapshotplaywright-cli是本仓库评审流程依赖的浏览器自动化命令行工具open打开指定 URLsnapshot输出当前 DOM 的可访问性快照包含元素角色、名称与可点击性后续所有点击都以快照中的引用ref为依据。标准 demo 设置首次进入应用会看到设置onboarding界面。按 AGENTS.md 中 Testing and previewing the app 一节的约定执行标准 demo 初始化点击Dont use a server不连接同步服务器点击View demo加载演示预算。等待预算加载完成后再逐步骤执行复现计划。为什么选择 demo 预算而不是空预算从源码看createDemoBudget会以testMode: true的方式创建一个名为 Demo Budget 的测试预算packages/loot-core/src/server/budgetfiles/app.ts它预置了真实的账户、交易、分类和预算金额数据远比空白预算适合验证报表、交易列表等需要数据支撑的功能路径。该 demo 预算的固定 ID 为_demo-budget并且是多标签页 coordinator 中特殊对待的可驱逐预算组参见 coordinator.ts 对create-demo-budget消息与_demo-budget组驱逐的处理保证重复创建 demo 不会堆积残留状态。仓库 E2E 测试中同样依赖 demo 数据如 onboarding.test.ts 加载ynab4-demo-budget.zip、actual-demo-budget.zip等演示数据文件可见 demo 预置数据是项目测试基础设施的一等公民。逐步骤取证复现计划要一步一快照地推进每执行一步点击后重新snapshot确保下一步点击使用的是新鲜的 DOM 引用页面状态变化后旧 ref 会失效。当走到失败状态时立即截图存证playwright-cli screenshot --filename$HOME/Downloads/pr-review-num/before-edge.png在运行摘要中如实记录bug 是否按描述复现了复现成功继续 Step 3。未复现这是一个重要发现必须在报告中如实说明并停止。可能的原因是该修复属于防御性改动针对的是一条难以触达的路径——这种情况下应把观察到的现象升级给用户判断而不是硬凑结论。demo 数据不足以支撑复现例如 bug 需要多币种环境而 demo 是单币种的同样明确说明并停止绝不伪造。Step 3 — 在预览环境验证修复关闭 edge 页面切换到 PR 的 Netlify 预览playwright-cli close playwright-cli open $PREVIEW_URL playwright-cli snapshot预览环境未就绪的处理如果页面返回 404 或 site not found等待约 10 秒后重载一次即可——Netlify 部署有时会滞后于 GitHub PR 事件。若重试后仍然打不开停止测试在报告中说明预览 URL 无法加载代码审查照常交付只是不含测试章节。绝不降级去测试一个过期构建——那会让修复是否生效的证据完全失效。重复验证流程预览加载成功后重复同样的标准 demo 设置与同样的复现步骤注意两个环境的 demo 数据是一致的因此复现结果可以直接对比这一点在 SKILL.md 的标准 demo 设置一节有明确说明然后截图playwright-cli screenshot --filename$HOME/Downloads/pr-review-num/after-preview.png此时你手上就有了成对的证据before-edge.png修复前 bug 存在与after-preview.png修复后 bug 消失。Step 4 — 判定结论四象限真值表在报告SKILL.md 中定义了完整的报告结构含 Testing 章节中用三行直白的陈述收尾Bug reproduces on edge: yes / noBug reproduces on preview: yes / noVerdict: fix confirmed | fix not observable | repro inconclusive判定逻辑由真值表决定EdgePreview结论yesnofix confirmed修复已确认yesyesfix not observable修复不可观察—— 升级处理nonorepro inconclusive复现无定论—— 说明原因noyesregression回归—— PR 把问题改得更糟了对每种结局的理解yes → no修复确认最理想的结果edge 上出 bug、预览上不出双份证据齐备修复真实改变了运行时行为。yes → yes修复不可观察bug 在两个环境都复现说明修复在真实运行时并未生效——即使代码看起来改对了也要升级处理这正是看起来正确但没改变运行时行为的那类风险。no → no复现无定论两个环境都复现不出必须说明为什么demo 数据不够需要特定前置条件不能含糊带过。no → yes回归罕见但极其重要。edge 上没问题的行为在预览上反而出问题说明 PR 引入了回归。一旦触发此情况必须在代码审查章节同步标记为 Critical。回归象限的存在正是双环境对比的价值所在单环境测试永远无法发现修复方案把原本正常的行为改坏了这类问题。测试实践的三个关键注意事项1. 视觉类 bug 必须统一视口如果 bug 属于视觉问题布局、颜色、对齐两个 URL 都要用相同的视口尺寸playwright-cli resize 1280 800在每次 demo 设置前执行。否则两个环境默认视口尺寸不一致可能掩盖或伪造出差异导致误判。feature PR 手册browser-testing-feature.md同样强调设置一个可呈现的视口如 1440×900可见视口一致性是浏览器测试取证的基础纪律。2. demo 数据可能不够用要如实说明交易列表、报表类 bug 常常依赖足够规模的数据才能暴露。demo 预置数据规模有限如果怀疑数据量不够所以没复现要明确说出来——不要用看起来没问题这种话搪塞因为那意味着你实际上并未真正走通代码路径。这类数据不足导致复现不充分的情况对应真值表中的repro inconclusive必须说明原因。3. 流程边界何时该停何时该继续整个手册贯穿一条决策主线——何时必须停止场景动作无法从 PR 和 issue 推导出复现计划停止测试告知用户bug 在 edge 上未复现可能为防御性修复报告现象停止并升级demo 数据不支持复现所需环境说明并停止不伪造预览 URL 重试后仍不可用停止测试报告 URL 问题代码审查照常交付视觉类 bug 未统一视口重新设置视口后再测停止并升级不是消极逃避而是对证据质量的负责——这条规则与 SKILL.md 的硬性规定绝不伪造复现、绝不向 GitHub 回写任何评论共同构成整套评审技能的可信度基石。与仓库测试基础设施的衔接这套浏览器验证流程并非孤立存在它与仓库既有的测试体系深度衔接E2E 测试仓库在packages/desktop-client/e2e/下用 Playwright 编写了覆盖账户、预算、报表、规则、日程等功能的端到端测试本地运行方式见 AGENTS.mdyarn workspace actual-app/web e2e其中的页面模型如 configuration-page.ts 通过 Try the demo 按钮创建 demo 文件与手册中的 demo 设置流程一一对应视觉回归测试VRTyarn vrt/yarn vrt:docker负责快照级的 UI 回归比对快照存放在各测试文件的*-snapshots/目录下可作为视觉类 bug 的补充证据手段feature PR 流程本文面向 bug PR对于功能/增强型 PR走的是另一套只测预览、带红色虚线高亮标注截图的流程参见 browser-testing-feature.md 与标注脚本 highlight-element.js两套手册共同覆盖了 PR 评审的浏览器测试环节。总结Actual Budget 的 bug 修复 PR 浏览器验证流程本质上是一套以双环境对比为核心的证据闭环从 PR/issue 推导出可执行的复现计划不可伪造在 edge 上确认 bug 真实存在before-edge.png在 Netlify 预览上确认修复生效after-preview.png用四象限真值表给出明确结论并对regression象限保持最高警惕。这套流程的可贵之处在于它把测试从模糊的看看行不行变成了可复现、可取证、可判定的人工验收协议并且为每一类失败场景都预设了明确的停止条件——既保证了评审质量也保护了证据的真实性。对于任何需要验证修复是否真的修好了的 PR 评审场景这套方法都值得直接复用。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考