
Every team I've worked on eventually reaches the same point with E2E tests: they start as a handful of scripts someone wrote in a hurry, and six months later they're a tangled mess that breaks on every deploy. Tests duplicate locators, share state in weird ways, and nobody wants to touch them.

I got tired of rebuilding the same structure from scratch every time, so I built a template that captures the patterns I keep reaching for. It's open source and you can grab it here: [playwright-ts-template-pom](https://github.com/Kazaz-Or/playwright-ts-template-pom).

To be honest I wanted to do it for a while but never had the time to write it down. Nowdays with the assist from your favorite coding agent I finally did, and this post is the write-up of the design decisions, the architecture, and how each piece fits together.

This post walks through the design decisions, the architecture, and how each piece fits together. It's not a Playwright tutorial — the docs are excellent for that. This is about the layer on top: how to organize a real test suite that doesn't fall apart at scale.

### Why Page Object Model?

The Page Object Model isn't new or exciting. That's kind of the point.

The idea is simple: every page in your app gets a class that owns all the locators and actions for that page. Tests never call `page.locator()` directly. Instead, they talk to the page object.

```typescript
// Without POM — locators scattered everywhere
test('should display hero heading', async ({ page }) => {
  await page.goto('/')
  const heading = page.getByRole('heading', { level: 1 })
  await expect(heading).toBeVisible()
})

// With POM — clean, readable, maintainable
test('should display hero heading @sanity', async ({ homePage }) => {
  await homePage.navigate()
  await expect(homePage.heroTitle).toBeVisible()
})
```

When a UI element changes, you fix it in one place — the page object — not in thirty tests. I've seen teams waste entire sprints updating selectors across test files because they didn't have this separation. It's the single most impactful pattern in test automation, and it's boring in the best possible way.

### The Architecture

Here's how everything is layered:

