DEV Community: Jakob Norlin

How To Write Playwright tests in minutes with Playwright MCP and Claude Code

Jakob Norlin — Mon, 05 Oct 2026 09:44:22 +0000

This article was originally published on the Endform blog.

By the end of this walkthrough you'll have a single Playwright test that Claude Code wrote against your live app, that you've reviewed in two passes, run repeatedly to check for flakiness, and committed next to the plain-English scenario it came from. The trick that makes it trustworthy: the agent reads locators off the running page through the Playwright MCP server instead of guessing them from your source code.

You need four things installed before step 1, so start there.

Before you start

Confirm all four of these first. Skipping one is the most common reason step 1 fails.

Node.js 20 or newer. Check with node --version. The MCP server launches through npx, so Node is required no matter how you installed Claude Code.
Claude Code, installed and signed in. Check with claude --version.
A Playwright project. You need playwright.config.ts at the repo root. No project yet? Run npm init playwright@latest to scaffold one.
An app to test. Local dev server or staging URL, either works. Playwright can start it for you when the config says so.

Got all four? Connect Claude Code to a browser.

The problem this setup solves

Here's a failure pattern you've probably lived through: Claude Code writes an end-to-end test, it passes locally, you merge, and CI goes red a day later on what looks like flakiness. The test was wrong from the start, it just had no way to show it.

The reason is where the locators came from. Reading your components without ever opening the app, an agent spots a button with a class like .btn-primary and writes a selector against it. Then a component library or some runtime logic rewrites that class on its way to the DOM, and by the time the browser renders, the selector points at a hashed string, a restructured node, or nothing. Nobody caught it because nobody ran the test against a real page. CI is the first thing that does.

Compare the two ways the same button gets targeted:

// Hallucinated: guessed from training data, does not exist on this page
await page.locator("#submit-btn").click();

// Grounded: read from the accessibility tree Claude Code can see
await page.getByRole("button", { name: "Place order" }).click();

Anthropic's Model Context Protocol is what closes the gap. The Playwright MCP server hands Claude Code a live browser: it can open the app, walk the accessibility tree, and build locators out of the roles and names the page actually exposes. It's working from a structured snapshot rather than a screenshot, which keeps the locators stable and the token cost low, because the model reasons over text it can already read. Same model, better inputs. Nothing here is a capability upgrade, only an access one.

Step 1: Register the Playwright MCP server

A single command wires the server into Claude Code:

claude mcp add playwright -- npx -y @playwright/mcp@latest

That entry gets saved to your local config, and the server process spins up the next time you open a session. -y skips the install confirmation npx would otherwise wait on, and @latest grabs the newest published build so you're not stuck on a stale cache.

By default this is a personal, single-project entry. Working on a team? Add --scope project, which writes the same config to a .mcp.json at the repo root so everyone shares one server without redoing setup:

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

Don't trust it until you've checked it. Run claude mcp list and look for ✔ Connected. Immediately after adding, you may catch a ✘ Failed to connect while npx is still pulling the package in the background; run the command again a few seconds later and it usually clears.

If retrying doesn't clear it, the problem is elsewhere. Claude Code runs the server as a subprocess in its own environment, and that subprocess can't always resolve npx the way your interactive shell does. Homebrew-installed Node on macOS is the usual culprit. Give it the absolute binary path instead of trusting PATH:

claude mcp remove playwright
claude mcp add playwright -- $(which npx) -y @playwright/mcp@latest

Run claude mcp list once more and wait for ✔ Connected before continuing.

Connected only means the process is alive. It doesn't prove Claude Code can actually drive a browser yet. Open a session and call the tool by name, otherwise Claude Code might reach for a Bash command instead of the MCP server:

