如何让你的编程工具在浏览器中检测其运行效果

这并不是一份针对初学者的教程，因此以下准备是必要的：

• 需要具备使用支持MCP（模型上下文协议）的编码工具的经验，例如Claude Code、Codex或Cursor，并且要了解如何向这些工具发出指令。

• 需要一个可以通过JavaScript或TypeScript编写的开发脚本在本地运行的Web应用。示例中使用了基于pnpm的Node项目，但实际使用过程中并不依赖任何特定的框架。

• 需要具备基本的Playwright基础知识，了解测试、定位器以及断言的概念。在学习前半部分内容时，并不需要预先准备现有的测试套件。

• 如果想要使用Playwright的MCP功能，需要Node.js 20或更高版本；如果还想安装katalepsis插件，则需要Node.js 22.12或更高版本以及Git。

• 需要熟悉终端命令和Git操作，因为编码工具会自动启动进程并执行git status等命令。

循环代理缺失的问题

编码工具之所以能迅速发挥重要作用，很大程度上是因为它们已经具备了完善的代码反馈机制：这些工具可以读取、编辑代码，运行格式化工具和测试用例，分析错误结果并重新尝试执行操作。因此，人们并不需要一次性就完成所有工作。

对于前端开发来说，目前明显缺失的是一个能够实现这种循环流程的工具。我理想中的循环流程应该是这样的：修改代码后运行测试，启动应用程序，使用新功能查看效果，发现问题后进行修复，然后再重新使用该功能。

最后这一步的重要性可能超乎你的想象。编码工具虽然可以告诉你“修复后的代码应该能够正常工作”，但我更希望它们能直接打开页面来验证这一结论是否正确。

Playwright的MCP功能正好可以实现这一点。我之前已经使用Playwright进行过端到端测试，而MCP服务器的另一个重要作用在于：它可以直接将浏览器交给编码工具使用。该服务器可以打开本地主机页面，查找控件元素，执行点击和输入操作，检查代码变化情况，并生成截图。

这与让编码工具运行pnpm playwright test是不同的。测试套件只会告诉你之前编写好的测试用例是否仍然能够通过，而MCP功能则会具体分析某项修改会对系统产生哪些影响。

如果编码工具对某些通用的地图层功能进行了重构，那么相关的测试用例可能会覆盖其中的一些辅助函数。但通过代码差异分析，还可以发现这些改动实际上会影响页面在初始渲染、元素选择、过滤以及重置等各个阶段的运行情况，因此编码工具会针对这些环节进行逐一测试。这种测试方式与我自己审查前端代码的方式非常相似。

设置过程相当简单，你只需要安装Node.js 20或更高版本，以及一个支持MCP功能的客户端工具即可：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

一个简单的验证方法就是让编码工具打开Playwright的TodoMVC演示页面，添加一个名为“浏览器质量测试”的待办事项，然后确认这个待办事项确实能够正常显示。如果它能完成这个操作，那就说明它具备使用浏览器的能力。接下来要做的就是看看它如何利用这些浏览器功能了。

为什么单独使用的浏览器会存在局限性

第二条规则是检查最终结果，而不是交互过程本身。“我点击了‘重置’按钮，但什么变化也没有发生”这样的描述并不能提供太多有用的信息。你真正关心的是：重置操作是否真的把各项设置恢复到了原来的状态。保存设置也是如此——关键在于确认在更改设置并保存后，重新加载页面时这些设置仍然存在。

如果用测试用例来表述这一规则，那么代码会像这样写：其中最重要的一行是在页面重新加载之后的那部分代码：

代理程序不需要编写这样的测试用例来遵守这一规则。通过MCP，它也可以手动完成相同的操作：点击按钮、保存设置，然后重新加载页面，并从新的页面状态中判断开关选项是否仍然处于启用状态。