![Architecture Diagram](https://res.cloudinary.com/dtt2usukl/image/upload/v1788378917/pomframeworkstrucutre_dfbkox.png)

Tests sit at the top and only talk to the fixtures layer. Fixtures inject page objects, helpers, and API clients. Page objects compose shared components (like the navbar and footer). Everything below is infrastructure that tests don't need to know about.

This layering means a test file looks like a specification, not like Playwright API calls stitched together.

### Fixtures Are the Glue

Playwright's fixture system is one of its best features, and it's the backbone of this template. Instead of manually creating page objects in every test, they're injected automatically:

```typescript
import { test as base } from '@playwright/test'
import { HomePage } from '../pages/home.page'
import { AssertionsHelper } from '../helpers/assertions.helper'

export const test = base.extend<TestFixtures>({
  homePage: async ({ page }, use) => {
    await use(new HomePage(page))
  },
  assertions: async ({ page }, use) => {
    await use(new AssertionsHelper(page))
  },
  blogApi: async ({}, use) => {
    await use(new BlogApi())
  },
  // ... 11 fixtures total
})
```

Every test destructures exactly what it needs. No global setup, no shared mutable state, no import chains. If a test needs the homepage and the assertions helper, it asks for them. If it only needs the API client, it asks for that. Playwright handles lifecycle and teardown.

This is dependency injection done right — lightweight, explicit, and type-safe.

### Components: Shared UI Pieces

Most apps have elements that appear on every page — a navbar, a footer, a search bar. In the template, these are modeled as components that get composed into page objects through a base class:

```typescript
export abstract class BasePage {
  readonly navbar: NavbarComponent
  readonly footer: FooterComponent

  constructor(protected readonly page: Page) {
    this.navbar = new NavbarComponent(page)
    this.footer = new FooterComponent(page)
  }

  abstract get path(): string

  async navigate(): Promise<void> {
    await this.page.goto(this.path)
    await this.page.waitForLoadState('domcontentloaded')
  }
}
```

Every page object extends `BasePage`, so every page automatically has access to navbar and footer actions. No duplication, no forgetting to initialize them.

### Helpers: Reusable Assertions and Utilities

Raw `expect()` calls work fine, but they get repetitive. The template includes helpers that wrap common assertion patterns:

```typescript
// Domain-specific assertions
await assertions.assertNoImageErrors() // Checks every <img> loaded
await assertions.assertMetaTag({ property: 'og:title', content: 'My Post' })
await assertions.assertOpenGraphTags()
await assertions.assertHasHeadings()

// Navigation helpers
await navigation.assertLinkNavigation('About', /\/about/)
await navigation.goBack()

// Performance measurement
const metrics = await performance.assertBudget(PerformanceBudgets.static)
performance.printMetrics(metrics)

// Accessibility (axe-core)
await a11y.assertNoCriticalViolations({ disableRules: ['color-contrast'] })
```

These aren't clever abstractions — they're shortcuts for things you'd write over and over. The accessibility helper wraps `@axe-core/playwright` so you can run WCAG audits in a single line. The performance helper measures Web Vitals (TTFB, FCP, LCP, CLS) and asserts them against configurable budgets.

The image checker was actually an interesting problem to solve. On Chromium, checking `naturalWidth > 0` works immediately. On Firefox and WebKit, lazy-loaded images (especially Next.js optimized ones) report `naturalWidth` as 0 because they haven't decoded yet. The fix was to scroll each image into view and wait for the load event before checking:

```typescript
async assertNoImageErrors(): Promise<void> {
  const images = await this.page.locator('img').all();
  for (const img of images) {
    await img.scrollIntoViewIfNeeded();
    const naturalWidth = await img.evaluate((el) => {
      const imgEl = el as HTMLImageElement;
      if (imgEl.complete && imgEl.naturalWidth > 0) return imgEl.naturalWidth;
      return new Promise<number>((resolve) => {
        imgEl.onload = () => resolve(imgEl.naturalWidth);
        imgEl.onerror = () => resolve(0);
        setTimeout(() => resolve(imgEl.naturalWidth), 5000);
      });
    });
    const src = await img.getAttribute('src');
    expect(naturalWidth, `Image failed to load: ${src}`).toBeGreaterThan(0);
  }
}
```

Small detail, but this is exactly the kind of thing that breaks your CI at 3am and takes an hour to debug. Having it solved once in a helper means you never think about it again.

### API Testing Without a Browser

Not everything needs a browser. The template includes an API layer built on axios for testing endpoints directly:

```typescript
export class BlogApi {
  private readonly client: AxiosInstance

  constructor(baseURL?: string) {
    this.client = axios.create({
      baseURL: baseURL ?? EnvConfig.baseUrl,
      timeout: 15_000,
      validateStatus: () => true, // Never throw on status codes
    })
  }

  async checkPageExists(path: string): Promise<boolean> {
    const response = await this.client.get(path, { maxRedirects: 5 })
    return response.status >= 200 && response.status < 400
  }

  async getRssFeed(): Promise<ApiResponse<string>> {
    /* ... */
  }
  async getResponseHeaders(path: string): Promise<Record<string, string>> {
    /* ... */
  }
}
```

The `validateStatus: () => true` is intentional — it means axios never throws on HTTP errors, so you can assert on status codes explicitly in tests rather than catching exceptions. Makes tests much more readable.

API tests are fast because they skip browser rendering entirely. They're good for smoke-checking that pages return 200, RSS feeds are valid XML, and headers are set correctly.

### Test Data Factory

Hardcoded test data is a trap. It makes tests brittle and hides assumptions. The template uses a factory pattern with faker.js:

```typescript
test('search handles random queries @regression', async ({ homePage }) => {
  await homePage.navigate()
  const query = TestDataFactory.searchQuery() // Random word
  await homePage.navbar.search(query)
})

test('XSS payloads are handled safely @regression', async ({ homePage }) => {
  await homePage.navigate()
  for (const payload of TestDataFactory.xssPayloads()) {
    await homePage.navbar.search(payload)
    const title = await homePage.page.title()
    expect(title).not.toContain('xss')
    await homePage.navbar.clearSearch()
  }
})
```

The factory generates random search queries, fake blog slugs for 404 testing, XSS payloads for security tests, and viewport sizes for responsive testing. It keeps test data close to the tests that use it without coupling them to specific values.

### The Tagging Strategy

Every test in the template is tagged as either `@sanity` or `@regression`:

```typescript
test('should display hero heading @sanity', async ({ homePage }) => {
  /* ... */
})
test('clicking Explore Articles navigates to blogs @regression', async ({
  homePage,
}) => {
  /* ... */
})
```

This isn't just for organization — it drives the CI pipeline. Sanity tests are the critical path: page loads, core navigation, the things that must work. They run first, and if they fail, regression tests are skipped entirely. No point running 73 regression tests when the homepage doesn't load.

The current split is 28 sanity tests that run in about 8 seconds and 73 regression tests that cover edge cases, SEO, performance, accessibility, and security.

### CI Pipeline

The GitHub Actions workflow has four stages:

```
Sanity (3 browsers) → Regression (3 shards × 3 browsers) → Report (merge + GitHub Pages) → Summary
```

**Sanity** runs fast across chromium, firefox, and webkit. If any browser fails, regression is skipped entirely (`fail-fast: true`).

**Regression** shards tests across 3 workers per browser — that's 9 parallel jobs. Sharding is important because regression tests include things like performance budgets and accessibility scans that are inherently slower. Running everything sequentially on a single runner would take several minutes. With sharding, it's typically under a minute.

The sharding required adding the `blob` reporter to the Playwright config. Without it, `playwright merge-reports` has nothing to merge — a lesson I learned the hard way when CI reports kept failing to deploy:

```typescript
reporter: [
  ['html', { outputFolder: 'playwright-report', open: 'never' }],
  ['list'],
  ...(process.env.CI ? [['github'], ['blob']] : []),
],
```

**Report** merges all blob reports from the sharded runs into a single HTML report and deploys it to GitHub Pages. Every CI run produces a browsable report with traces, screenshots, and video for failures.

**Summary** writes a GitHub Step Summary with a status table and a direct link to the Pages report. It's a small thing, but it saves time when you're scanning through notifications at 7am.

The workflow triggers on PRs to master, nightly at 04:00 UTC, and manual dispatch with a configurable base URL.

There's also a separate `static-checks.yml` that runs ESLint, Prettier, and TypeScript type checking on every push. These are fast and cheap — there's no reason not to run them on every commit.

### Logging

All scripts use winston instead of `console.log`. This might seem like overkill for a test framework, but structured logging with timestamps and log levels makes debugging CI failures significantly easier. When you're staring at a wall of CI output trying to figure out what happened, having `14:23:05 [ERROR] Failed to send Slack notification: 403` is much more useful than a bare string.

The logger is configured via `LOG_LEVEL` environment variable, so you can crank it up to `debug` when investigating issues without changing code.

### Scripts: Slack and LLM Analysis

The template includes two optional scripts for CI integration:

**Slack Notifier** reads the Playwright JSON report and sends a formatted Block Kit message with test results. Without a webhook URL configured, it prints the payload to the logger — useful for testing the format before hooking it up.

**LLM Failure Analyzer** reads error context files from `test-results/` and sends them to Claude or OpenAI for root-cause analysis. It categorizes failures as test issues (bad selectors), app issues (regressions), or environment issues (timeouts). Without an API key, it falls back to local pattern matching that handles the common cases.

Both are wired into the custom reporter but disabled by default. Uncomment one line in the Playwright config to enable them:

```typescript
reporter: [
  ['./scripts/custom-reporter.ts', { slack: true, llmAnalysis: true }],
],
```

### How to Use This Template

The template is built against my blog ([kazis.dev](https://kazis.dev)) but it's designed to be adapted. The process is:

1. Update `BASE_URL` in your `.env` or `config/env.config.ts`
2. Update routes in `constants/routes.enum.ts`
3. Create page objects by extending `BasePage`
4. Register them in `fixtures/base.fixture.ts`
5. Write tests

That's it. The helpers, components, CI pipeline, reporters, and tagging strategy all carry over. You're not adopting a framework — you're forking a working setup and adjusting the page objects to match your app.

### What I Intentionally Left Out

- **Visual regression testing.** Playwright supports screenshot comparison, but it adds complexity (baseline management, flaky diffs from font rendering) that most teams don't need initially.
- **Database seeding.** This template tests against a live URL. If you need to seed data, add it to the fixtures — the pattern supports it, but the implementation is app-specific.
- **Authentication flows.** Same reasoning — the storage state pattern varies too much between apps to include a generic version.
- **Docker.** The CI runs directly on GitHub runners. If you need containerized execution, wrapping it in Docker is straightforward but adds a layer I didn't want to bake in.

These are all things you might add, but starting without them keeps the template focused on what's universal: structure, patterns, and CI.

### Final Thoughts

The best test frameworks are the boring ones. They use well-known patterns, they're easy to navigate for someone who didn't write them, and they get out of the way so you can focus on what actually matters — writing good tests.

This template is the result of building the same thing several times and finally writing it down. If it saves you a few days of setup, or if it gives you ideas for organizing your own suite, that's a win.

Check it out: [github.com/Kazaz-Or/playwright-ts-template-pom](https://github.com/Kazaz-Or/playwright-ts-template-pom)


A Playwright template I keep reaching for — POM pattern, fixtures, helpers, CI pipeline, and the reasoning behind each piece.

My Go-to Playwright Template Framework for E2E Tests


Testing visual elements is straightforward with Playwright, but how do you verify that a specific sound effect played when a user clicked a button or an in-game event occurred? Since automated browsers in CI pipelines don't have "ears," we have to get creative.

The easy answer is Monkey-patching for browser Web Audio APIs and the HTMLAudioElement to intercept audio playback and verify it in our test assertions.

The most reliable way to track audio in a browser is to override the global functions responsible for playing sound. This includes:

`HTMLAudioElement.prototype.play()`: For sounds triggered by `<audio>` tags or `new Audio().play()`.

`AudioBufferSourceNode.prototype.start()`: For sounds played using the Web Audio API, common in games and complex interactive experiences.

By overriding these methods, we can record every attempt to play a sound file into a global array on the window object, which Playwright can then inspect.

1. Creating the Audio Helper (as a fixture)
   First, let's build a clean, AudioMonitor class and wrap it in a Playwright fixture. This ensures that every test gets its own isolated instance of the monitor, preventing "state leaking" when running tests in parallel.

```typescript
// fixtures/audio-fixture.ts
import { test as base, Page } from '@playwright/test'

export class AudioMonitor {
  constructor(private page: Page) {}

  async start() {
    await this.page.addInitScript(() => {
      ;(window as any).soundsPlayed = []

      // --- 1. Patch Standard HTML5 Audio ---
      const originalHtmlAudioPlay = HTMLAudioElement.prototype.play
      HTMLAudioElement.prototype.play = function (...args) {
        const soundName =
          this.src.split('/').pop()?.split('.')[0] || 'unknown_html_audio'

        ;(window as any).soundsPlayed.push({
          name: soundName,
          src: this.src,
          type: 'HTMLAudio',
          timestamp: Date.now(),
        })

        return originalHtmlAudioPlay.apply(this, args)
      }

      // --- 2. Patch Web Audio API ---
      const originalBufferSourceStart = AudioBufferSourceNode.prototype.start
      AudioBufferSourceNode.prototype.start = function (...args) {
        const soundName =
          (this as any).audioName ||
          (this.buffer
            ? `buffer_len_${this.buffer.length}`
            : 'unknown_web_audio')

        ;(window as any).soundsPlayed.push({
          name: soundName,
          type: 'WebAudio',
          timestamp: Date.now(),
        })

        return originalBufferSourceStart.apply(this, args)
      }
    })
  }

  async getPlayedSounds(): Promise<string[]> {
    return await this.page.evaluate(() => {
      return (window as any).soundsPlayed?.map((s: any) => s.name) || []
    })
  }

  async verifyExpectedSounds(expectedSounds: string[]) {
    const playedSounds = await this.getPlayedSounds()
    const missing = expectedSounds.filter(
      expected => !playedSounds.some(played => played.includes(expected))
    )
    return { played: playedSounds, missing }
  }
}
```

In my case, I use a base fixture to extend the Playwright test fixture and include the audioMonitor fixture.

```typescript
// Extend Playwright's base test to include our audioMonitor fixture
export const test = base.extend<{ audioMonitor: AudioMonitor }>({
  audioMonitor: async ({ page }, use) => {
    const monitor = new AudioMonitor(page)
    await monitor.start()
    await use(monitor)
    // Cleanup is automatic as the window object is destroyed with the page
  },
})

export { expect } from '@playwright/test'
```

2. Now use it in your tests:

```typescript
// tests/audio-feature.spec.ts
import { test, expect } from '../fixtures/audio-fixture'

const SOUNDS = ['sound_1', 'sound_2', 'sound_3', 'sound_4']

test('should play expected sounds when audio is ON', async ({
  page,
  audioMonitor,
}) => {
  await page.goto('/somepage')

  // Trigger action that should play the expected sounds
  await page.getByTestId('somebuttonid').click()

  const { missing } = await audioMonitor.verifyExpectedSounds(SOUNDS)

  expect(missing.length, `Missing sounds: ${missing.join(', ')}`).toBe(0)
})
```

Pros of this approach:

- Fixture-Based Isolation: Unlike singletons, fixtures are local to the test worker. This is critical for parallel execution.

- Headless Friendly: This solution doesn't rely on system audio output, making it perfect for CI/CD environments (Docker, GitHub Actions) where no sound card exists.

- Zero Dependencies: It leverages native browser APIs and Playwright’s built-in addInitScript and test.extend capabilities.

- Timing & Sequence: Because we capture a timestamp for every sound, you can even assert that "Sound A" played before "Sound B."

- Traceability: Because these interactions happen in the browser context, these "sounds" will actually show up in your Playwright Console Logs if you add the console.log mentioned above, making the Playwright HTML Report much more descriptive.

Cons of this approach:

While powerful, this method captures the intent to play audio. It doesn't guarantee that the user actually heard it (e.g., if the OS volume is zero or a physical speaker is unplugged). However, for functional E2E verification, ensuring the application code correctly calls the playback APIs is the gold standard for automated testing.


How to test browser audio in Playwright by intercepting HTML5 and Web Audio API calls—ensuring reliable sound tests.

Testing Browser Audio with Playwright


If performance and SEO is a fundamental aspect of your website, you should be monitoring it. Playwright & Lighthouse integration is an excellent way to start.

This setup allows you to run performance audits as part of your regular test suite, catching performance regressions before they reach production.

### Why Combine Playwright with Lighthouse?

Lighthouse is Google's open-source tool for improving web page quality. It audits performance, accessibility, SEO, and best practices. However, running Lighthouse manually or through basic CI scripts doesn't integrate well with your existing test infrastructure. Playwright, on the other hand, is excellent for browser automation but doesn't have built-in performance auditing capabilities. By combining them, you get:

- Automated performance regression testing
- Integration with your existing Playwright test suite
- Consistent browser environments across tests
- Detailed performance metrics and reports
- CI/CD pipeline integration

### Setting Up the Integration

Let's start by installing the required dependencies. You'll need Playwright and the `playwright-lighthouse` integration library:

```bash
npm install --save-dev @playwright/test playwright playwright-lighthouse get-port
```

The `get-port` package is crucial for managing ports dynamically, ensuring tests don't conflict with each other.

### Creating the Lighthouse Test Fixture

The key to this integration is setting up a proper Playwright fixture that manages the Chrome debugging port. Here's an example setup:

```typescript
// tests/performance/lighthouse.ts
import { chromium, Browser } from 'playwright'
import { test as base } from '@playwright/test'

const getPortPromise = import('get-port')

type LighthouseFixtures = {
  port: number
  browser: Browser
}

export const lighthouseTest = base.extend<{}, LighthouseFixtures>({
  port: [
    async ({}, use) => {
      const { default: getPort } = await getPortPromise
      const port = await getPort()
      await use(port)
    },
    { scope: 'worker' },
  ],

  browser: [
    async ({ port }, use) => {
      const browser = await chromium.launch({
        args: [`--remote-debugging-port=${port}`],
      })
      await use(browser)
    },
    { scope: 'worker' },
  ],
})

export const test = lighthouseTest
```

**What's happening here?**

1. **Dynamic Port Allocation**: `get-port` ensures each test worker gets a unique debugging port, preventing conflicts in parallel execution
2. **Worker Scope**: Both fixtures use `worker` scope, meaning they're shared across tests in the same worker process
3. **Chrome Remote Debugging**: The browser launches with `--remote-debugging-port`, which Lighthouse needs to connect and run audits

### Now for the actual tests measurement

Now let's create actual performance tests. The beauty of this approach is that you can test multiple pages with different performance thresholds:

```typescript
// tests/performance/lighthouse.spec.ts
import { test } from './lighthouse'

const thresholds = {
  accessibility: 90,
  'best-practices': 90,
  seo: 90,
}

const urlsToTest = [
  { name: 'Homepage', uri: '/' },
  { name: 'About Page', uri: '/about' },
  { name: 'Blogs Page', uri: '/blogs' },
]

test.describe('Lighthouse Audits', () => {
  for (const pageInfo of urlsToTest) {
    test(`Check Lighthouse scores for ${pageInfo.name}`, async ({
      page,
      port,
    }) => {
      await page.goto(`http://someurl.com`)
      const { playAudit } = await import('playwright-lighthouse')
      await playAudit({
        page,
        port,
        thresholds,
      })
    })
  }
})
```

Few things to note here - You do have a clear method for flexible thresholds, then you can set different performance standards for different pages, which can be crucial for dynamic websites which various different pages and content.
Also, in this way you can easily add new pages.

When you run these tests, Lighthouse evaluates several key areas which you should be familiar with:

### Performance Metrics

- **First Contentful Paint (FCP)**: When the first text/image appears
- **Largest Contentful Paint (LCP)**: When the main content is likely loaded
- **Speed Index**: How quickly content is visually displayed
- **Cumulative Layout Shift (CLS)**: Visual stability measure

### Other Audits

- **Accessibility**: Screen reader compatibility, color contrast, ARIA labels
- **Best Practices**: HTTPS usage, console errors, deprecated APIs
- **SEO**: Meta tags, structured data, "crawlability"

### Advanced Configuration Options

You can customize the Lighthouse configuration for more specific testing needs:

```typescript
const advancedThresholds = {
  performance: 85,
  accessibility: 95,
  'best-practices': 90,
  seo: 90,
  pwa: 80,
}

