TL;DR
This article covers how to use GitHub Copilot with Playwright MCP and Playwright's Test Agents to write tests that pass in CI and not only in an editor session. It covers the instructions file, agent-mode generation, a stress run before merge, a review checklist and fixing red CI runs from the trace.
Treat every Copilot-written test as a pull request that has to pass CI before anyone trusts it, and fix red runs from the trace instead of the log. A Copilot spec merges after it passes every repeat under the CI config and survives review.
- Register Playwright MCP in VS Code with
code --add-mcp. Start every MCP session fresh with--isolated, and load the signed-in state your tests get with--storage-state. - Write rules in
.github/copilot-instructions.mdthat name your fixtures file, your auth project and your config. - Give Copilot a concrete scenario on your own app: the route relative to
baseURL, the steps a user takes and the outcome to assert. - Run each new spec many times under the config CI uses, with retries off. Review every Copilot spec against the checklist before you approve it.
- Download the failed job's trace artifact and have Copilot read it with
npx playwright trace. Prompt for the root cause before any code changes.
In VS Code, you can use configured MCP servers in Copilot Chat. Playwright MCP works with VS Code, and once it is connected, your AI assistant uses its tools to open the browser, navigate to the page and interact with elements. Then the pull request goes red in GitHub Actions.
That first pass proved less than it looked. By default, Playwright MCP runs the browser in headed mode, and its default persistent profile keeps login state and cookies between sessions. On GitHub-hosted runners, each job starts on a new virtual machine (single-CPU runners get a new container instead).
So you paste the failing log back into Copilot. The log doesn't show the page, the failing request or the test's history, so the agent guesses. Its guess tends to be a wait or a looser assertion that turns the run green and leaves the bug in place.
The fix is to treat every Copilot-written test as a pull request that has to pass CI before anyone trusts it, and to fix red runs from the trace instead of the log.
Connecting Playwright MCP to Copilot
Copilot can't write a good test for a page it has never seen. Before it can see yours, Playwright MCP needs Node.js 20 or newer and an MCP client such as VS Code. If the repo has no Playwright project yet, scaffold one before you bring Copilot in: it will copy whatever config and tests it finds. Playwright's standard MCP configuration runs npx @playwright/mcp@latest, and npx installs a package that isn't in the project's dependencies into a folder in the npm cache.
Playwright's MCP guide registers the server in VS Code with code --add-mcp. Use that command rather than editing each developer's settings file by hand: one line in the repo's README registers the same server, with the same flags, for everyone who runs it. After you register the server, check that VS Code lists it as running before you switch Copilot Chat to agent mode.
Playwright MCP works on the page's accessibility tree, not on pixels. Each Playwright MCP snapshot shows the page elements, their roles, and text content. page.getByRole() locates elements by their ARIA role, ARIA attributes and accessible name, and Playwright recommends prioritizing user-facing attributes such as page.getByRole() to make tests resilient. So the accessibility tree already nudges Copilot toward the locators you want, as long as your instructions keep it there.
By default, the MCP browser runs headed so you can see what it does. Watching helps you catch a wrong turn early. A pass you watched is still not a CI pass.
Writing copilot-instructions.md
Copilot doesn't know your suite. Repository custom instructions give Copilot additional context on how to understand your project. Left to guess, it writes a login into the test and a full URL into page.goto(). A role prompt won't change that. Rules that name your files will.
Anti-pattern
A generic instructions file
You open the file with "You are an expert in Playwright and TypeScript" and follow it with rules about clean code. Copilot reads it and still writes a spec that fills in the login form at the top and goes to https://staging.example.com/cart. Both choices pass on your laptop. Both break when CI points at a preview environment or the test account's password rotates.
Fix
Write rules that name your fixtures file, your auth project and your config, and give the reason with each rule so Copilot can apply it to cases the rule doesn't list. Put the file at .github/copilot-instructions.md:
# Playwright tests in this repo
- Import `test` and `expect` from `tests/fixtures.ts`, never from `@playwright/test`. Page objects are fixtures in that file. Add new ones there instead of defining page classes in a spec.
- Never log in inside a test. The `setup` project in `playwright.config.ts` signs in once, and every test project starts from its saved state.
- Never commit anything under `playwright/.auth/`: those files can impersonate the test account. The setup project reads credentials from `TEST_USER_EMAIL` and `TEST_USER_PASSWORD`.
- Navigate with relative paths such as `page.goto('/cart')`. `baseURL` comes from the config and changes per environment in CI. Never hardcode a host.
- Find elements with `page.getByRole()` and an accessible name. No CSS or XPath selectors and no `nth()`, `first()` or `last()`: they break or hit the wrong element when the DOM changes.
- Never add a fixed wait. Rely on actions that wait automatically and on web-first assertions such as `await expect(locator).toBeVisible()`.
- Assert the outcome the scenario promises with `await expect(...)`, never with `isVisible()`, which checks once and returns.
- Never leave `test.only` in a spec.
Each rule maps to how Playwright works. Custom fixtures come from test.extend(), which returns a new test object that includes them, so a spec that imports test from @playwright/test gets none of your page objects. Keep page objects as fixtures in one file, not as a fresh class in every spec Copilot writes:
// tests/fixtures.ts
import { test as base, expect, type Page } from '@playwright/test';
export class CartPage {
constructor(private readonly page: Page) {}
async open() {
await this.page.goto('/cart');
}
checkoutButton() {
return this.page.getByRole('button', { name: 'Checkout' });
}
}
export const test = base.extend<{ cartPage: CartPage }>({
cartPage: async ({ page }, use) => {
await use(new CartPage(page));
},
});
export { expect };
For tests without server-side state, Playwright recommends a setup project. Create a new setup project in the config and declare it as a dependency for all your testing projects. This project will always run and authenticate before all the tests. A test that logs in again repeats that work and breaks every time the login page changes. The saved state file can hold cookies and headers that impersonate the test account, and Playwright strongly discourages committing it to any repository, which is why the instructions name the directory.
baseURL builds the URL for page.goto(), page.route(), page.waitForURL(), page.waitForRequest() and page.waitForResponse(), and it is unset by default. Set it from an environment variable, and every relative page.goto('/cart') follows CI to the environment the job targets:
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
use: {
// Specs use relative paths; CI sets BASE_URL per environment
baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
},
projects: [
{ name: 'setup', testMatch: /.*\.setup\.ts/ },
{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
storageState: 'playwright/.auth/user.json',
},
dependencies: ['setup'],
},
],
});
The locator and wait rules come from Playwright's own docs. Playwright doesn't recommend CSS or XPath locators, because DOM changes make the tests fragile, and the locator guide advises against first(), last() and nth() because Playwright may click an element you didn't intend once the page changes. The page.waitForTimeout() docs say never to wait for a timeout in production, because tests that wait for time are inherently flaky. Leave these rules out, and nothing stops Copilot from copying patterns out of older code.
Installing the Test Agents
Agent mode with a good instructions file gets you a long way. Playwright's Test Agents add structure on top: a planner, a generator that turns the planner's Markdown plan into tests, and a healer that patches failing ones. The init-agents command adds their definitions to the repo:
npx playwright init-agents --loop=vscode
Each definition is a collection of instructions and MCP tools that Playwright provides, so you don't write a custom agent file for Copilot by hand.
The agentic experience needs VS Code 1.105 or later to work properly in VS Code. One reporter's planner agent could not detect the Playwright MCP tools after they switched Copilot Chat to planner mode (#37744). The reporter closed the issue once VS Code 1.105.0 resolved it. Check the editor version before you debug the agents.
Rerun init-agents after every Playwright upgrade. Playwright's docs say to regenerate the definitions whenever Playwright is updated, so they pick up new tools and instructions. Commit the regenerated files in the same pull request as the version bump, so a reviewer sees both together.
The seed test
The seed test decides where the agents think a test starts. The planner runs it to do all the setup your tests need: global setup, project dependencies, fixtures and hooks. A seed that imports straight from @playwright/test and signs in on its own teaches the agents a starting state your suite never uses. Write it with your real fixtures:
// tests/seed.spec.ts
import { test, expect } from './fixtures';
test('seed', async ({ page }) => {
await page.goto('/');
await expect(page.getByRole('navigation')).toBeVisible();
});
What comes out is ordinary test files. The generator produces executable Playwright tests that you commit, review and run in CI like any other spec. Prefer that over tests that look up selectors at runtime: a spec on disk can be diffed, reviewed and stress-run before it merges.
Generating a test in agent mode
With the agents set up, the prompt decides what the test checks. Copilot can only assert an outcome you told it about.
Anti-pattern
A prompt with no outcome
You ask Copilot to "write tests for the login page". With no scenario and no expected result, it writes tests that open the page and check that a heading is there. Those tests pass, and they would keep passing if the sign-in button did nothing. Point Copilot at a third-party site instead of your own app, and the test also depends on someone else's uptime and bot protection.
Fix
Give Copilot a concrete scenario on your own app: the route relative to baseURL, the steps a user takes and the outcome to assert. Name the target file, and attach the instructions file and an existing spec as context so it copies your imports and style:
Scenario: a signed-in user adds "Trail Running Shoes" to the cart from /products,
opens the cart, checks out and pays with the saved card.
Expected: an "Order confirmed" heading and an order number on the confirmation page.
Perform the steps in the browser first, then write tests/checkout.spec.ts.
Follow .github/copilot-instructions.md and match the style of tests/cart.spec.ts.
Let the agent perform the scenario in the browser before it writes code. The generator agent works that way: it turns a plan into tests and verifies selectors and assertions live as it performs the scenarios. Checking live leaves Copilot less room to invent a locator that isn't on the page.
The spec that should come back imports from your fixtures, uses relative paths and finds elements by role and text:
// tests/checkout.spec.ts
import { test, expect } from './fixtures';
test('signed-in user checks out with the saved card', async ({ page, cartPage }) => {
await page.goto('/products');
await page
.getByRole('listitem')
.filter({ hasText: 'Trail Running Shoes' })
.getByRole('button', { name: 'Add to cart' })
.click();
await cartPage.open();
await cartPage.checkoutButton().click();
await page.getByRole('button', { name: 'Pay with saved card' }).click();
await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
await expect(page.getByText(/Order number \d+/)).toBeVisible();
});
Model choice matters less than this context. A model that can see the page through MCP and read your fixtures file beats a stronger model guessing from the prompt alone.
Stress-testing before merge
An agent that reruns a test until it passes has shown the test can pass once. One pass isn't enough to merge.
Anti-pattern
Merging on one green run
The spec passed in the headed MCP session, then passed in CI on its second attempt, and the pull request merged. The retry hid a race between a click and a network call. Now the spec fails on main, in somebody else's pull request.
Fix
Run each new spec many times under the config CI uses, with retries off, so flakiness shows up before merge instead of hiding behind a retry. It's the same check you'd use to confirm a suspected flaky test, applied before the spec ever lands. The --repeat-each <N> option runs each test N times; the default is 1. Add the stress settings to playwright.config.ts:
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
// Exit with an error on CI if any spec still has test.only
forbidOnly: !!process.env.CI,
// The stress job sets STRESS_RUN, so a flaky spec fails instead of passing on a retry
retries: process.env.STRESS_RUN ? 0 : 2,
use: {
baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
// With retries off, keep a trace for every failed repeat
trace: 'retain-on-failure',
},
projects: [
{ name: 'setup', testMatch: /.*\.setup\.ts/ },
{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
storageState: 'playwright/.auth/user.json',
},
dependencies: ['setup'],
},
],
});
With retries off, trace: 'retain-on-failure' still keeps a trace for each failed test, so a repeat that fails leaves something to debug. forbidOnly makes the run exit with an error if any test or group is marked test.only() or test.describe.only(), which the docs call useful on CI. A focused test Copilot forgot to unfocus fails the job, since GitHub Actions always sets CI to true.
Run the stress job on pull requests that touch tests, scoped to the spec files the pull request changed. Keep your main Playwright workflow as it is and add this job next to it:
name: Stress changed specs
on:
pull_request:
paths:
- 'tests/**'
jobs:
repeat-each:
runs-on: ubuntu-latest
env:
STRESS_RUN: '1'
BASE_URL: ${{ vars.STAGING_URL }}
TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npx playwright install --with-deps
- name: Run each changed spec 10 times
run: |
SPECS=$(git diff --name-only --diff-filter=AM "origin/${{ github.base_ref }}...HEAD" -- 'tests/*.spec.ts')
if [ -z "$SPECS" ]; then echo "No changed specs"; exit 0; fi
npx playwright test $SPECS --repeat-each 10
- uses: actions/upload-artifact@v4
if: failure()
with:
name: stress-traces
path: test-results/
The success signal is every changed spec passing all ten repeats, not one green check. We default to 10 repeats and lower the count only for long end-to-end flows, since ten repeats of a short spec cost little and ten of a long checkout flow burn real CI minutes.
Reviewing Copilot's output
A green stress run says the test is stable. It doesn't say the test checks anything.
Anti-pattern
Approving a clean-looking green test
The spec reads well and passes, so it gets approved. Read it line by line and it waits on time, clicks by position and checks the result once:
// Anti-pattern: sleeps instead of waiting, clicks by CSS position,
// checks once with isVisible(), and test.only must never merge
import { test, expect } from '@playwright/test';
test.only('checkout works', async ({ page }) => {
await page.goto('https://staging.example.com/cart');
await page.waitForTimeout(3000);
await page.locator('.cart-actions button').nth(1).click();
await page.waitForTimeout(2000);
const confirmed = await page.locator('.confirmation').isVisible();
expect(confirmed).toBeTruthy();
});
Fix
Review every Copilot spec against this checklist before you approve it. For the checks this one leaves out, such as cleanup and healer diffs, see the pre-merge review checklist for AI-generated tests.
- Reject any
page.waitForTimeout(). Its docs call tests that wait for time inherently flaky, and a guessing agent often adds a wait. - Reject CSS, XPath and position-based locators. They break or hit the wrong element when the DOM changes. Reject code that scores elements at runtime to pick a selector for the same reason, and ask for
page.getByRole(). - Check the assertions. With an assertion like
isVisible(), the test doesn't wait at all: it checks the locator once and returns. Require anexpecton the outcome the scenario promised, not on the page having loaded. - Search for
test.onlyand for a login in the test body. Either one means Copilot ignored the instructions file, so fix the instructions as well as the spec.
The reviewed version imports from the fixtures file, clicks the checkout button through the cartPage fixture and asserts the confirmation heading by role:
// tests/checkout.spec.ts
import { test, expect } from './fixtures';
test('checkout confirms the order', async ({ page, cartPage }) => {
await cartPage.open();
await cartPage.checkoutButton().click();
await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
});
Fixing red CI runs
Even a reviewed, stress-run spec goes red eventually, and the quickest-looking fix is to paste the log into Copilot Chat. Give it the trace instead.
Anti-pattern
Fixing from the log
You copy the failing step's output into Copilot Chat and accept the fix it suggests. From the log alone, the agent can't see what was on the page, which request returned the wrong data, or whether the test failed the same way before, so it guesses. An agent that guesses often adds a wait, loosens the assertion or retries until the test passes, and the bug stays in the code.
Fix
Download the failed job's trace artifact and have Copilot read it with npx playwright trace. Coding agents can run that command to explore a Playwright trace and understand failing or flaky tests from the command line. One request, which shipped in v1.59, asked for a CLI command that converts Playwright traces into LLM-friendly Markdown and HTML files, so AI assistants can analyze traces when the GUI-based Trace Viewer is not accessible (#38936). A maintainer replied: "Explore cli for trace viewer." The issue was closed as completed and labeled v1.59.
# Replace 9876543210 with the failed run's ID
(mkdir -p ci-traces && cd ci-traces && gh run download 9876543210 -n stress-traces)
# Show the trace CLI's commands before Copilot uses them
npx playwright trace --help
Then prompt for the root cause before any code changes:
tests/checkout.spec.ts failed in CI. The trace is under ci-traces/.
Use npx playwright trace to read the actions, network requests and error.
Before you change any code, tell me the root cause and the trace evidence for it.
If the app is wrong, stop and say so. Do not change the test.
If the test is wrong, fix it under .github/copilot-instructions.md:
no waitForTimeout, no weaker assertions, no retries.
Then run npx playwright test tests/checkout.spec.ts --repeat-each 10.
Asking for the root cause first is the line that matters. If the trace shows the app is wrong, such as a request that returns an error or a total that doesn't add up, you've found a real bug: fix the app or file it, and don't let Copilot rewrite the test to match broken behavior. When the test was wrong, rerun the fixed spec with --repeat-each before you push. A fixed test meets the same bar as a new one.
To check Copilot's reading of a trace yourself, the trace viewer walkthrough for red CI jobs shows where locator timeouts and backend errors show up.
The weak link in trace-driven fixes is getting the context to the agent. Downloading artifacts by hand works for one pull request, not for every red run across a team, and you lose the test's history along the way. Currents' Fix failing CI tests opens a failed test's context in GitHub Copilot and other agents, and any agent that can open a URL reads the failure from a Fix link. That context includes the error-context snapshot: the page's accessibility tree at the moment of failure. In VS Code, the Currents extension shows your CI runs, failures and flaky tests next to the code, its Fix actions send the error, stack, test history and error-context snapshot to the editor's agent, and its Trace Viewer streams a failed attempt's trace into an editor tab, with nothing to download.
Healer and agent gotchas
The healer looks like the shortcut for every red test, and its output needs the closest review of anything the agents produce.
Anti-pattern
Healing every red test
Several specs fail in CI. You run the healer on each one and merge whatever comes back green or skipped.
Fix
Review every healer patch against the same checklist as a new test. For a failing test, the healer suggests a patch such as a locator update, a wait adjustment or a data fix, and a wait adjustment is exactly what the review rejects. The healer's output is either a passing test or a skipped one, which it produces when it believes the functionality is broken. Treat a newly skipped test in a pull request as a failed review, not a fix: someone has to confirm the feature is broken.
Healed is not correct
"Self-healing" means a test was changed until it passed, not that anyone showed it was right. A proposal for a triage agent warned that the healer is built to get failing tests passing, so it may rewrite a test to match a real app bug (#43675). A maintainer replied that nowadays you are probably better off asking your agent to fix the tests instead of using the healer at all. The proposal was closed as not planned. Use the healer for locator drift after a UI change, and fix CI failures from the trace.
Stale definitions and auth state
Two setup details come back to bite the agents later. Definitions you generated once go stale across Playwright upgrades, and agents running old definitions miss the new tools and instructions, so regenerate them with every version bump. The auth file your setup project writes and MCP loads stays out of the repo, because it can hold cookies and headers that impersonate the test account.
Where Copilot stops helping
Copilot writes good tests for flows it can see and your instructions describe. Hidden state is where it stops: seeded data, feature flags, a third-party identity provider. Write that fixture yourself, and let Copilot fill in the steps on top of it.
Don't use Copilot to fix flaky infrastructure either. When a spec fails differently across repeats, the cause is often the environment or the data, and an edit to the test only hides it. Fix the environment, then let the stress run prove the spec again.
Everywhere else, the bar doesn't move. A Copilot spec merges after it passes every repeat under the CI config and survives review, and a red run gets fixed from the trace, not from the log.
Frequently asked questions
How do I connect Playwright MCP to GitHub Copilot in VS Code?
Register the server with code --add-mcp, the way Playwright's MCP guide does. Connecting Playwright MCP to Copilot has the full setup.
What should go in copilot-instructions.md for Playwright tests?
Put rules in it that name your fixtures file, your auth project and your config, and give the reason with each rule so Copilot can apply it to cases the rule doesn't list. Put the file at .github/copilot-instructions.md. The generic instructions file anti-pattern shows a full example.
What are the Playwright test agents?
Playwright's Test Agents are a planner, a generator that turns the planner's Markdown plan into tests, and a healer that patches failing ones. The init-agents command adds their definitions to the repo, and Playwright's docs say to regenerate the definitions whenever Playwright is updated. Installing the Test Agents covers the setup.
Can I trust the Playwright healer agent's fixes?
Not without review. Review every healer patch against the same checklist as a new test: for a failing test, the healer suggests a patch such as a locator update, a wait adjustment or a data fix, and a wait adjustment is exactly what the review rejects. Healing every red test explains how to treat a newly skipped test.
Why does a Copilot test pass in the MCP browser but fail in CI?
By default, Playwright MCP's persistent profile keeps login state and cookies between sessions. In CI, each test runs in a new browser context with its own local storage, session storage and cookies, so none of the session's state is there. Start every MCP session fresh with --isolated, and load the signed-in state your tests get with --storage-state, as the stale session anti-pattern shows.
How do I check a Copilot-written Playwright test for flakiness before merging?
Run each new spec many times under the config CI uses, with retries off, so flakiness shows up before merge instead of hiding behind a retry. The --repeat-each <N> option runs each test N times, and the default is 1. Merging on one green run has the config and the GitHub Actions job.
How do I get Copilot to fix a failing Playwright test from CI?
Give it the trace, not the log: download the failed job's trace artifact and have Copilot read it with npx playwright trace. Coding agents can run that command to explore a Playwright trace and understand failing or flaky tests from the command line. Ask for the root cause before any code changes, as fixing from the log explains.
What should I check when reviewing AI-generated Playwright tests?
Reject any page.waitForTimeout(), reject CSS, XPath and position-based locators, check the assertions, and search for test.only and for a login in the test body. A green stress run says the test is stable, but it doesn't say the test checks anything. Reviewing Copilot's output walks through the checklist.