Using Playwright MCP, open [your app's local URL] and tell me the page title and the first heading you see.

If it answers with something concrete off the page, not a hedge and not a generic description, the tool works. That answer is coming from a live snapshot rather than memory, which is the entire reason you connected it.

These commands are current as of August 2026. MCP tooling changes quickly, so if a command here stops matching what you see, check the official Playwright MCP repo. Server verified and driving a browser, the next hurdle is login.

Step 2: Get past the login wall with storage state

Nearly every test worth writing sits behind authentication. A checkout, a settings screen, an admin panel, all of them dead ends if the agent can't clear the sign-in page.

The MCP server has no idea about your suite's existing auth. It either carries its own browser profile across sessions or, in isolated mode, boots logged out every time. Either way it's disconnected from however your tests currently authenticate.

Fix it by launching the server with a session already loaded:

npx @playwright/mcp@latest --isolated --storage-state .auth/user.json

--isolated holds the profile in memory rather than writing it to disk, so every session starts fresh. --storage-state reads a saved authenticated session from a file, and anything that changes mid-session gets thrown away at the end. But that file has to exist first.

Playwright's auth docs suggest a dedicated setup test that signs in and saves the session:

import { test as setup } from "@playwright/test";

const authFile = ".auth/user.json";

const password = process.env.TEST_USER_PASSWORD;
if (!password) {
  throw new Error("TEST_USER_PASSWORD is not set");
}

setup("authenticate", async ({ page }) => {
  await page.goto("https://your-app.example.com/login");
  await page.getByLabel("Email").fill("test-user@example.com");
  await page.getByLabel("Password").fill(password);
  await page.getByRole("button", { name: "Log in" }).click();
  await page.waitForURL("**/dashboard");
  await page.context().storageState({ path: authFile });
});

Wire it to run automatically by adding a setup project in playwright.config.ts that the browser projects depend on:

projects: [
  { name: 'setup', testMatch: /auth\.setup\.ts/ },
  {
    name: 'chromium',
    use: { storageState: '.auth/user.json' },
    dependencies: ['setup'],
  },
],

Run it once:

npx playwright test --project=setup

When it finishes, .auth/user.json holds a live authenticated session, and auth.setup.ts is now part of the suite, so login logic lives in exactly one place.

Worth doing if your app allows it: create a throwaway test user through an API or seed script before login and tear it down after. Claude Code pokes at the app while it explores, and a disposable account keeps it from mutating a shared login someone else is on.

With the file in place, re-register the server so it loads that session:

claude mcp remove playwright
claude mcp add playwright -- npx -y @playwright/mcp@latest --isolated --storage-state .auth/user.json

For teams, mirror it in .mcp.json:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state",
        ".auth/user.json"
      ]
    }
  }
}

For messier auth flows, Endform's Playwright MCP guide goes deeper on this.

Now that Claude Code browses as a logged-in user, it's time to write the prompt that turns a described flow into a committable test.

Step 3: Build the prompt in three parts

This step is where a shippable test and a throwaway one diverge. Rather than one rambling paragraph that asks for a test and hopes, split the prompt into three parts that each do one job.

Part one is environment setup: the app-specific facts the agent can't deduce on its own.

The website under test is at https://staging.yourapp.com.
You're already logged in as a test user through the storage state configured earlier.
The test user's cart currently holds one item, a placeholder t-shirt priced at $24.99.

Part two is the scenario, phrased the way you'd brief a teammate, not as pseudocode:

# Guest checkout with a saved card
1. Open the cart page.
2. Proceed to checkout.
3. Confirm the shipping address shown is the default one.
4. Select the saved Visa card ending in 4242.
5. Place the order.
6. Confirm the order confirmation page shows an order number and the correct total.

Keep this as a markdown file in the repo next to the tests it drives, not buried in a chat log. Playwright Test Agents work the same way: a planner writes the scenario as markdown, and a later step compiles it into code. Splitting the two into separate, reviewable artifacts is worth carrying over here.

This part is also the one nobody on the team can write better than you. The environment facts are just facts, and the system prompt below is boilerplate you reuse everywhere. The scenario is the only part carrying judgment: does the address get confirmed before payment, does the saved card matter more than a fresh one, is the confirmation total worth asserting or is a loaded page enough? An agent can't rank those. Someone who knows the product has to.

Part three is the system prompt, the standing rules that ride along on every test and describe what "good" looks like, not just what to do:

You are a Playwright test generator.
Explore the app using the Playwright MCP tools before writing any code, don't generate steps from assumption alone.
Prefer getByRole, getByLabel, and getByTestId locators over CSS selectors or XPath.
Don't add manual waitForTimeout calls, rely on Playwright's built-in auto-waiting and retrying assertions instead.
Group related steps with test.step for readability in the trace viewer.
Assert on outcomes a user would actually see, not on incidental implementation details.
Save the finished test to the tests directory, run it, and keep iterating until it passes.