const lighthouseConfig = {
  extends: 'lighthouse:default',
  settings: {
    onlyCategories: ['performance', 'accessibility', 'best-practices', 'seo'],
    skipAudits: ['uses-http2'], // Skip specific audits if needed
  },
}

// In your test
await playAudit({
  page,
  port,
  thresholds: advancedThresholds,
  config: lighthouseConfig,
  reports: {
    formats: {
      html: true,
      json: true,
    },
    name: `lighthouse-report-${pageInfo.name}`,
    directory: './lighthouse-reports',
  },
})
```

### Integration with Playwright Config

Your `playwright.config.ts` should include a dedicated performance testing project:

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

export default defineConfig({
  testDir: './tests',
  projects: [
    // ... other projects
    {
      name: 'Performance',
      fullyParallel: true,
      testDir: './tests/performance',
      use: {
        headless: true, // Performance tests should run headless
      },
    },
  ],
})
```

### Running the Tests

Execute your performance tests with a dedicated npm script:

```json
{
  "scripts": {
    "test:performance": "npx playwright test --project=Performance"
  }
}
```

Before running the tests, make sure your development server is running:

```bash
# Terminal 1: Start your app
npm run dev

# Terminal 2: Run performance tests
npm run test:performance
```

### CI/CD Integration

For continuous integration, you'll want to build and serve your application statically. Here we're using a simple GitHub Actions workflow to run the tests.

