Playwright Testing with AI Agents

Use Claude Code, Cursor, or Codex to write and review Playwright tests, verify assertions, and evaluate ContextQA MCP creation and Playwright export.

Quick answer

An AI coding agent can inspect an application, propose Playwright scenarios, write specs, run them, and investigate failures. Start with an explicit behavior contract and review the generated assertions. Use ContextQA MCP when you want the same assistant to create and run managed tests and retrieve their evidence. If you export those tests to Playwright, inspect the generated project for manual steps and missing assertions before treating it as automated regression coverage.

This tutorial starts with ordinary Playwright. It works with Claude Code, Cursor, Codex, or another coding agent that can edit your repository and run its test command.

Prerequisites

• A repository with an approved Node.js version and package manager.
• An installed @playwright/test dependency and its browser binaries, or permission to add them on a feature branch.
• A disposable local or staging application for real application testing.
• A written expected result, relevant source files, and reproducible test data.
• For the ContextQA path, an account, a reachable test environment, and MCP setup.

If Playwright already exists in the repository, retain its configuration and fixtures. Do not ask the agent to replace working test infrastructure simply to follow a tutorial. For a new project, follow the official Playwright installation guide and commit the resulting lockfile.

1. Define the behavior before generating code

For a report filter, a useful contract is:

Condition	Expected behavior	Evidence
A user selects September	The requested reporting period is September	Submitted value or request payload
The report finishes	The page identifies the selected period	Exact visible result
The service fails	The page reports failure without showing success	Error assertion and response evidence
The user cannot access reports	The operation is denied	Authorization and absence of restricted data

Avoid a test that clicks “Generate” and merely checks that the page still exists. That would miss an incorrect period, a failed request, or an unauthorized result. Decide which checks belong in unit tests, integration tests, and a real end-to-end journey.

Give the agent a bounded task:

Read our Playwright configuration, report-page component, existing fixtures,
and report API contract. Propose tests for period selection and service failure.
Use the existing test runner and data setup. Show the expected result for each
scenario before writing specs. Identify any missing fixture or requirement.
Do not invent an API endpoint or weaken an assertion to make a run pass.

2. Learn the assertion pattern with a small fixture

The following spec is self-contained: it creates a tiny report form in the browser. It teaches locator and assertion behavior; it does not test your application's backend, authentication, or reporting implementation.

Save it as tests/report-form.spec.ts in a Playwright project:

import { test, expect } from '@playwright/test';

test('the report result identifies the selected month', async ({ page }) => {
  await page.setContent(`
    <form aria-label="Report filters">
      <label for="period">Reporting month</label>
      <select id="period" name="period">
        <option value="2026-08">August 2026</option>
        <option value="2026-09">September 2026</option>
      </select>
      <button type="submit">Generate report</button>
    </form>
    <p role="status"></p>
    <script>
      document.querySelector('form').addEventListener('submit', (event) => {
        event.preventDefault();
        const month = document.querySelector('select').value;
        document.querySelector('[role="status"]').textContent =
          'Report ready for ' + month;
      });
    </script>
  `);

  await page.getByLabel('Reporting month').selectOption('2026-09');
  await page.getByRole('button', { name: 'Generate report', exact: true }).click();
  await expect(page.getByRole('status')).toHaveText('Report ready for 2026-09');
});

Run only this spec initially:

npx playwright test tests/report-form.spec.ts

The page fixture gives the test its own browser page and context. It does not create isolated database records for an application. Real test-data setup and cleanup remain your responsibility. See Playwright fixtures.

The final await expect(...).toHaveText(...) retries the condition until it matches or times out. An immediate boolean check can inspect the page too early. Playwright's assertion reference explains which matchers retry.

3. Turn the pattern into an application test

Replace page.setContent() with navigation to your actual report page. Reuse your repository's authenticated fixture and create a unique test account or report record through its approved setup routine. Do not paste the example markup into the application to make the test pass.

Ask the agent to inspect the rendered page before choosing locators. Prefer accessible labels and roles where they identify the control; use an agreed test ID for otherwise ambiguous elements. Scope repeated buttons to the correct form or section. These choices follow Playwright's locator guidance.

For a real report workflow, add the missing boundary checks:

1. Confirm the chosen period reaches the report service.
2. Confirm the final result contains the expected seeded data.
3. Verify failure behavior with an approved service stub or disposable fault scenario.
4. Verify permissions with a separate restricted account.
5. Clean up created data even if an assertion fails.

A stubbed response is useful for deterministic UI behavior. Label that test as a UI test with a stubbed service; keep a separate application-backed test if service integration matters to the release decision.

4. Review and diagnose the result

Reject fixed sleeps added to hide timing problems. Ask which condition the test needs to await. Preserve the first failure when investigating retries, and inspect whether the failure concerns the product, test data, locator, or environment.

For a focused debugging run:

npx playwright test tests/report-form.spec.ts --trace on --reporter=html
npx playwright show-report

Traces can reveal actions, DOM snapshots, and network activity. Treat them as potentially sensitive application evidence and restrict sharing accordingly. See Trace Viewer.

Prove the test can fail: in a disposable branch, change the fixture's result to the wrong month and run the unchanged spec. It must fail on the month assertion. Restore the behavior and rerun. This checks the oracle rather than rewarding a green result.

5. Create the equivalent managed test with ContextQA MCP

After connecting your assistant, first confirm the active workspace and available tools. The hosted MCP server does not automatically see your local filesystem or localhost; use a reachable test deployment or your organization's approved private-network setup.

In the confirmed ContextQA workspace, create one test for the report page at
<approved staging URL>. Use the prepared test account and reporting data.
Select September 2026, generate the report, and assert both the selected period
and the expected seeded total. Do not execute yet. Return the new test ID and
all steps so I can review the assertions and data references.

Review the returned steps, then request execution for the approved test ID. Wait for the terminal result and inspect step evidence; a monitoring URL alone is not proof of a pass. Ask for relevant logs or screenshots when available, and distinguish a likely root cause from a confirmed diagnosis. The execution reference describes this loop.

6. Evaluate export before moving coverage

Use the Playwright export and portability guide for the generated file manifest, local saving, credential review, and acceptance procedure. AI verification placeholders and manual checkpoints need remediation before unattended CI. Existing suites should follow the separate Playwright migration guide.

Troubleshooting and FAQ

The locator matches multiple buttons. Scope it to the observed form, dialog, or row. Do not select an arbitrary first match unless position is itself the contract.

The sample passes, but the application fails. The sample proves only the local fixture. Investigate authentication, seed data, service responses, and application locators separately.

Can the agent maintain tests automatically? It can propose changes. Review any changed assertion, new skip, removed scenario, or altered expected result as a coverage decision.

Is an exported green run equivalent to ContextQA passing? Only after meaningful assertions and execution dependencies are reconciled. An assumed-success placeholder does not verify the business outcome.

Sources and implementation reviewed September 25, 2026. Verify the tool schema in your connected client before using version-dependent capabilities.

Next step

Connect ContextQA MCP and create one reviewed test. To evaluate managed execution alongside your repository, book a testing workflow demo and bring one Playwright spec, its fixtures, and a failure you need to diagnose.