You don't have to write this cold. Debbie O'Brien, a longtime Playwright advocate and ex-member of Microsoft's Playwright team, keeps a public set of prompt files for exactly this, a better base than reinventing it.

Stacked together, this is the full message to Claude Code:

You are a Playwright test generator.
Explore the app using the Playwright MCP tools before writing any code, don't generate steps from assumption alone.
Prefer getByRole, getByLabel, and getByTestId locators over CSS selectors or XPath.
Don't add manual waitForTimeout calls, rely on Playwright's built-in auto-waiting and retrying assertions instead.
Group related steps with test.step for readability in the trace viewer.
Assert on outcomes a user would actually see, not on incidental implementation details.
Save the finished test to the tests directory, run it, and keep iterating until it passes.

The website under test is https://staging.yourapp.com.
You're already logged in as a test user through the storage state configured earlier.
The test user's cart currently holds one item, a placeholder t-shirt priced at $24.99.

# Guest checkout with a saved card
1. Open the cart page.
2. Proceed to checkout.
3. Confirm the shipping address shown is the default one.
4. Select the saved Visa card ending in 4242.
5. Place the order.
6. Confirm the order confirmation page shows an order number and the correct total.

The proof this prompt works is watching the agent call the MCP tools to explore before it writes any test code. A "explore first" instruction only counts if the agent obeys it. Three parts, three jobs, one message. Next, the generation itself.

Step 4: Let it generate the test

One look at the page isn't where Claude Code stops. It keeps navigating and reading through the MCP server until it has actually seen every element the scenario names. That's what separates this from feeding a model a plain-English description and hoping.

Watch a run and the sequence is plain: open the page, click through the scenario's steps, read back what each returned, and only then start writing assertions. It writes the spec last, runs it, and keeps tweaking until it passes instead of handing you untested code.

A real example: on a logout scenario, two headings both matched "Secure Area," so Playwright threw a strict mode violation, because a locator meant to act on one element matched several. Claude Code read the error, diagnosed it, and appended exact: true so the locator demanded the full heading text rather than a substring. That correction landed in the same pass, no nudge from the developer.

A checkout with a cart, saved card, and confirmation page runs the same loop, step by step, until green. Here's a second flow to show it's not a one-off.

Endform's guide to shipping quality end-to-end tests with Playwright MCP has a scenario worth reusing: check that a newly created team shows up in an activity log. Sign in, confirm a signup event is already logged, create a team, confirm the new event lands. Endform walks through the scenario and the review, not the code, so here's a plausible test around that flow, in the shape Claude Code would generate it against a live app:

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

test("new team activity appears in the activity log", async ({ page }) => {
  await test.step("open the activity log", async () => {
    await page.goto("https://staging.yourapp.com/dashboard");
    await page.getByRole("link", { name: "Activity" }).click();
  });

  await test.step("confirm the signup event is already logged", async () => {
    await expect(page.getByText("you signed up")).toBeVisible();
  });

  await test.step("create a new team", async () => {
    await page.getByRole("button", { name: "Create a new team" }).click();
    await page.getByLabel("Team name").fill("QA Playground");
    await page.getByRole("button", { name: "Create team" }).click();
  });

  await test.step("confirm the new team event appears in the log", async () => {
    await expect(page.getByText("you created a new team")).toBeVisible();
  });
});

Notice how deliberate the file is. Every link and button name is text Claude Code read off the page. The test.step blocks track the scenario one to one, so a failure drops you straight on the broken step. No manual waits anywhere, because the retrying assertions cover timing.

You end up with a runnable file that clears its first run more often than not, precisely because each locator was verified against the page before a line got written. That still isn't the same as a good test, which is what step 5 is for.

Step 5: Review it in two passes

Passing once doesn't earn a test a place in the suite. Run two review passes, because they catch different things: one on the code, one on the meaning.

Pass one is the code. Read it and ask if you'd have written it this way. Generated tests tend toward the baroque, redundant checks, extra steps, logic that folds down to less, and trimming that is usually the first win. Hold the locators to the priority you set (getByRole and getByTestId over CSS or XPath), swap out anything brittle, and make sure each assertion proves something a user would notice rather than just confirming an action didn't throw. The test.step groupings should read the way a person would narrate the flow.

