I'm Tony. I build and operate web products, and Claude Code is my main development tool every day. A familiar problem appears when a coding agent finishes a form or user flow: the application builds, existing tests pass, and the interface looks correct. Then someone actually uses it. A button does nothing, validation behaves incorrectly, or a user reaches a screen they should never access.
A successful build tells me the code passed a build process, not that the feature works for its users. A screenshot tells me what the browser displayed at one moment, not what happens when someone interacts with it. In this article, I'll show you how I combine Claude Code with Playwright to test real browser behavior, collect evidence, investigate failures, and verify fixes. You'll also get a reproducible example, a test plan, agent instructions, and an evidence-review checklist you can adapt to your own projects.
This is article five in Making Coding Agents Reliable, a series about practical workflows for understanding, verifying, and maintaining code produced by AI coding agents. Each article focuses on one part of making an agent useful inside a real development process.
A good-looking UI can still be broken
Consider an admin application that lets employees view and export reports. You ask Claude Code to implement a report-export feature, including a date filter and permissions for different user roles. The agent adds a button, connects it to an API endpoint, updates the relevant components, and runs the existing tests.
Everything appears ready. An administrator opens the report page, sees the Export report button, and receives a confirmation after clicking it. The UI shows no obvious error, and the browser console is quiet. But none of those observations establishes that the downloaded file contains the correct data.
Several problems can hide behind that apparently successful interaction:
- Functional: The export button responds, but the downloaded file is empty.
- Validation: The date filter accepts an end date earlier than the start date.
- State: The user changes the report filter while an export is running, and the UI displays the wrong result.
- Navigation: Refreshing a report's direct URL returns the user to the dashboard.
- Permissions: A Viewer cannot see the export button, but the API still accepts export requests from that account.
- Tenant isolation: A user from one organization can retrieve a report belonging to another organization.
- Responsive layout: A form appears correct at desktop width but becomes unusable on a narrow screen.
These problems require different evidence. A screenshot might reveal a broken mobile layout, but it cannot establish that the server rejected an unauthorized export request. A unit test might confirm that a permission-checking function works, but not that every relevant API endpoint actually calls it.
I separate two questions when reviewing agent-generated code: Did the implementation behave as written, and did we implement the behavior the product actually requires?
The first question is answered through suitable tests and observations. The second requires acceptance criteria that exist independently of the implementation. When an agent writes both the feature and every test from its own interpretation, it can miss a requirement in both places.
Browser verification helps connect the two questions. It gives us evidence about what users can actually do, provided we test the right behaviors.
Turn requirements into browser-observable outcomes
Let's use a fictional TypeScript monorepo throughout the example:
project/
├── apps/
│ ├── admin/
│ └── api/
├── packages/
│ ├── ui/
│ └── shared/
├── tests/
│ └── e2e/
└── e2e-test-plan.md
The team uses pnpm, with commands such as pnpm -F api test for API tests. The admin application communicates with an API serving multiple customer organizations. Each organization owns its reports, and the API must enforce strict tenant isolation.
For the export feature, our test environment contains two fictional organizations, Alpha and Beta, and three accounts.
| Account | Organization | Role |
|---|---|---|
| admin.alpha | Alpha | Admin |
| viewer.alpha | Alpha | Viewer |
| admin.beta | Beta | Admin |
An Admin can view and export reports belonging to their organization. A Viewer can view their organization's reports but cannot export them. Neither role can access reports belonging to another organization.
These rules become an explicit verification matrix:
| User | View Alpha | Export Alpha | View Beta | Export Beta |
|---|---|---|---|---|
| Admin Alpha | Allow | Allow | Deny | Deny |
| Viewer Alpha | Allow | Deny | Deny | Deny |
| Admin Beta | Deny | Deny | Allow | Allow |
A requirement such as "Viewers cannot export reports" is too broad to verify with one UI assertion. It contains at least two independently testable behaviors: the Viewer should not receive the export action in the interface, and the API must reject an export request made with Viewer credentials.
I write acceptance scenarios using four elements: initial state, user action, expected outcome, and required evidence.
For example:
# e2e-test-plan.md
## TC01: Admin exports an authorized report
Given: Admin Alpha is authenticated
And: Report alpha-001 exists
When: The user opens the report
And: Selects Export report
Then: A download completes
And: Its contents match the Alpha fixture
## TC02: Viewer cannot export
Given: Viewer Alpha is authenticated
When: The user opens an Alpha report
Then: Export report is unavailable
And: A direct export API request is rejected
## TC03: Cross-tenant access is denied
Given: Admin Alpha is authenticated
And: Report beta-001 exists
When: The user opens the Beta report URL
Then: Beta report content is not disclosed
And: Exporting beta-001 is rejected
## TC04: Invalid date range
Given: Admin Alpha opens the report filter
When: End date is earlier than start date
Then: Validation feedback appears
And: No export request is submitted
## TC05: Export failure
Given: The export API returns an error
When: Admin Alpha requests an export
Then: The UI reports the failure
And: The loading state ends
Notice that each scenario checks something observable. "Export works correctly" is a general intention. "A download completes and contains the expected Alpha records" gives us a result we can verify.
This test plan also identifies where browser testing is insufficient. TC02 and TC03 require server-side verification, even if the UI appears to enforce both restrictions.
Prepare a deterministic test environment
Before giving an agent browser access, I want the application and test data under control. Otherwise, a failed test might indicate an actual defect, an expired session, unexpected fixture data, or another test changing the same records. When the environment changes unpredictably, interpreting the evidence becomes harder.
For this example, I would prepare:
- A dedicated test application and API, isolated from production.
- Seeded accounts for Admin Alpha, Viewer Alpha, and Admin Beta.
- Stable report identifiers such as
alpha-001andbeta-001. - Distinct report contents containing
ALPHA-REPORTandBETA-REPORT. - A repeatable reset procedure for database and application state.
- Predictable API responses for delayed requests and error conditions.
- Test credentials supplied through environment variables rather than prompts or committed files.
The distinction between fixture identity and actual access rights matters. Setting a browser cookie that says tenant=alpha does not establish tenant isolation. The server must derive the authenticated user's organization from a trusted session or identity and apply that constraint when fetching records.
I also keep agent permissions separate from application permissions. Playwright MCP may give Claude Code the ability to click a button, but the authenticated account determines what that click can do. Neither a prompt nor a browser automation setting replaces server-enforced access control.
For this example, a small deterministic fixture can demonstrate the interaction without requiring the entire monorepo. You can create a standalone claude-playwright-workflow directory and use the following file structure:
claude-playwright-workflow/
├── fixture/
│ ├── index.html
│ └── server.mjs
├── tests/
│ └── report.spec.ts
├── playwright.config.ts
├── agent-task.md
└── evidence/
The fixture represents a simplified report screen. Its purpose is to reproduce a browser-observable defect, not to simulate a production authentication system or establish tenant security.
Here is the deliberately flawed interface:
<!-- fixture/index.html -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Report export fixture</title>
</head>
<body>
<h1>Reports</h1>
<label>
Start date
<input type="date" id="start">
</label>
<label>
End date
<input type="date" id="end">
</label>
<button id="export">Export report</button>
<p id="status" role="status"></p>
<script>
const button = document.querySelector('#export');
const status = document.querySelector('#status');
button.addEventListener('click', async () => {
status.textContent = 'Exporting...';
const start = document.querySelector('#start').value;
const end = document.querySelector('#end').value;
const params = new URLSearchParams({ start, end });
try {
const response = await fetch(
`/api/export?${params}`
);
if (!response.ok) {
throw new Error('Export failed');
}
status.textContent = 'Export complete';
} catch {
status.textContent = 'Export failed';
}
});
</script>
</body>
</html>
For a zero-dependency server, use Node's built-in HTTP module:
// fixture/server.mjs
import { createServer } from 'node:http';
import { readFile } from 'node:fs/promises';
const html = await readFile(
new URL('./index.html', import.meta.url)
);
createServer((req, res) => {
const url = new URL(req.url, 'http://localhost');
if (url.pathname === '/api/export') {
res.writeHead(200, {
'Content-Type': 'text/csv'
});
res.end('report\nALPHA-REPORT\n');
return;
}
res.writeHead(200, {
'Content-Type': 'text/html'
});
res.end(html);
}).listen(4173, '127.0.0.1');
The fixture contains two intentional defects. It accepts an invalid date range, and it treats any successful HTTP response as a completed export without actually providing a file download. The API stub accepts all requests, so it must not be mistaken for a security-test implementation.
Start the fixture with:
node fixture/server.mjs
The application is available at http://127.0.0.1:4173. It provides a small target where a browser test can detect behavior that a screenshot of the initial form would miss.
Give Claude Code a clear browser-testing task
I use Playwright in two complementary ways. Playwright MCP allows Claude Code to navigate the application, interact with controls, inspect page state, and reproduce unexpected behavior. Playwright Test stores assertions as executable test files that other developers and CI can run without relying on the agent's interpretation.
You can register Playwright MCP with Claude Code:
claude mcp add playwright -- npx @playwright/mcp@latest
The -- separates Claude's options from the MCP server command. The default configuration scope is local; you can also choose project for a repository-shared .mcp.json configuration or user for broader availability.
Useful management commands include:
claude mcp list
claude mcp get playwright
claude mcp remove playwright
Inside Claude Code, /mcp lets you inspect MCP connections. Claude Code initially loads MCP tool names and makes fuller tool definitions available when needed, rather than placing every connected tool's definition into context immediately.
MCP tool permission names follow the mcp__playwright__* pattern. You can manage them through the allow, ask, and deny permission settings. The article on permissions and MCP tool control in this series covers that boundary in greater detail.
Once the test environment is running, I give Claude Code a task that keeps observation separate from modification:
# agent-task.md
Target:
- Application: http://127.0.0.1:4173
- Fixture: fixture/
- Test plan: e2e-test-plan.md
Use Playwright MCP to inspect the report export flow.
First, reproduce these scenarios:
1. Submit a valid date range.
2. Submit an end date before the start date.
3. Observe what happens when export succeeds.
4. Observe what happens when export fails.
For each scenario, record:
- Initial browser state
- Exact actions
- Expected behavior
- Actual behavior
- Console or network evidence
- Screenshot when relevant
- Pass, Fail, or Not verified
Do not modify application code during exploration.
Do not claim a download succeeded merely because
the status message says "Export complete".
Do not infer authentication, authorization, or
tenant isolation from this fixture.
After exploration, propose Playwright Test cases.
Wait until evidence is recorded before fixing code.
The instructions intentionally avoid telling Claude that the UI is broken. I want it to compare actual behavior with acceptance criteria, not find confirmation for a predetermined diagnosis.
This distinction matters because the same agent may implement the feature and review it. Clear acceptance criteria and independently reviewed assertions reduce the risk of the agent confirming its own assumptions.
Use Playwright to exercise meaningful user flows
After exploring the fixture through MCP, I turn the observed interactions into repeatable tests. A useful test should perform the user action and inspect an outcome that matters, not merely verify that a control exists.
Install the Playwright Test package and browser in the example directory:
npm install --save-dev @playwright/test
npx playwright install chromium
Create a configuration that records useful failure evidence:
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
use: {
baseURL: 'http://127.0.0.1:4173',
trace: 'retain-on-failure',
screenshot: 'only-on-failure'
},
reporter: 'html'
});
Then create three tests around the fixture's behavior:
// tests/report.spec.ts
import { test, expect } from '@playwright/test';
test('report page provides export controls', async ({
page
}) => {
await page.goto('/');
await expect(
page.getByRole('heading', { name: 'Reports' })
).toBeVisible();
await expect(
page.getByRole('button', {
name: 'Export report'
})
).toBeVisible();
});
test('invalid date range blocks export', async ({
page
}) => {
let exportRequests = 0;
await page.route('**/api/export?*', async route => {
exportRequests++;
await route.fulfill({
status: 200,
body: 'report\nALPHA-REPORT\n'
});
});
await page.goto('/');
await page.locator('#start').fill('2026-02-20');
await page.locator('#end').fill('2026-02-10');
await page.getByRole('button', {
name: 'Export report'
}).click();
await expect(
page.getByRole('status')
).toContainText('Invalid date range');
expect(exportRequests).toBe(0);
});
test('server failure produces an error state', async ({
page
}) => {
await page.route('**/api/export?*', async route => {
await route.fulfill({
status: 500,
body: 'Export unavailable'
});
});
await page.goto('/');
await page.getByRole('button', {
name: 'Export report'
}).click();
await expect(
page.getByRole('status')
).toHaveText('Export failed');
});
The first test verifies that the page renders. The second tests validation and confirms that invalid input does not generate an export request. The third controls the server response to reproduce an error state deterministically.
Run the suite with the fixture server running:
npx playwright test
The expected outcome for the original fixture is two passing tests and one failing test. The invalid-date test should fail because the implementation submits the request and displays "Export complete" instead of validation feedback.
This is a useful demonstration of a general problem. The UI can render correctly, the button can respond to clicks, and the request can return HTTP 200 while the user flow still violates its requirements.
The fixture also contains a missing download behavior. To test an actual download in a complete implementation, a Playwright test can wait for the browser's download event and inspect the resulting file:
const downloadPromise = page.waitForEvent('download');
await page.getByRole('button', {
name: 'Export report'
}).click();
const download = await downloadPromise;
const path = await download.path();
expect(download.suggestedFilename()).toMatch(/\.csv$/);
expect(path).toBeTruthy();
This checks that a browser download occurred. The next step would be reading the file and comparing its contents with the expected report fixture. An event or filename alone does not establish data correctness.
For the full monorepo, I would also test navigation, user roles, direct report URLs, and API authorization. Those require the real authenticated application and appropriate API tests, not the simplified HTML fixture.
Inspect failures before asking the agent to repair them
A failing assertion identifies a mismatch between expected and observed behavior. It does not automatically identify the cause. I want the agent to inspect the evidence before changing code.
After running Playwright Test, open its report:
npx playwright show-report
For the intentionally broken date-validation case, the relevant failure will concern this assertion:
await expect(
page.getByRole('status')
).toContainText('Invalid date range');
A representative failure summary looks like this:
FAIL: invalid date range blocks export
Expected:
Status contains "Invalid date range"
Observed:
Status contains "Export complete"
Additional observation:
One export request was submitted.
Assessment:
Fail
This is an illustrative summary of the expected failure, not a captured execution log. When running the example, use the generated HTML report, trace, and failure screenshot as the actual evidence.
I would ask Claude to answer several questions before editing: Did the form read the entered dates correctly? Did the client validate their order? Was the export request sent? Did the server accept invalid parameters? Did the UI show a success state based only on the HTTP status?
Those questions guide the investigation toward observable behavior. In this fixture, the event handler builds a request without checking the date range. The server accepts the request, and the interface displays success because the response was successful.
A screenshot showing "Export complete" is helpful, but the network observation is more important. Together, they demonstrate that invalid data reached the API and was treated as successful.
There is another important review step: inspect the tests themselves. If Claude generated a test that only checks whether the status message changes, that test can pass while the export remains incorrect. A test written by the same agent that implemented the feature is not independent validation until someone checks its assertions against the original requirement and reviews its execution.
Run the tests again after changes
After the failure is understood, I let Claude propose a focused repair. In the fixture, the client should reject an invalid date range before sending the request, while the API should also validate its inputs. The client-side check improves the interaction, and the server-side check prevents invalid requests from bypassing the browser.
The client can add this condition before constructing the request:
if (start && end && end < start) {
status.textContent = 'Invalid date range';
return;
}
The comparison works here because populated date inputs use the normalized YYYY-MM-DD format. The API should separately validate date values and ordering rather than trusting client-side checks. I would keep these responsibilities distinct when applying the fix to the actual monorepo.
A repair task for Claude Code can remain narrowly scoped:
The invalid date-range test failed.
Review the recorded browser and network evidence.
1. Identify the behavior causing the failure.
2. Implement client-side date validation.
3. Add matching API validation in the real application.
4. Keep the existing valid-export flow intact.
5. Run the previously failing test.
6. Run the relevant regression tests.
7. Report actual outcomes and remaining gaps.
Do not weaken or delete the failing assertion.
Do not report unexecuted checks as passing.
I would run the browser suite again, then run the relevant API tests in the monorepo:
npx playwright test
pnpm -F api test
The first command checks the observed user behavior. The second exercises the application's API test suite, whose assertions must cover the server behavior we changed.
For this example, I expect the date-validation test to pass after the client fix. I would still consider the feature incomplete until the download implementation, its file contents, and the relevant authorization behavior were verified.
The evidence record should show the original failure, the code change, the test results after modification, and any requirements left unverified. That record is more useful than a final agent message saying "fixed."
Understand what browser tests cannot prove
Browser tests are valuable because they execute interactions against a running application. They are not a complete representation of everything users might do or every way a system might fail. Their usefulness depends on the scenarios, assertions, fixtures, and environment we choose.
For example, a Playwright test that confirms a Viewer cannot see an Export button does not prove that the API rejects Viewer requests. A test that confirms Alpha reports appear in an Alpha user's report list does not prove that a direct request for a Beta report will fail. Those are authorization and tenant-isolation requirements that need explicit server-side tests.
Likewise, a screenshot assertion can detect an unexpected visual difference without establishing whether the interface is usable. Responsive testing should include interactions at the viewport sizes the product supports. State-related testing should exercise loading, errors, retries, and navigation rather than relying exclusively on initial page rendering.
There are practical limits to automated interpretation, too. An agent can misread a trace, write a weak assertion, or treat an environmental failure as an implementation defect. That's why I separate observed evidence from the agent's explanation and review both before accepting a change.
The evidence-review checklist
Before accepting an agent-generated frontend feature, I check:
- [ ] The acceptance scenarios were defined independently of the implementation.
- [ ] Tests ran against a known, isolated environment.
- [ ] The correct identity, role, and tenant were used.
- [ ] Meaningful interactions were executed, not just initial rendering.
- [ ] Assertions checked outcomes rather than only button clicks.
- [ ] Invalid inputs and failure states were covered.
- [ ] Downloads or submitted data were inspected when required.
- [ ] Permission and tenant boundaries were verified at the API.
- [ ] Failed runs retained enough evidence for reproduction.
- [ ] The agent's test assertions were reviewed.
- [ ] The original failure was retested after repair.
- [ ] Relevant regression tests were executed.
- [ ] Unverified requirements remained explicitly marked as such.
I use three assessment states: Pass, Fail, and Not verified. This avoids treating the absence of an observed failure as evidence of correctness. It also prevents a passing browser suite from hiding requirements the suite never attempted to exercise.
For the report-export example, the final verification record should identify the evidence for each acceptance scenario. If validation passes but tenant isolation has not been tested, those results must remain separate.
My goal is not to make Claude Code run more tools. It is to create a short, repeatable path from a requirement to an observation, from an observation to a test, and from a failure to a verified repair.
Playwright MCP is useful for exploration and reproduction. Playwright Test preserves stable checks so the team can run them again. The developer remains responsible for deciding whether those checks actually cover the product's requirements.
What's the most frustrating UI bug you've seen pass automated checks but fail in a real browser?



Top comments (0)