Playwright Fundamentals

1 The Hook

A mid-level SDET joins a Wellington startup that uses Playwright but has no central config. Each developer set it up differently. Some use TypeScript, some plain JavaScript. Some have baseURL set; others hardcode URLs throughout the test files. The CI pipeline runs a different browser to local dev.

When the SDET sets up a standard playwright.config.ts, three previously “intermittent” failures become permanent. They were only passing because of browser-specific timing quirks in one developer’s local setup. The tests were never actually reliable — they were just lucky.

The config is the foundation. Get it wrong and everything built on it is unstable. A flaky test is usually a symptom. An inconsistent config is usually the disease.

2 The Rule

3 The Analogy

4 Watch Me Do It

Here is a production-grade playwright.config.ts. Every setting is deliberate.

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,  // Don't commit test.only
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined,
  reporter: process.env.CI
    ? [['html'], ['github']]
    : [['html', { open: 'on-failure' }]],

  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    actionTimeout: 10_000,
    navigationTimeout: 30_000,
  },

  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
});

Now the fixture pattern. Fixtures are composable, lazily initialised, and automatically torn down. They are strictly better than beforeEach for shared setup.

// fixtures.ts
import { test as base, expect } from '@playwright/test';
import { LoginPage } from './pages/LoginPage';

type Fixtures = {
  loginPage: LoginPage;
  authenticatedPage: void;
};

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

  authenticatedPage: async ({ page }, use) => {
    // Log in once, reuse auth state
    await page.goto('/login');
    await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
    await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
    await page.getByRole('button', { name: 'Log in' }).click();
    await page.waitForURL('**/dashboard');
    await use();
  },
});

export { expect };

Tests import from fixtures.ts instead of @playwright/test directly. The fixture is only initialised when a test declares it as a parameter — unused fixtures cost nothing.

Auto-waiting is baked into every Playwright action. When you call page.getByRole('button').click(), Playwright waits for the element to be visible, stable, enabled, and not obscured before clicking. You do not write waitForSelector or sleep. If a test is fragile because of timing, the root cause is almost always a missing assertion before an action, not a missing sleep.

5 When to Use It

• Every new Playwright project — config before the first test.
• Retrofitting to existing projects that have inconsistent setup.
• When onboarding a new team member: the config is the first document they read.
• Before starting any cross-browser work — the projects array is how you add browsers, not command-line flags.

6 Common Mistakes

7 Now You Try

8 Self-Check

Click each question to reveal the answer.

9 ISTQB Mapping

10 Next Steps