根据不同的需求，我也会要求提供不同类型的证据。例如，需要检查URL是否发生了变化、某个按钮是否被禁用，或者是否有对话框弹出——这些都需要通过分析DOM结构和浏览器状态来确定，而截图并不能满足这些需求。另外，如果需要判断某个对话框是否被截取了、两个元素是否重叠了，或者文本在手机屏幕上显示的效果如何，这时截图就非常有用。不过有时候，这两种方法都是必要的，因为有些模态窗口在DOM结构中是存在的，但在屏幕上可能无法正常显示。

对于布局上的变化来说，就需要调整页面的大小，并捕捉用户实际看到的界面效果：

在测试过程中，代理程序还可以查看控制台日志；如果某个功能需要调用API或进行网络请求，那么也可以检查相关的网络请求记录。不过我只需要关注那些由这次变更所引发的错误而已。例如，如果一个已经存在了六个月的警告信息并不会影响整个测试流程；而对于仅对客户端生效的变更，则不需要进行网络性能测试。如果某个本应能够成功保存设置的操作实际上导致了“500 Internal Server Error”这样的错误，那我肯定需要知道这一点。

browser_console_messages和browser_network_requests这两个函数可以用来查看页面输出的信息以及发起的网络请求记录。因此，即使用户界面看起来没有问题，但如果保存操作失败了，也会在日志中显示相应的错误信息：

综合这些规则，就能把这一节开头那些模糊不清的测试要求转化为具体可执行的操作步骤了：

通过这些步骤，我就能够有效地验证这个功能是否按照预期工作了。

如何启动真实应用

在应用真正运行之前，代理程序根本无法进行任何测试，而正是在这种情况下，它最容易选择走捷径。

我并不想在每个代码仓库中都写“运行 `pnpm dev`”这样的指令，因此这套流程要求代理程序自行判断如何启动项目。它会首先检查 `package.json` 文件中的 `dev` 脚本，然后参考 `README` 文档中的说明；只有当其他方法都无法让应用正常运行时，才会选择使用现有的 Docker 配置来启动应用。

这套流程实际上就是 “浏览器评审” 功能中 “启动应用程序” 部分的具体实现方式，你将在下一节中看到完整的示例。在典型的 Vite 或 Next.js 项目中，按照这个流程操作，代码会看起来像这样：

# 1. 这个项目是如何启动的？
jq .scripts package.json
# {
#   "dev": "vite",
#   "build": "vite build",
#   "test": "vitest run",
#   "e2e": "playwright test"
# }

# 2. 在代理程序拥有的临时文件夹中，后台启动开发服务器，并记录其进程 ID，以便日后能精确地终止该进程。
QA_DIR=$(mktemp -d)
pnpm dev --port 5173 > "$QA_DIR/dev.log" 2>&1 & &
echo $! > "$QA_DIR/dev.pid"

# 3. 等待服务器启动成功后，再打开浏览器。
until curl -sf http://localhost:5173 > /dev/null; do sleep 1; done

如果项目中没有 `dev` 脚本，就会查看 `README` 文件；而如果 `README` 中说明应用需要通过 `docker compose up` 来启动 Postgres 和 Redis，代理程序就会使用该配置文件来创建相应的容器，并记录这些容器的信息。它不会重新编写配置文件。

我真正不希望看到的是代理程序为了方便测试而对应用程序进行任何修改：不允许使用临时身份验证绕过机制，不允许搭建虚假服务器，也不允许更改 `.env` 文件中的配置，更不允许因为无法确定正确的配置方式而创建一些临时路由。我们的目标应该是测试我实际要发布的软件本身。

比如下面这种修改，当登录页面成为测试障碍时，代理程序确实会倾向于这样做：

- if (!session) redirect("/login");
+ if (!session && process.env.NODE_ENV !== "development") redirect("/login");

如果代理程序使用项目文档中规定的测试账户或初始数据无法通过身份验证，正确的做法应该是立即停止操作，并报告该浏览器评审被阻断的原因。如实反映问题才是负责任的做法；而如果关闭了应用程序的身份验证机制再进行评审，那根本就不算是对真正应用的评估。