Pass two is the one no linter will ever do for you, and it's the one that matters more. Put the scenario next to the finished test and ask whether the thing being verified still matches what the scenario meant, not just whether it's green. Tests drift here quietly. On that logout test, Claude Code noticed the login banner showed once and got eaten by the stored session, so it retargeted the assertion to the permanent heading before wrapping up. Useful that it caught it, but it happened during generation, not review, and that's the point: next time it might not, and this pass is your backstop.

The first draft gets much faster; the judgment moves into refinement. And that judgment, what the product does, what risk you're covering, what the scenario is really asserting, is yours to bring. Both passes done, one last check remains.

Step 6: Verify, then commit

The commands below use this tutorial's logout test as the example. A test that passed while being generated still hasn't earned your trust. Run it again, clean, outside the generation loop:

npx playwright test tests/logout.spec.ts

A single green run tells you almost nothing about reliability. Fire it several times in a row:

npx playwright test tests/logout.spec.ts --repeat-each 5

--repeat-each reruns the same test N times in one invocation. It's among the fastest ways to smoke out a test that's green most runs and red occasionally, the exact flakiness that tends to surface only once it hits CI.

Repeats clean? Commit the test together with the markdown scenario behind it:

git add tests/logout.spec.ts tests/scenarios/logout.md
git commit -m "Add logout test with scenario spec"

Committing them together keeps intent attached to implementation. Whoever reads the diff later sees what the test was meant to prove, not just the assertions.

One thing to check before that first commit: your .gitignore. A freshly scaffolded Playwright project ignores playwright/.auth/, its default spot for storage state. But this setup writes to .auth/ at the repo root, a different path the default rule doesn't cover, which means a live authenticated session can slip into history unnoticed.

Add the right path first:

echo ".auth/" >> .gitignore

That one line keeps the session out of your repo history by intent rather than luck.

Verified, stable over repeats, and committed alongside its scenario, the test is a dependable addition. What gets harder from here: longer flows, data that shifts between runs, and auth beyond a plain login form.

Where this workflow falls down

Trust comes from being straight about where Claude Code struggles, not just where it shines. Four things break it fairly predictably.

Long multi-step flows. The longer the flow, the more the agent loses the thread, since each step starts from a fresh snapshot rather than the whole sequence before it, and long MCP sessions dropping browser context is a known issue. Splitting the flow into smaller scenarios and stitching them later holds up better.

Data that changes between runs. The agent tends to assert against whatever it saw at generation time, a timestamp, an order ID, a count, and those move on the next run. Assertions last longer when they target something stable: a confirmation state, a completed action, the presence of a result, not the exact value from one run.

Deep conditionals. While generating, the agent only travels one branch, one role, one account state, one flag. Branches it never walks stay invisible to it. Prompt each branch on its own, or write the conditional logic yourself, rather than expecting one pass to find every path.

OAuth and third-party auth. Usually the first wall you hit. Redirects out to Google, Microsoft, or any external identity provider leave your app, and the agent's control loop isn't built to follow through the handoff. One developer automating GitHub's OAuth earned a temporary IP ban for it, and other providers can react to automated logins the same way, which makes this genuinely fragile. The move is to authenticate in a separate setup step, save the session with storageState, and generate against an app that's already logged in.

None of these shrink the workflow's value. They just mark where a scenario needs prep before you hand it over.

What comes next: keeping the suite fast

We opened with a test that looked done and broke in CI regardless. Claude Code explored the real app through Playwright MCP, checked what was on the page, and produced a test you reviewed, verified, and committed.

That changes the economics of test creation. Once a trustworthy test costs minutes instead of hours, teams write more of them, and a bigger suite brings its own problem. Those tests still run in CI, and as the count climbs, the bottleneck moves from writing tests to running them fast without flakiness.

Endform runs every Playwright test on its own isolated machine in parallel, which keeps suite duration predictable no matter how many you add.

The Playwright + GitHub Actions setup that actually runs fast

Jakob Norlin — Tue, 15 Sep 2026 14:53:37 +0000

This article was originally published on the Endform blog.

By the end of this you'll have a Playwright pipeline that gives useful feedback on every PR and stays under five minutes on a single runner, no sharding required. You need a Playwright suite, a GitHub repo, and the default Actions workflow that npm init playwright@latest generated. Two changes carry most of the weight: caching the browser binaries and fixing parallelism. Both are config edits you can land in an afternoon.