```yaml
# .github/workflows/performance.yml
name: Performance Tests

on: [push, pull_request]

jobs:
  performance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Start server and run tests
        run: |
          npm start &
          npx wait-on http://localhost:3000
          npm run test:performance
```

### Best Practices and Tips

#### 1. Set Realistic Thresholds

Don't start with perfect scores (100/100). Begin with current performance levels and gradually improve:

```typescript
const realisticThresholds = {
  performance: 70, // Start here, aim for 90+
  accessibility: 85, // Should be high from the start
  'best-practices': 80,
  seo: 75,
}
```

#### 2. Test Multiple Device Types

Lighthouse can simulate different devices:

```typescript
await playAudit({
  page,
  port,
  thresholds,
  config: {
    extends: 'lighthouse:default',
    settings: {
      emulatedFormFactor: 'mobile',
      throttling: {
        rttMs: 150,
        throughputKbps: 1600,
        cpuSlowdownMultiplier: 4,
      },
    },
  },
})
```

#### 3. Handle Dynamic Content

For pages with dynamic content, ensure they're fully loaded before auditing:

```typescript
test('Performance test with dynamic content', async ({ page, port }) => {
  await page.goto('http://localhost:3000/dashboard')

  // Wait for dynamic content to load
  await page.waitForSelector('[data-testid="dashboard-content"]')
  await page.waitForLoadState('networkidle')

  const { playAudit } = await import('playwright-lighthouse')
  await playAudit({ page, port, thresholds })
})
```