说明文件的存放位置

起初，我考虑的是继续在 `AGENTS.md` 文件中添加相关内容。这个文件已经包含了仓库中所有代理程序都应该了解的规则：代码结构、编码规范、测试理念、如何进行最小限度的修改，以及禁止编写无意义的注释。

我本来还打算再添加上百行内容，介绍如何启动应用、如何配置浏览器环境、需要点击哪些按钮、应该截图哪些界面、如何查看控制台错误信息以及如何关闭应用程序……但到了某个阶段，这个文件就会不再仅仅是指导说明，而变成了一篇冗长繁琐的文档。

“技能”文件的处理方式则有所不同。这类文件是一个文件夹，其中包含一个以简短的名称和描述开头的SKILL.md文件。在会话开始时，助手只会看到这些名称和描述，每个技能只会有一两行相关内容。当某个任务与描述相符，或者有其他指令指定了需要使用某个技能时，助手才会读取文件的其余部分并按照其中的指示来执行操作。因此，你可以编写一份详细的长流程文件，而在实际需要的时候才将其加载出来。

我最终得出的结论是：将AGENTS.md视为“章程”，而将技能文件视为“操作手册”。章程内容简短，适用于所有情况，它规定了必须遵守的基本规则，但不会详细说明具体操作方法；而操作手册则是针对特定情况制定的逐步指导流程，只有当遇到这种情况时才会被使用。

在这种配置下，AGENTS.md明确规定：用户可见的修改内容必须在浏览器中经过验证后才能被视为完成；而“browser-review”技能文件则详细说明了如何进行这种验证：

/
├── AGENTS.md
└── .agents/
    └── skills/
        ├── browser-review/
        │   └── SKILL.md
        ├── pr-review/
        │   └── SKILL.md
        └── grill-me/
            └── SKILL.md

AGENTS.md中的规则表述简洁明了，且始终处于可见状态：

## 浏览器验证

用户可见的修改内容必须在运行中的应用程序中经过验证后才能被视为完成。

对于涉及用户界面变更的任务，请参考`.agents/skills/browser-review/SKILL.md`文件。

成功的构建测试、类型检查、单元测试或端到端测试并不能替代浏览器验证。

请不要提交与浏览器验证相关的结果文件。在进行验证之前，务必停止所有相关操作并完成清理工作。

技能文件中包含了具体的操作步骤，只有在实际需要时才会被加载。我使用的是Codex和Claude Code，因此系统中有一个全局的AGENTS.md文件，Claude的CLAUDE.md会导入这个文件；同时还有一个共享的技能文件夹，这两个工具都会读取其中的内容。无论那天我使用哪个助手，它都会遵循相同的操作流程。

导入语句只需要一行代码，因为Claude Code允许CLAUDE.md通过@符号来引用另一个文件：

@~/.codex/AGENTS.md

以下是我最初编写的内容的简化版本：

---
名称：浏览器测试
描述：使用Playwright MCP来验证运行中的应用程序中那些对用户可见的变更。

---

# 浏览器测试

## 在开始测试之前

运行`git status --short`，记住之前存在哪些文件和目录。不要修改任何已存在的代码或配置。

仔细阅读测试任务和相关差异信息，弄清楚哪些路由受到了影响，数据流发生了怎样的变化，以及页面在加载、为空、出现错误、被选中或被禁用时的状态会发生什么变化；同时也要判断是否有某些内容需要在页面刷新后依然保持不变，还有哪些附近的功能可能会因此出现异常。

## 启动应用程序

首先使用仓库提供的开发脚本进行初始化设置，然后按照文档中的说明进行本地环境的配置，最后使用现有的Docker环境来运行应用程序。不要自行创建新的启动配置文件，也不要为了方便测试而修改应用程序的行为。请记录下你启动的所有进程和容器。

## 测试变更内容