Here's the complete setup first, then the reasoning behind each piece.

The complete workflow

Two files. Worker count, fullyParallel, and the reporters go in playwright.config.ts. Caching, the Chromium-on-PR split, and the artifact upload go in the workflow YAML.

playwright.config.ts:

typescript

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  fullyParallel: true, // parallelize tests within a file, not just across files
  forbidOnly: !!process.env.CI, // fail the build if a stray test.only is committed
  retries: process.env.CI ? 2 : 0, // retry flaky tests in CI only
  workers: process.env.CI ? "50%" : undefined, // scale workers to the runner; measure and raise from here
  reporter: [
    ["html"], // full report, uploaded as an artifact
    ["github"], // inline annotations on the run summary
  ],
  use: {
    trace: "on-first-retry", // capture a trace when a test retries
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
  ],
});

.github/workflows/playwright.yml:

yaml

name: Playwright Tests
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
          cache: "npm" # caches ~/.npm, the safe npm cache, not node_modules

      - name: Install dependencies
        run: npm ci

      # Cache the browser binaries. The lockfile is a proxy for the
      # Playwright version, so it usually turns over when you update Playwright.
      - name: Cache Playwright browsers
        id: playwright-cache
        uses: actions/cache@v6
        with:
          path: ~/.cache/ms-playwright
          key: ${{ runner.os }}-playwright-${{ hashFiles('package-lock.json') }}

      # Cache miss: download browsers and system libraries together
      - name: Install browsers and system dependencies
        if: steps.playwright-cache.outputs.cache-hit != 'true'
        run: npx playwright install --with-deps

      # Cache hit: binaries are restored, but system libraries still need installing
      - name: Install OS dependencies for browsers
        if: steps.playwright-cache.outputs.cache-hit == 'true'
        run: npx playwright install-deps

      # Chromium only on PRs for fast feedback; the full browser set on merges to main
      - name: Run Playwright tests
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            npx playwright test --project=chromium
          else
            npx playwright test
          fi

      # Upload the report whether tests pass or fail, so failures are never lost
      - name: Upload Playwright report
        uses: actions/upload-artifact@v7
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 14

Drop both in, push, and the first run populates the cache while every run after it skips the download. The rest of this post explains why each block earns its place.

Where the time actually goes

The default workflow from npm init playwright@latest works, it just spends most of its time on setup and a serial test run. On a public repo with about 40 lightweight tests, the baseline came in at 3m 18s. Treat that as a fixed number for comparing fixes, not a prediction of your own run times.

Only two steps mattered. Install Playwright Browsers took 42 seconds because it downloads Chromium, Firefox, and WebKit plus their system libraries on every single run, whether or not those browsers changed. Run Playwright tests took 2m 25s, and that number is about parallelism. The generated config pins CI to one worker:

typescript

workers: process.env.CI ? 1 : undefined,

So the suite runs close to one test at a time even with idle cores. Checkout, Node setup, and npm ci came in at a second or two each and aren't worth touching.

Two independent bottlenecks: repeated download overhead, and serial execution. Here's each fix.

Fix 1: cache the browser binaries

Playwright installs its browsers to ~/.cache/ms-playwright, which on the Linux runner resolves to /home/runner/.cache/ms-playwright. That directory is what you cache. The binaries only change when your Playwright version changes, so keying the cache to a hash of package-lock.json is a convenient proxy. Updating Playwright turns the cache over, though any unrelated dependency edit does too, which forces the occasional slow run you didn't strictly need.

One thing most guides skip: the cache stores the browser binaries but not the OS libraries they need, because those get installed system-wide with apt and never land in ~/.cache/ms-playwright. On a cache hit the binaries are present but the libraries are missing, and tests fail with Host system is missing dependencies to run browsers. So you install the libraries on a cache hit too, just without the download:

yaml

steps:
  - name: Cache Playwright browsers
    id: playwright-cache
    uses: actions/cache@v6
    with:
      path: ~/.cache/ms-playwright
      key: ${{ runner.os }}-playwright-${{ hashFiles('package-lock.json') }}

  - name: Install Playwright browsers and system dependencies
    if: steps.playwright-cache.outputs.cache-hit != 'true'
    run: npx playwright install --with-deps

  - name: Install OS dependencies for browsers
    if: steps.playwright-cache.outputs.cache-hit == 'true'
    run: npx playwright install-deps