#### 4. Monitor Performance Over Time

Store results and track performance trends:

```typescript
const results = await playAudit({
  page,
  port,
  thresholds: {}, // Don't fail on thresholds, just collect data
  reports: {
    formats: { json: true },
    directory: './performance-history',
  },
})

// Store results in your preferred monitoring system
await storePerformanceMetrics(results, pageInfo.name)
```

### Troubleshooting Common Issues

#### Port Conflicts

If you encounter port conflicts, ensure you're using `get-port` correctly and that tests aren't running in shared browser contexts.

#### Timeout Errors

Increase Playwright's timeout for performance tests:

```typescript
test.setTimeout(60000) // 60 seconds for performance tests
```

#### Inconsistent Results

Performance can vary between runs. Consider:

- Running tests multiple times and averaging results
- Using consistent hardware in CI
- Disabling CPU throttling for development testing

---

That's it. Would love to hear your thoughts and feedback.


Integrate Lighthouse performance audits into your Playwright test suite for automated performance monitoring and regression testing.

Measure Website Performance with Playwright & Lighthouse


## The Problem with Flaky Tests

We've all been there - you have a test suite that works perfectly in isolation, but occasionally fails due to external factors beyond your control (like a third-party service being down). Maybe it's a network hiccup, a temporary service unavailability, or leftover test data from previous runs. While Playwright offers built-in retry mechanisms, sometimes you need more control over what happens between retry attempts.

