How can you make your coding agent verify its work in the browser?
Playwright MCP lets coding agents review real browser behavior after frontend changes, reducing false completions.
Key Takeaways
- Passing tests do not guarantee correct UI behavior, so frontend changes should be verified in a real browser.
- Playwright MCP enables coding agents to open pages, interact with controls, inspect changes, and collect visual evidence.
- Effective browser review must be based on the actual code change, using a short plan to test affected features.
- Verification should check end results, such as state persistence or UI updates after reload, not just successful interactions.
Meta description: Learn how Playwright browser review makes coding agents verify frontend changes, start real apps, separate reviewers, and use katalepsis for evidence.
Tags: Playwright, coding agents, frontend testing, katalepsis, browser review
Featured image: abstract friendly illustration of a browser window reviewing a frontend change, no people, no logos, no text
For developers who use coding agents such as Claude Code, Codex, or Cursor on web applications written in JavaScript or TypeScript, browser review with Playwright MCP can close the gap between green tests and a usable interface. The workflow asks the agent to start the real app, use the feature it just changed, capture the evidence, and only then call the work done. For user-facing changes, that makes browser review part of the definition of done. The author of the original article turned this habit into an open-source tool called katalepsis.
Passing Tests Do Not Prove UI Behavior
The routine is familiar: the agent edits code, runs the formatter, checks types, runs tests, sees that everything passes, and reports that the change is complete. That feedback loop is strong for code, but it stops short of the user-facing layer.
The original article lists several frontend problems that passed tests yet remain obvious to a person in seconds: a control overlapping another element, a selected state that is present in application state but not highlighted on screen, reset working on one path but not another, a filter updating state while leaving old data visible, a save that appears fine until the page is refreshed, a map layer drawn in the wrong order, and a modal that opens but does not fit the viewport.
These are not edge cases created for drama. They are the kind of defects that appear when code logic and UI behavior diverge. A test suite can prove that the code still satisfies written assertions, but it cannot prove that the changed screen behaves as a user expects.
Playwright MCP Adds Browser Evidence
Playwright MCP is a Model Context Protocol server that gives a compatible coding agent direct access to a browser. The agent can open a local page, read the page structure, find controls, click, type, inspect what changed, and take screenshots.
The setup is small. It requires Node.js 20 or newer and a client that supports the Model Context Protocol. The examples use a Node project with pnpm, but nothing depends on a specific framework. The server can be added with:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
A simple sanity check is to ask the agent to open the Playwright TodoMVC demo, add a todo, and confirm that the new item appears. That proves the agent can drive a browser. The harder part is making it do useful review.
This is not the same as asking the agent to run pnpm playwright test. An end-to-end test suite answers whether scenarios that were already written still pass. Browser review asks a different question: what could this particular change affect, and what does the application actually do after that change?
In a map-layer example, unit tests may cover a few shared utilities, but the agent can read the diff, infer that the code runs during initial render, selection, filtering, and reset, and then try each of those paths in the browser. That is closer to how a careful frontend developer reviews their own change.
Browser Review Needs a Change-Based Plan
Giving the agent a browser only gives it the ability to look. Without instructions, it may return the weakest possible report: open a route, see that the page loaded, and call verification complete. That report would not catch any of the bugs listed earlier.
The first rule is that the review must come from the change. If the change touched a filter, the agent should use the filter. If it touched reset logic, the agent should create a state first and then reset it. If it touched persistence, the agent should refresh the page. If it changed a modal, the agent should open and close it. If it changed responsive layout, the agent should resize the viewport.
That sounds obvious when a human says it, but it is not obvious when the instruction only says to verify that the app works. In practice, the agent should read the diff and write a short plan before touching the browser. It helps to know what a test, a locator, and an assertion mean, but an existing suite is not required for the first pass.
For a filter-bar change in src/features/projects/FilterBar.tsx and src/features/projects/useFilters.ts, a useful plan could be:
- Open /projects and note the number of rows shown.
- Filter by Status: Active and confirm every visible row is Active.
- Add Owner: me and confirm the list narrows again.
- Clear filters and confirm the original row count returns.
- Apply a filter, refresh the page, and confirm the filter survives because it is stored in the page address.
Then the agent executes the plan with Playwright MCP tools. A trimmed call sequence looks like:
browser_navigate { "url": "http://localhost:5173/projects" }
browser_snapshot {} -> table with 40 rows
browser_click { "element": "Status filter", "ref": "e14" }
browser_click { "element": "Active option", "ref": "e31" }
browser_snapshot {} -> table with 12 rows, all "Active"
browser_click { "element": "Clear filters", "ref": "e15" }
browser_snapshot {} -> table with 40 rows
The ref values come from the accessibility snapshot, so the agent can find controls without guessing selectors.
The second rule is to check the end result, not only the interaction. Clicking a reset button and seeing no exception is weak evidence. The claim that matters is that reset restores the prior state. For a setting save, the claim is that a user can change the setting, save, reload, and see the setting still enabled.
A Playwright test for that claim might load the settings page, click the Weekly digest switch, click Save, reload the page, and assert that the switch is still checked. The agent does not need to write that test. Through browser tools it can perform the same steps manually and read the state from a fresh snapshot.
The kind of evidence should match the question. Whether a button is disabled, a dialog opened, or the page address changed is usually a state question. Whether a dialog is clipped, two elements overlap, or text wraps badly on a small screen is a visual question. Sometimes both are needed, because a modal can exist correctly in the page structure while being unusable on screen.
For layout review, the agent can resize to 375 by 812, take a screenshot, then resize to 1440 by 900 and take another. It can also check console and network output, but the original article emphasizes only new errors introduced by the change. A long-standing warning should not derail every review, and a client-only interaction does not always need a network audit. A save that returns a 500 status after the UI looked fine is different: that is a signal worth capturing.
A useful report names the route, the actions taken, the checks passed, screenshots, the test command, and any fix found and rechecked. In the article’s settings example, the review recorded that the switch remained checked after reload, the update returned 200, no new console errors appeared, screenshots showed the label wrapping cleanly at 375 and 1440 widths, pnpm test settings passed 14 tests, and a disabled Save button bug in SettingsForm.tsx was found, fixed, and rechecked.
Start, Review, and Clean Up Safely
The agent cannot review anything until the application is running, and that is where shortcuts are tempting. The workflow should not hardcode pnpm dev in every repository. Instead, it should discover how the project starts: first check the dev script in package.json, then the README, and only fall back to an existing Docker setup if the app cannot reasonably run otherwise. In a typical Vite or Next.js project, package.json may list dev as vite, build as vite build, test as vitest run, and e2e as playwright test.
A practical flow is:
- Inspect package.json scripts to learn the dev command.
- Start the dev server in a temporary folder owned by the agent.
- Record the process ID so the agent can stop exactly the process it started.
- Run the browser review against the local port.
- Stop only that process and remove only the files or temporary state it created.
- Check git status to avoid touching unrelated changes.
This cleanup rule matters because a coding agent may be working in a repository with other running services. Killing unrelated processes or deleting unrelated files turns a review task into a side effect.
The original article also separates the author from the reviewer. The agent that made the change may be biased toward its own interpretation of the diff. A separate reviewer agent, given the same browser tools but a fresh set of instructions, is more likely to notice that the change needs a real UI check rather than a rationalization.
The instructions themselves can be split between project-level guidance and a reusable skill. In the original article, AGENTS.md can point the agent to the browser-review procedure, while the skill holds the reusable rules: derive the test from the diff, check the end result, collect the right evidence, and clean up only what the agent started.
That habit later became katalepsis, an open-source tool that packages the workflow. The original article says it also includes logic for deciding whether a check really passed. Installation requires Node.js 22.12 or newer and Git.
The value for readers is not that Playwright MCP replaces test suites. It adds a second layer of evidence: the application was actually used, and the changed behavior was observed.
Common Mistakes
- Treating a loaded page as proof. A report that says a route opened and the page loaded is not a frontend review.
- Asking the agent to verify the app without tying the review to the diff. The plan should follow the changed code path.
- Accepting unit tests that passed against the old code as proof of a fix. The map-layer cursor example in the original article shows the difference.
- Checking only the interaction instead of the final state. A button click is less important than what remains after reload.
- Using screenshots for every question. State changes often need accessibility or network evidence, while visual issues need screenshots.
- Cleaning up too broadly. The agent should stop only the process ID it recorded and remove only temporary state it created.
This workflow is most useful for user-facing web applications where a change can look correct in code and still behave incorrectly on screen. It is less necessary for purely internal scripts, batch jobs, or changes with no UI surface.

Comments (0)