页面加载完成后，不要立即停止测试流程。要完整地执行整个变更后的操作流程，并检查最终的结果。对于功能方面的验证，可以使用浏览器或DOM的状态来进行判断；而对于视觉方面的问题，则需要通过截图来确认。请及时报告任何新的错误信息或失败的请求，而不要忽略那些旧的警告信息。

如果发现某个功能出现了故障，请先修复导致问题的最小原因，然后重新运行相关的测试，并再次检查整个操作流程。千万不要想当然地认为修复后的代码就能正常工作。

## 清理测试环境

即使测试失败，也必须进行环境清理。关闭所有浏览器，停止服务器和容器的运行，并删除生成的截图、日志文件以及其他测试产生的残留文件，但请只删除你自己创建的这些文件。在完成清理工作之前，请再次运行`git status --short`命令。绝对不要执行`git add`、`git commit`或`git push`等操作。

## 提交测试结果

请详细说明你测试了哪些路由，进行了哪些操作，检查了哪些状态，运行了哪些测试，以及发现了什么问题并如何进行了修复。如果无法完成全部测试，请说明原因。

这些做法其实都并不高明。关键在于，这种行为本身就是人们的默认预期，因此我并不指望代理程序能够自行判断是否应该打开浏览器来执行相关操作。

为什么审核者应该独立工作

明显的缺陷在于：负责判断代码是否完成工作的代理程序，恰恰就是编写该代码的同一個程序。虽然这种做法还是有一定价值的——毕竟我也会自己测试自己的代码——但问题在于，这种测试方式是基于开发者对代码实现原理的理解来进行的。

这里所说的“原理”，指的是开发者对自己所修改的代码的认知：他们知道修改了哪些代码，认为这些代码会带来什么影响，同样重要的是，也明白哪些代码没有受到影响。他们的测试计划正是基于这种认知制定的。因此，他们会只测试那些他们原本打算修改的部分，而完全不会去检查那些他们没有意识到会被影响的代码路径。这就是人们在自己测试代码时常常会犯的错误，而那些在审核过程中被遗漏的漏洞，往往就隐藏在这些被忽略的地方。

因此，当第二个代理程序来审核某个分支代码时，我会要求它自行确定测试范围。我现在制定的全局规则要求使用一个没有之前交流记录的新审核者：这个审核者只会收到原始请求、代码差异文件以及相关的审核工具，而不会了解到开发者认为代码为何能够正常工作。审核者需要自己判断这些修改可能会对代码产生哪些影响，并据此进行测试，而不能依赖开发者的截图、质量保证笔记或测试结果。

为这个审核者准备的提示信息被刻意设计得非常简短：

你正在审核一个并非你自己编写的代码分支。

原始请求：
  需要将端到端应用的URL设置为可以通过E2E_BASE_URL来配置，这样测试就可以在任何端口上运行。

请执行`git diff main...HEAD`命令查看代码变更内容。按照“浏览器审核”指南进行操作，自行判断这些变更可能会对代码产生哪些影响，然后进行测试，并用证据支持你的判断结果。

迄今为止，最有效的发现来自于一个将端到端测试配置中的应用URL设置为可配置的Pull Request。审核者注意到，那些预先设置好的测试数据中，图像文件的URL仍然被硬编码为旧的端口地址，而在其他端口上运行应用程序后，这个问题确实得到了验证：有三条请求发送到了错误的端口，导致请求失败；而页面上则显示了备用图片。这个错误完全没有引起任何警报或异常。

简单来说，修改后的全局配置文件内容如下：

// e2e/global-setup.ts
const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:8080";

await seedDatabase({
  media: [
    { id: "m1", url: "http://localhost:8080/test-media/cover-1.jpg" },
    { id: "m2", url: "http://localhost:8080/test-media/cover-2.jpg" },
    { id: "m3", url: "http://localhost:8080/test-media/cover-3.jpg" },
  ],
});

