End-to-End Tests for Static Sites with Playwright

Most of a static site cannot break at runtime: it is HTML and CSS that either built correctly or did not. The few parts that can break are the ones readers use most — search, the theme toggle, the mobile menu, copy buttons on code samples, the language switcher, a contact form backed by an edge function. They depend on JavaScript, on a search index generated at build time, and sometimes on a serverless function, and they fail in ways that build checks cannot see: a search index that loads from the wrong path, a menu button that no longer toggles after a component refactor, a form that posts to a function that was renamed.

This guide writes a compact Playwright suite for those flows and runs it against every preview deploy. It is part of Testing Static Sites in CI. The examples come from a 410-page Astro site with Pagefind search, a theme toggle, a mobile menu and a Cloudflare Worker contact form, and a 2,300-page Hugo docs site with a language switcher.

Prerequisites

• Preview deploys per pull request with the URL available to CI, as in Automating Preview Deploy Pipelines with GitHub Actions.
• @playwright/test 1.48 or newer.
• A short list of the flows that matter, ideally informed by analytics on which features are used.

Step 1: Configure Playwright for a Remote Base URL

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: 'tests/e2e',
  timeout: 20_000,
  retries: process.env.CI ? 2 : 0,
  reporter: [['list'], ['html', { open: 'never' }]],
  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:4321',
    trace: 'on-first-retry',
    extraHTTPHeaders: process.env.PREVIEW_AUTH ? { Authorization: `Basic ${process.env.PREVIEW_AUTH}` } : {}
  },
  projects: [
    { name: 'desktop-chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'mobile-webkit', use: { ...devices['iPhone 14'] } }
  ],
  webServer: process.env.BASE_URL ? undefined : { command: 'npx serve dist -l 4321', port: 4321 }
});

When BASE_URL is set, tests run against the preview; locally, Playwright serves the build directory itself. extraHTTPHeaders passes basic-auth credentials for previews protected as in Password-Protecting Preview Deployments. trace: 'on-first-retry' records a full trace — DOM snapshots, network, console — only when a test fails once, which makes failures diagnosable without slowing every run.

Step 2: Test the Flows Readers Use

Write one test per flow, locate elements by role and accessible name, and assert on outcomes rather than implementation.

Search — the index loads, results appear, a result navigates:

test('search finds a guide and navigates to it', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('button', { name: 'Search' }).click();
  const dialog = page.getByRole('dialog', { name: 'Search' });
  await dialog.getByRole('searchbox').fill('cache headers');
  const first = dialog.getByRole('link').first();
  await expect(first).toContainText(/cache/i);
  await first.click();
  await expect(page).toHaveURL(/cache/);
  await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
});

Theme toggle — switches, persists across navigation and reload:

test('theme choice persists', async ({ page }) => {
  await page.emulateMedia({ colorScheme: 'light' });
  await page.goto('/guide/');
  await page.getByRole('button', { name: /dark|theme/i }).click();
  await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark');
  await page.goto('/guide/install/');
  await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark');
});

Mobile menu — opens, moves focus, closes with Escape and returns focus:

test('mobile menu is keyboard operable', async ({ page, isMobile }) => {
  test.skip(!isMobile);
  await page.goto('/');
  const button = page.getByRole('button', { name: 'Menu' });
  await button.click();
  await expect(page.getByRole('navigation', { name: 'Primary' })).toBeVisible();
  await page.keyboard.press('Escape');
  await expect(button).toBeFocused();
});

Step 3: Forms and Functions Without Side Effects

A contact form posts to an edge function that sends email. Testing it end to end against a preview must not send real mail on every pull request. Two options: the preview environment configures the function with a sandbox mail provider or a DRY_RUN variable, or the test intercepts the request and asserts on what would have been sent.

test('contact form validates and submits', async ({ page }) => {
  await page.goto('/contact/');
  await page.getByRole('button', { name: 'Send' }).click();
  await expect(page.getByText('Please enter your email')).toBeVisible();

  await page.getByLabel('Email').fill('reader@example.com');
  await page.getByLabel('Message').fill('Test from CI');
  const response = page.waitForResponse('**/api/contact');
  await page.getByRole('button', { name: 'Send' }).click();
  expect((await response).status()).toBe(200);
  await expect(page.getByRole('status')).toHaveText(/thanks/i);
});