In this post, I'll show you how to leverage Playwright's retry system with custom fixtures to perform cleanup operations between retries, ensuring each retry attempt starts with a clean slate.

## Understanding Playwright's Built-in Retry Mechanism

Playwright provides a simple retry configuration that you can set in your `playwright.config.ts`:

```typescript
// playwright.config.ts
export default defineConfig({
  // Retry failed tests up to 2 times
  retries: process.env.CI ? 2 : 0,

  // Or configure per project
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
      retries: 2,
    },
  ],
})
```

While this works great for simple flaky tests, it doesn't help when your test failures are caused by leftover data or state from previous attempts. This is where custom retry handling becomes invaluable.

## The Solution: Custom Retry Fixture

The key insight is to create a custom fixture that can detect when a test is being retried and perform necessary cleanup operations. Here's how I implemented this pattern in one of my projects:

### Step 1: Create a RetryHandler Class

First, let's create a `RetryHandler` class that manages the cleanup logic.
In this example, we are cleaning up test data that could be stored in various systems like MongoDB, Redis, files, or other external services.

```typescript
// utils/retry-handler.ts
import { logger } from '@moonactive/admin-common-logger'
import { Fixtures } from 'fixture/base.fixture'
import { TestInfo } from 'playwright-decorators'

export class RetryHandler {
  async retryHandler(
    testInfo: TestInfo,
    context: Fixtures, // Where you pass other fixtures you want to clean up
    testData: any[] // Where you pass the test data you want to clean up
  ): Promise<void> {
    // Only perform cleanup if this is a retry attempt (retry > 0)
    if (testInfo.retry > 0) {
      await RetryHandler.retryCleaner(context, testData)
    }
  }

  static async retryCleaner(
    context: Partial<Fixtures>,
    testData: any[]
  ): Promise<void> {
    try {
      const { mongo, redis } = context
      const dataIds = testData.map(
        item => item.id || item._id || item.identifier
      )

      const contextDetails = {
        mongo: !!mongo,
        redis: !!redis,
      }

      logger.info(
        `Triggering retry cleanup for data: ${dataIds}, context: ${JSON.stringify(
          contextDetails
        )}`
      )

      // Clean up database records if MongoDB is used
      if (mongo) {
        await mongo.deleteTestDataFromDB(testData)
      }

      // Clean up Redis records if Redis is used
      if (redis) {
        await redis.deleteTestDataFromRedis(testData)
      }

      if (!mongo && !redis) {
        logger.error('Missing context for retryCleaner')
        throw new Error('Missing context for retryCleaner')
      }
    } catch (err) {
      logger.error(`Failed to clean up after retry: ${err}`)
      throw err
    }
  }
}
```

### Step 2: Integrate with Playwright Fixtures

Next, integrate the RetryHandler into your Playwright fixture system:

```typescript
// fixture/base.fixture.ts
import { RetryHandler } from '../utils/retry-handler'
// ... other imports

export type Fixtures = {
  logger: Types.SomeLogger
  app: App
  expect: typeof expect
  mongo: DatabaseHelper
  redis: RedisHelper
  bq: BQHelper
  api: APIHelper
  sqs: SqsHelper
  retry: RetryHandler // Our custom retry handler
}

export const test = base.extend<Fixtures>({
  // ... other fixtures

  retry: async ({}, use) => {
    const retryHandler = new RetryHandler()
    await use(retryHandler)
  },

  // ... other fixture implementations
})
```

### Step 3: Use the Retry Handler in Tests

Now you can use the retry handler in your tests:

```typescript
// tests/example.spec.ts

test('Create and validate test data', async ({
  app,
  api,
  mongo,
  redis,
  retry,
}, testInfo) => {
  // Define test data that might need cleanup
  const testData = [
    { id: 'test-item-1', name: 'Test Item 1', type: 'example' },
    { id: 'test-item-2', name: 'Test Item 2', type: 'example' },
  ]

  // Call retry handler at the beginning of the test
  // This will clean up any leftover data if this is a retry attempt
  await retry.retryHandler(testInfo, { mongo, redis }, testData)

  // Your actual test logic
  await app.createTestItems(testData)

  // Validate the created items
  await api.validateTestItems(testData)

  // Perform additional test actions
  await app.performActionsOnItems(testData)
})
```

## How Does It Work?

The magic happens in the `testInfo.retry` property. Playwright automatically increments this value for each retry attempt:

- **First attempt**: `testInfo.retry = 0` (no cleanup performed)
- **First retry**: `testInfo.retry = 1` (cleanup is performed)
- **Second retry**: `testInfo.retry = 2` (cleanup is performed again)

This ensures that cleanup only happens when needed, avoiding unnecessary operations on the first test run.

## Key Benefits

### 1. **Intelligent Cleanup**

Only performs cleanup operations when actually retrying, not on the initial test run.

### 2. **Flexible Context**

You can pass different fixtures and resources based on what your specific test needs to clean up.

### 3. **Comprehensive Coverage**

The example shows cleanup across multiple systems (database, GitHub, configuration), but you can adapt it to your needs.

### 4. **Proper Error Handling**

Includes logging and error handling to help debug cleanup issues.

### 5. **Type Safety**

Leverages TypeScript for better IDE support and catch errors at compile time.

## Advanced Usage Patterns

### Multi-Service Cleanup

You can extend this pattern to handle different types of cleanup based on the test context:

```typescript
await retry.retryHandler(
  testInfo,
  {
    mongo,
    redis,
    elasticsearch,
    fileSystem,
    api,
  },
  testData
)
```

### Conditional Cleanup

Add logic to perform different cleanup based on test metadata:

```typescript
async retryHandler(
  testInfo: TestInfo,
  context: Fixtures,
  data: any[],
  options?: { skipRedis?: boolean; skipDB?: boolean; skipFiles?: boolean }
): Promise<void> {
  if (testInfo.retry > 0) {
    await RetryHandler.retryCleaner(context, data, options)
  }
}
```

### Custom Retry Limits

You can even implement custom retry logic based on specific conditions:

```typescript
async retryHandler(
  testInfo: TestInfo,
  context: Fixtures,
  data: any[],
  maxRetries: number = 2
): Promise<void> {
  if (testInfo.retry > 0 && testInfo.retry <= maxRetries) {
    await RetryHandler.retryCleaner(context, data)
  } else if (testInfo.retry > maxRetries) {
    logger.warn(`Exceeded max retries (${maxRetries}), skipping cleanup`)
  }
}
```

## Best Practices

1. **Call Early**: Always call the retry handler at the very beginning of your test, before any test actions.

2. **Be Specific**: Only clean up the specific data your test creates to avoid affecting other tests.

3. **Log Everything**: Include comprehensive logging to help debug retry scenarios.

4. **Handle Failures**: Make sure cleanup failures don't prevent the retry from proceeding.

5. **Test Your Cleanup**: Consider writing separate tests to verify your cleanup logic works correctly.

## Conclusion

This pattern transforms Playwright's basic retry mechanism into a powerful tool for handling complex test scenarios. By combining custom fixtures with intelligent cleanup logic, you can ensure that flaky tests get a truly fresh start on each retry attempt.

The approach is particularly valuable for integration tests that interact with external services, databases, or file systems where leftover state can cause cascading failures.

Have you implemented similar retry patterns in your test suites? I'd love to hear about your experiences and any creative solutions you've developed!


Do you have a flaky test that is out of your control? Do you have some functionality you need to apply between retries? This is the tip for you.

Playwright Tips: Leverage Playwright's Retry Mechanism as a Custom Fixture


So a little bit context first - As our test suites grow in complexity and execution parallelism, pinpointing the origin of specific network requests and responses becomes increasingly crucial dude to some random flakiness.

In our Playwright automation framework, we recently encountered a scenario where we needed to intercept a response from a particular worker instance in our parallel test execution. This led us to devise a solution leveraging Playwright's request interception capabilities and custom headers.

When running Playwright tests in parallel using multiple workers, identifying which worker initiated a specific network request can be challenging. This is especially true when dealing with APIs that might behave slightly differently based on the context of the worker or the test being executed.
In our case, we needed to verify the response of a specific API call triggered by an action within a particular test running on a specific worker. Using the builtin `page.waitForResponse()` with a URL matcher wasn't sufficient because multiple workers could potentially trigger the same API call around the same time. We needed a more precise way to target the response we were interested in.

Therefore, our approach was to inject a custom header into the outgoing request from a specific worker instance. This unique header would then allow us to identify the corresponding response. Playwright's `page.route()` API provides a powerful mechanism to intercept and modify requests before they are sent.

