Building a Production-Grade Playwright Framework from Scratch

Most end-to-end test automation suites fail not because the underlying tools are weak, but because they are built like ad-hoc scripts instead of maintainable software systems. In this guide, we break down the exact production-grade Playwright framework architecture we deploy for enterprise clients.

1. Why Playwright Won the Automation Wars

For years, Selenium was the undisputed standard for browser automation, despite notorious struggles with driver synchronization, sluggish test speeds, and fragile element waits. Cypress improved developer ergonomics, but suffered from iframe limitations, lack of true multi-tab support, and isolated browser process constraints.

Microsoft's Playwright changed the landscape by leveraging direct CDP (Chrome DevTools Protocol) and bi-directional browser websocket connections. Key architectural advantages include:

Automatic Waiting: Playwright checks for element visibility, stability, and enabled states before performing actions—eliminating 90% of explicit sleep delays.
Isolated Browser Contexts: Creating a new BrowserContext takes milliseconds, delivering clean cookies, storage, and cache isolation without launching fresh browser instances.
Native Multi-Tab & Network Interception: Out-of-the-box support for OAuth redirects, PDF downloads, and request mocking.

2. Production Repository Architecture

Treat test code with the same architectural rigor as your production backend. Here is the structure we standardize on:

Enterprise Directory Layout Structure

playwright-framework/
├── .github/workflows/e2e.yml       # CI/CD pipeline with matrix sharding
├── config/
│   ├── env.dev.ts                  # Target environment URLs & credentials
│   └── playwright.config.ts        # Global timeouts, workers, reporters
├── src/
│   ├── fixtures/
│   │   └── base-test.ts            # Extended Playwright test with auto-injected POMs
│   ├── pages/                      # Page Object Models (POM)
│   │   ├── base.page.ts            # Shared base class (navigation, toast alerts)
│   │   ├── login.page.ts           # Login page actions & locators
│   │   └── checkout.page.ts        # Payment workflows
│   ├── utils/                      # Database seeders, API helpers, token generators
│   └── tests/                      # Feature-based spec files
│       ├── auth/login.spec.ts
│       └── billing/checkout.spec.ts
└── package.json

3. Dependency Injection via Custom Fixtures

The biggest anti-pattern in Playwright tests is repeatedly instantiating page objects inside test cases (const loginPage = new LoginPage(page)). Playwright provides a powerful dependency injection mechanism called Fixtures:

src/fixtures/base-test.ts TypeScript

import { test as base } from '@playwright/test';
import { LoginPage } from '../pages/login.page';
import { CheckoutPage } from '../pages/checkout.page';

// Declare fixture types for TypeScript autocomplete
type Pages = {
  loginPage: LoginPage;
  checkoutPage: CheckoutPage;
  authenticatedUser: void;
};

export const test = base.extend<Pages>({
  loginPage: async ({ page }, use) => {
    await use(new LoginPage(page));
  },

  checkoutPage: async ({ page }, use) => {
    await use(new CheckoutPage(page));
  },

  // Auto-authenticating fixture using storageState
  authenticatedUser: async ({ page }, use) => {
    await page.goto('/auth/session-seed');
    // Pre-populate session JWT in cookies/localStorage
    await page.context().addCookies([
      { name: 'session_token', value: 'enterprise-test-jwt', domain: 'localhost', path: '/' }
    ]);
    await use();
  },
});

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

Notice how clean and expressive the resulting spec becomes:

src/tests/billing/checkout.spec.ts TypeScript

import { test, expect } from '../../fixtures/base-test';

test.describe('Enterprise Checkout Flow', () => {
  test('processes multi-currency transactions without errors', async ({
    checkoutPage,
    authenticatedUser,
  }) => {
    await checkoutPage.navigate();
    await checkoutPage.selectCurrency('EUR');
    await checkoutPage.confirmPayment();

    await expect(checkoutPage.successBadge).toBeVisible();
    await expect(checkoutPage.orderConfirmationNumber).toMatch(/ORD-[0-9]{6}/);
  });
});

4. Parallel Execution & CI/CD Sharding

When an enterprise test suite grows beyond 500 tests, running sequentially in CI is unacceptably slow. Playwright supports native test sharding across multiple GitHub Actions runner nodes with zero additional tooling:

.github/workflows/e2e.yml YAML

name: Playwright Regression Matrix
on: [push, pull_request]

jobs:
  e2e-tests:
    timeout-minutes: 20
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shardIndex: [1, 2, 3, 4]
        shardTotal: [4]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps chromium

      - name: Run Sharded Playwright Suite
        run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}

      - name: Upload Blob Artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: blob-report-${{ matrix.shardIndex }}
          path: blob-report
          retention-days: 1

By splitting our 2,000+ test case suites across 4 parallel runners, total pipeline run times dropped from 48 minutes to under 8 minutes, unblocking rapid production deployments.

5. The Zero-Tolerance Flakiness Protocol

Best Practices for Deterministic Tests

Never use arbitrary timeouts (page.waitForTimeout): Rely strictly on locator assertions that await state conditions (toBeVisible(), toHaveText()).
Seed clean test data via API: Do not navigate through 10 registration forms to create a test user. Use an API helper before the test runs to mint credentials directly.
Trace viewer for post-mortem analysis: Configure trace: 'retain-on-failure' in your Playwright config to inspect DOM snapshots, console logs, and network traffic when tests fail.

Priya Rajendran

Lead QA Automation Architect

Priya leads automated quality assurance and test infrastructure at Arvaan Core Logic. She has architected end-to-end testing frameworks for multi-million dollar SaaS and fintech platforms.