With the function in dry-run mode on previews, this test exercises the real route, validation and response handling — which caught a renamed function route that would have silently broken the form — without sending anything. The function itself is described in Adding a Contact Form with Cloudflare Workers.

Step 4: Crawl-Style Checks With the Same Tooling

Playwright is also a convenient way to run broad, shallow checks that need a browser: every page in a sample loads without console errors, every language-switcher option on a page leads to a 200, every "Edit this page" link points at a file that exists. These are loops rather than scripted flows:

for (const url of sampleUrls) {
  test(`no console errors on ${url}`, async ({ page }) => {
    const errors: string[] = [];
    page.on('pageerror', (e) => errors.push(e.message));
    page.on('console', (m) => m.type() === 'error' && errors.push(m.text()));
    await page.goto(url);
    await page.waitForLoadState('networkidle');
    expect(errors).toEqual([]);
  });
}

On the Hugo docs site this caught a script that threw on pages without code blocks, introduced when a copy-button component assumed at least one <pre> existed.

Step 5: Keep It Fast and Stable

The suite runs in the official Playwright container (mcr.microsoft.com/playwright:v1.48.0-noble), which avoids a browser download per run. Tests run fully parallel with fullyParallel: true; there is no shared state on a static site, so they are safe to parallelise. The whole suite — 11 flow tests and 40 crawl-style checks across two projects — took 110 seconds on the Astro site and 190 seconds on the Hugo site.

Flakiness came almost entirely from two sources: fixed waits (waitForTimeout) left in early tests, and a search index that sometimes took longer than the default 5-second assertion timeout to load on cold previews. Replacing the waits with web-first assertions and giving the search assertion an explicit 10-second timeout brought flaky failures from 7 per 100 runs to under 2.

Choosing What Not to Test

A Playwright suite for a static site should stay small. Content is not tested end to end: pages are checked by the build-output layer, and clicking through navigation to reach every page is slow and adds nothing a link checker does not already do. Styling is tested by visual regression, not by asserting CSS values. Third-party widgets are tested only at their integration point — the placeholder renders and the consent-gated load happens — never their internal behaviour, which you cannot fix anyway. Keeping to roughly one test per interactive feature is what kept this suite under two minutes and made each failure mean something.

Measured Impact

The two production escapes were both in WebKit-specific clipboard behaviour on older iOS versions not covered by the emulated device profile.

Pitfalls & Rollback

• Testing implementation details. Selectors like .btn-primary > svg break on refactors; use roles and names.
• Sending real side effects. Use dry-run modes or request interception for forms.
• Running against production. Tests should gate merges, which means running against previews.
• Ignoring WebKit. Clipboard, <dialog> and focus behaviour differ enough to matter.
• Rollback: the suite is a CI job; making it non-required disables the gate without touching the site.

Conclusion

A static site has only a handful of flows that can break at runtime, and they are the ones readers notice. A Playwright suite of a dozen role-based tests, run against every preview in Chromium and WebKit with traces on retry, catches almost all of those breakages before merge in about two minutes.

FAQ

What should end-to-end tests cover on a static site?

The small number of features that depend on JavaScript or a server function and that readers notice when they break. Typical examples are site search, the theme toggle, the mobile navigation menu, copy-to-clipboard buttons, language switchers, tabs and any form backed by an edge function.

Should Playwright tests run against a local build or the preview deploy?

Against the preview when possible, because it includes the host's redirects, headers and functions. A local static server over the build directory is a good fallback for fast feedback and for testing on pull requests from forks, which may not get preview deploys.

How do I make Playwright tests on static sites less flaky?

Never wait for fixed time periods. Use web-first assertions that wait for state, such as expecting a dialog to be visible or a URL to change, locate elements by role and accessible name, and retry failed tests once or twice in CI.

How many browsers should I test?

Chromium catches most problems. Adding WebKit is worthwhile for sites with many iPhone readers, because Safari differs in clipboard, dialog and focus behaviour. Firefox is optional for most static sites. Mobile viewport emulation in Chromium covers responsive layouts.

Related

• Parent: Testing Static Sites in CI — where end-to-end tests fit.
• Accessibility Testing with axe and pa11y in CI — the same Playwright setup running axe.
• Running Smoke Tests Against a Preview URL — a lighter post-deploy check.
• Adding Pagefind to an Astro Site — the search the tests exercise.
• Handling Form Submissions on a Static Site — the form backend.