Here's an example of how we implemented this solution:

```typescript
import { Page, Response } from '@playwright/test'

async function waitForResponseOfSpecificWorkerInstance(
  page: Page,
  partialRoute: string,
  uniqueIdentifier: string,
  timeout = 21000
): Promise<Response> {
  const regexRoute = new RegExp(partialRoute)

  await page.route('**/*', route => {
    const url = route.request().url()
    const urlObj = new URL(url)
    const pathname = urlObj.pathname

    if (regexRoute.test(pathname)) {
      const newHeaders = { ...route.request().headers() }
      newHeaders['X-Unique-Identifier'] = uniqueIdentifier
      route.continue({ headers: newHeaders })
    } else {
      route.continue()
    }
  })

  const response = await page.waitForResponse(
    response => {
      const requestHeaders = response.request().headers()
      return (
        regexRoute.test(response.url()) &&
        requestHeaders['x-unique-identifier'] === uniqueIdentifier
      )
    },
    { timeout }
  )
  return response
}
```

Let's break down what this simple function does:

```typescript
waitForResponseOfSpecificWorkerInstance(page, partialRoute, uniqueIdentifier, timeout):
```

- Takes the Playwright Page object, a partialRoute (a string or regular expression to match the URL), a uniqueIdentifier (a string to identify the worker instance), and an optional timeout as arguments.
- Returns a Promise that resolves with the intercepted Response object.

```typescript
const regexRoute = new RegExp(partialRoute)
```

Creates a regex from the partialRoute variable to allow for flexible URL matching.

```typescript
await page.route('**/*', route => { ... });
```

This is the heart of the request interception. `page.route('**/*')` intercepts all network requests made by the page.
The provided callback function is executed for each intercepted request.

```typescript
const url = route.request().url()
const pathname = new URL(url).pathname

if (regexRoute.test(pathname)) { ... }
```

Extracts the URL and then specifically the pathname from the intercepted request. We often focus on the pathname for route matching.
Then we check if the pathname of the current request matches the provided partialRoute.

```typescript
const newHeaders = { ...route.request().headers() }

newHeaders['X-Unique-Identifier'] = uniqueIdentifier
```

Creates a copy of the existing request headers. It's important to copy the headers to avoid modifying the original object directly. Then we inject our custom header. We add a new header named `X-Unique-Identifier` with the value of the uniqueIdentifier variable that was passed to the function as an argument.

```typescript
route.continue({ headers: newHeaders })
else { route.continue() }

```

Allows the intercepted request to continue to the server, but now with our newly added custom header.
If the request URL doesn't match our target partialRoute, we simply allow the request to continue without modification.

```typescript
const response = await page.waitForResponse(response => { ... }, { timeout })

```

This is where we wait for the specific response we are interested in. The callback function within `waitForResponse` checks two conditions:

- `regexRoute.test(response.url())` Ensures the response URL matches our target route.
  `requestHeaders['x-unique-identifier'] === uniqueIdentifier` Checks if the request that led to this response had our custom X-Unique-Identifier header with the expected value.

And finally, once a matching response is found (both URL and custom header match), the promise resolves with the Response object and returns it.

Now, lets take a look at how we can use this function in a test:

```typescript
import { test, expect } from '@playwright/test'
import { waitForResponseOfSpecificWorkerInstance } from './utils' // Assuming the function is in a utils.ts file

test('Edit refresh lock', async ({ app, api }, testInfo) => {
  // Assuming 'app' and 'api' is a fixture object containing your page objects and api helper function like waitForResponseOfSpecificWorkerInstance

  const responsePromise = api.waitForResponseOfSpecificWorkerInstance(
    app.myPage,
    '/api/v1/example/',
    `worker_${testInfo.workerIndex}`
  )

  // Perform some action that will trigger the API call

  const response = await responsePromise
  expect(response.status()).toBe(200)
})
```

In this example:

- We use `testInfo.workerIndex` (testInfo is a built-in fixture of Playwright) to get a unique identifier for the current worker running the test. This ensures that each parallel test execution will have a distinct X-Unique-Identifier header.
- We call our `waitForResponseOfSpecificWorkerInstance` function before performing the action that triggers the API call.
- We pass the page object, the partial route of the API endpoint we're interested in (/api/v1/example/), and the unique worker identifier as a string.
- The test then proceeds to perform the action on the browser.
- We await the `responsePromise`, which will resolve only when a response from the /api/v1/example/ endpoint is received and its corresponding request had the X-Unique-Identifier header matching the current worker's index.

By doing that simple trick, we can now precisely target and handle responses from specific worker instances in our parallel test execution, reduce flakiness (even in parallel execution) and enhanced debugging abilities.


Target specific API responses with Playwright parallel execution using custom headers for reliable automation.

Playwright Articles

All Playwright Articles

My Go-to Playwright Template Framework for E2E Tests

Testing Browser Audio with Playwright

Measure Website Performance with Playwright & Lighthouse

Playwright Tips: Leverage Playwright's Retry Mechanism as a Custom Fixture

Playwright Tips: Using Custom Headers in Playwright for Worker-Specific Response Handling