The id on the cache step is what lets the two install steps read cache-hit and pick a branch. On a cache miss, playwright install --with-deps downloads browsers and libraries together. On a cache hit, playwright install-deps runs instead, every time, installing only the libraries. It's fast because there's no download, just a dependency check apt has already satisfied. Each job starts from a clean machine, so this isn't a one-off step you skip later.

One alternative skips caching: run the job inside the official mcr.microsoft.com/playwright image, which ships with browsers and OS packages preinstalled. You're trading the browser download for an image pull rather than removing it. It's a common choice for visual regression work where consistent rendering matters, but for most suites the cache is lighter.

Fix 2: run tests in parallel with workers

The 2m 25s test run is Playwright doing exactly what the config told it to. Two changes fix it.

fullyParallel: true lets tests within a single file run across workers. By default Playwright parallelizes separate files but runs tests inside one file in order, so a suite concentrated in a few large files leaves most workers idle. The second change replaces the hard one-worker cap with a percentage:

typescript

export default defineConfig({
  fullyParallel: true, // top-level, applies to every project
  workers: process.env.CI ? "50%" : undefined, // top-level, not inside a project
  use: {/* ... */},
  projects: [/* chromium, firefox, webkit */],
});

Both keys sit at the top level of defineConfig, alongside use and projects, not nested inside any one project.

On the worker count, one assumption gets repeated: that GitHub's free runners are 2-core. That's true for private repos, but public repos now get 4-core Linux runners for free. On a 2-core runner undefined resolves to one worker, so the default is effectively serial. On a 4-core runner the same undefined gives you two workers out of the box.

Runner	Cores	50% gives you	Worth trying
Private repo, ubuntu-latest	2	1 worker	Set to 2 explicitly
Public repo, ubuntu-latest	4	2 workers	75% or 100%, then measure
Larger runner	8	4 workers	75% and up, more headroom

Start at 50%, look at wall-clock time on your suite, and raise it in steps until the run stops getting faster or the tests start going flaky. There's no single correct number, since it depends on core count, how heavy your tests are, and how much memory each browser instance eats. The thing not to do is push workers well above your core count. Once workers contend for the same cores and RAM, you trade a faster run for memory pressure and intermittent failures that didn't exist serially.

With fullyParallel on and the cap lifted, the test run on a 4-core runner drops to roughly half, and the install step is already cached. Those two fixes together pull the whole job under five minutes.

Fix 3: run only the browsers you need

The baseline was hiding something. The default config runs your tests against Chromium, Firefox, and WebKit, so those 40 tests were actually 120 test runs on every push. A good share of that 2m 25s was the same assertions executing twice more against browsers that rarely surface a bug the first one missed.

If your product doesn't need every browser verified on every change, tier it by event. Run Chromium on every PR, where the feedback loop needs to be fast and most rendering and logic bugs show up. Save the full three-browser sweep for merges to main or a nightly schedule. It's a single flag switched on the triggering event:

yaml

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      # checkout, setup-node, cache, and install from the earlier sections
      - name: Run Playwright tests
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            npx playwright test --project=chromium
          else
            npx playwright test
          fi

On a PR this runs Chromium alone. On a push to main it falls through to the full set. This keeps everything in one job. Local runs are unaffected, since the conditionals key off the CI event.

If you'd rather run the three browsers as separate parallel jobs on main, a conditional matrix does that:

yaml

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        project: ${{ github.event_name == 'push'
          && fromJSON('["chromium", "firefox", "webkit"]')
          || fromJSON('["chromium"]') }}
    steps:
      # same setup steps
      - run: npx playwright test --project=${{ matrix.project }}

A push to main fans out into three jobs, one per browser; a PR collapses to a single Chromium job. It stays bounded at three jobs, so it doesn't drift into open-ended job-splitting.

One caveat on WebKit: the build Playwright runs on Linux tracks WebKit's main development branch, often ahead of what Apple ships in Safari, and it lacks Apple's platform integrations. A green Linux WebKit run is a good signal for layout and JavaScript bugs, but it's not proof the page looks right in Safari. When that distinction matters you need macOS runners, which is a separate decision from this workflow.

Get the failure report off the runner