开发者的理解是“应用URL现在是由E2E_BASE_URL决定的”，因此他运行的所有测试都使用了默认端口，而那些被硬编码的URL地址恰好也是正确的。但审核者并没有这种先入为主的观念。他仔细阅读了所有被修改过的配置文件内容，在8081端口上运行了应用程序，最终得出了不同的结论。

发现：在 e2e/global-setup.ts 文件中，那些用于初始化的媒体资源链接仍然指向 :8080 这个端口。  
将 E2E_BASE_URL 设置为 http://localhost:8081 后运行应用程序，结果有 3 次请求到 http://localhost:8080/test-media/... 的操作失败了，错误原因是 net::ERR_CONNECTION_REFUSED。  
在页面上显示时，图库显示的是 3 张备用图片，而不是实际的媒体文件（例如 gallery-8081.png）。  
建议的解决方法是将这些初始化链接根据 E2E_BASE_URL 进行重新生成，或者让它们成为相对路径。

为了解决这个问题，我们只需要为每个链接添加一行代码即可：

{ id: "m1", url: new URL("/test-media/cover-1.jpg", baseURL).href },

进行测试后发现，无论采用哪种方法，检查这些卡片是否存在的结果都是正确的，因为备用图片同样属于“卡片”这一类别。只有通过查看页面以及网络浏览器的记录，才能发现这个差异——而这正是本文所要讨论的内容。

自己完成清理工作

一旦代理程序能够启动服务器和浏览器，那么进行清理工作就成为了设计流程中必不可少的一部分。否则，每次会话结束后都会留下一些残留物：比如未关闭的节点进程、Chromium 浏览器窗口、截图文件、Playwright 的运行记录、临时生成的认证文件，或者 Docker 容器等等。

不过，“把所有东西都清理干净”这种做法其实是错误的。pkill node 这条命令并不能算作真正的清理操作，它只会终止正在运行的节点进程；而 git clean -fd 则会删除那些与代理程序无关的、未被跟踪的文件。

正确的原则是：只清理你自己创建的东西，其他东西一律不要动。在清理前后使用 git status 命令来检查文件状态，这样就可以确保浏览器测试过程中产生的任何更改不会被无意中加入到代码库中。

# 不进行清理操作
pkill node
git clean -fd

# 进行清理操作
kill "$(cat "$QA_DIR/dev.pid")"
rm -rf "$QA_DIR"

在完成清理工作后，我期望看到的结果应该是这样的：

清理结果：
- 我启动的开发服务器已经停止运行（进程 ID 为 48213，使用命令 pnpm dev --port 5173 来终止它）。
- Playwright 的 MCP 浏览器也已经关闭。
- 文件 export-dialog-375.png 和 export-dialog-1440.png 已被删除。
- 目前仍在运行的进程是 pid 39102，它是通过 pnpm dev 在端口 :3000 上启动的，这个进程在我开始清理操作之前就已经在运行了，所以它并不属于我创建的进程。

两次使用 git status 命令检查后的结果是一样的，这说明在清理过程中没有任何错误发生，那些原本就存在的未跟踪文件也没有被删除。

这个规则也不是我凭空想出来的。在开发我即将介绍的这个工具时，用于测试该工具的代理程序自动执行了清理操作，它关闭了我机器上所有的 Playwright 浏览器窗口，而不仅仅是它自己使用的那个浏览器。公平地说，该代理程序在它的运行总结中确实提到了这一点。

当某项技能不再足够使用时

这个工具确实起到了预期的效果，因为代理程序确实会打开相应的应用程序。但我得到的结果仍然只是文字描述而已。代理程序会告诉我它已经打开了页面、按照流程进行了操作，一切看起来都正常，而我只能相信它的说法。

这其实就是我最初遇到的那个问题，只不过程度更严重了一些。我并不想要关于浏览器表现的漂亮描述，而是需要实实在在的证据：哪些操作成功了，哪些失败了，同时还需要有截图和运行记录作为支撑，这样我就可以把这些资料提交给审核人员。