Playwright writes an HTML report on every run, but a CI runner is torn down when the job ends, so by default that report vanishes and you never see it. Teams usually discover this on their first failing run, when they go looking for the detail behind a red X and find nothing left to open.

Upload it as an artifact before the job exits:

yaml

steps:
  - name: Upload Playwright report
    uses: actions/upload-artifact@v7
    if: ${{ !cancelled() }}
    with:
      name: playwright-report
      path: playwright-report/
      retention-days: 14

The if: ${{ !cancelled() }} is doing real work. Without it, the step only runs when everything before it passed, which is backwards, since the run you most want the report for is the one that failed. This uploads whether tests passed or failed and skips only on a manual cancel. Use retention-days: 14 for active development and 30 on release branches.

The artifact gives you the full report but costs a few clicks. You can't open the HTML file directly, since it loads its data over HTTP, so you download the zip, unzip it, and run npx playwright show-report path/to/playwright-report. Fine when you need a trace, more friction than most failures deserve.

That's where a second reporter comes in. The github reporter writes failures as inline annotations in the Actions UI, so a failed assertion shows up on the run summary and against the offending line in the diff, no download in the loop. Add it alongside the HTML reporter rather than replacing it:

typescript

export default defineConfig({
  reporter: [["html"], ["github"]],
  // ... rest of your config
});

Now a failed run annotates the summary with what broke and where, and the full HTML report is still attached for the times you need the trace, screenshots, and step timeline.

Passing config and secrets

If your tests need a base URL or an API token, pass it through the test step with an env block. Non-sensitive values can go straight in the workflow; anything secret goes in a repository secret and gets referenced:

yaml

steps:
  - name: Run Playwright tests
    env:
      BASE_URL: https://staging.example.com
      API_TOKEN: ${{ secrets.API_TOKEN }}
    run: # ... as above

When to add sharding (and when not to)

Sharding splits your suite across several CI jobs running in parallel, each handling a slice, with a final step merging the reports. It's the standard answer to a slow Playwright suite, and it works, but it solves a problem you don't have until a single runner genuinely can't keep up.

The decision rule: start with workers and fullyParallel, tune the worker count, and measure your best single-runner time. If you've maxed that and still need more speed, try a bigger runner before sharding. An 8 or 16-core GitHub-hosted runner gives you more workers without the merge-reports step or shard-count maintenance. Only reach for sharding when one runner, even a larger one, can't finish inside your PR review window.

Suite size	Single-runner time	What to do
Under 50 tests	Well under 5 min	Workers and fullyParallel are plenty
50–200 tests	Around 3 to 5 min	Move to a bigger runner before you shard
Over 200 tests, or 10+ min	Past your PR window	Shard, or move the run off your own CI

Run time is what matters here, not test count. A suite of heavy end-to-end flows hits the ceiling sooner than the same number of light page checks. Sharding buys wall-clock time; it costs more CI minutes, a merge-reports step, and a shard count you revisit as the suite grows. That's maintenance you take on deliberately, not a default the moment a run feels slow.

Common setup mistakes

Installing browsers without --with-deps. npx playwright install alone fetches binaries but not the system libraries, and runners don't ship those. Tests fail with a "Host system is missing dependencies" error that says nothing about the cause. Use --with-deps on a cache miss and install-deps on a cache hit.

Caching node_modules instead of the npm cache. A restored node_modules can carry platform-specific or partially built dependencies that don't match the runner, surfacing as subtle failures. Cache ~/.npm by setting cache: 'npm' on the setup-node step and let npm ci rebuild cleanly each run.

Setting workers too high for the runner. More workers stop helping once they outnumber the cores, and past that point the browser instances contend for CPU and memory, trading speed for flakiness. Scale to the runner and raise only as far as your measurements stay stable.

Forgetting the github reporter. Without it, a failed run tells you something broke but not what. Adding ['github'] alongside ['html'] puts the failure inline on the summary.

Wrapping up

A fast Playwright pipeline on GitHub Actions doesn't require sharding. Caching the browser binaries and tuning parallelism for your runner are both afternoon-sized config changes, and they pay off on every PR rather than once. The single-runner setup holds for a good while as a suite grows, and outgrowing it is a scaling decision to make on purpose when your numbers cross the line, not evidence something was done wrong.

If your suite has crossed that line and you don't want to own shard counts, matrix jobs, and report merging, Endform gives you the same parallelism without the CI plumbing.