Playwright Complete Guide for QA Engineers: The Ultimate Playwright Testing Tutorial (2026)

If you're a QA engineer looking to modernize your test automation stack, Playwright is the tool you've been waiting for. Developed by Microsoft and open-sourced in 2020, Playwright is a Node.js library that enables fast, reliable, and cross-browser end-to-end testing for modern web applications.

This Playwright testing tutorial takes you from zero knowledge to a production-ready test suite — whether you're migrating from Selenium, leaving Cypress for something more powerful, or building your automation framework from scratch.

Playwright is a full browser automation framework — not just a test runner. It supports Chromium (Chrome, Edge), Firefox, and WebKit (Safari) from a single unified API. Unlike older tools, it was built for the modern web: SPAs, JavaScript-heavy frontends, shadow DOM, iframes, service workers, and complex auth flows.

Key takeaway: Playwright gives QA engineers precise control over browsers, network traffic, device emulation, storage state, and more — all from one consistent API.

• Auto-waiting — eliminates flaky timing issues; no more sleep() calls.
• Cross-browser with a single API — Chromium, Firefox and WebKit without browser-specific workarounds.
• Network interception & mocking — full control over requests, something Selenium can't do natively.
• Multiple contexts & tabs — multi-user and multi-tab journeys in one test.
• First-class TypeScript support — types ship out of the box.
• Trace Viewer — timeline debugging with DOM snapshots, network logs and screenshots.
• Speed — talks directly to browsers via CDP / Firefox / WebKit protocols, bypassing slow WebDriver.

Playwright talks to browsers over WebSocket connections using native debugging protocols. This gives low-latency command execution, event-driven listeners (page, network, console), and both headed and headless modes.

Your Test Code
     │
     ▼
Playwright Node.js API
     │
     ▼
Browser Channels (CDP / Firefox / WebKit)
     │
     ▼
Real Browser Instances

A BrowserContext is Playwright's equivalent of an incognito profile — fully isolated cookies, localStorage and session state. This is how Playwright enables parallel testing without state bleeding.

Prerequisites: Node.js 18+ and npm/yarn/pnpm. New to setup? Follow our step-by-step Playwright installation guide for beginners for Windows, Mac and Linux walkthroughs and common-error fixes.

mkdir playwright-qa-project
cd playwright-qa-project
npm init -y
npm init playwright@latest

The interactive CLI asks you to pick TypeScript or JavaScript, the test folder, GitHub Actions workflow, and whether to install browsers. After setup you'll have:

playwright-qa-project/
├── tests/
│   └── example.spec.ts
├── playwright.config.ts
├── package.json
└── .gitignore

A typical playwright.config.ts sets fullyParallel: true, retries on CI, an HTML reporter, a baseURL, trace: 'on-first-retry', screenshots and video on failure, and projects for Chromium, Firefox, WebKit and mobile devices.

Run tests with npx playwright test or open the interactive runner with npx playwright test --ui.

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

test.describe('Homepage Tests', () => {
  test('should display the correct page title', async ({ page }) => {
    await page.goto('/');
    await expect(page).toHaveTitle(/Welcome/);
  });

  test('should navigate to the About page', async ({ page }) => {
    await page.goto('/');
    await page.getByRole('link', { name: 'About' }).click();
    await expect(page).toHaveURL('/about');
  });
});

test.describe groups tests, test defines a single case, the destructured page fixture is your interface to the browser tab, and expect() wraps web-first assertions.

Use locators in this priority order: role → label → placeholder → text → test ID → CSS/XPath.

// Role-based (recommended)
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByRole('checkbox', { name: 'Remember me' }).check();

// Label-based
await page.getByLabel('Email address').fill('user@example.com');

// Placeholder / text
await page.getByPlaceholder('Search products...').fill('laptop');
await page.getByText('Welcome back!', { exact: true });

// Test ID — stable, intentional
await page.getByTestId('login-submit-btn').click();

// CSS / XPath — last resort
await page.locator('.submit-button').click();

Chain locators to scope a search: page.locator('[data-testid="user-card"]').getByRole('button', { name: 'Edit' }).

// Clicks
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByText('Item').dblclick();
await page.getByText('File').click({ button: 'right' });

// Forms
await page.getByLabel('Username').fill('john_doe');
await page.getByLabel('Country').selectOption('US');
await page.getByLabel('Accept terms').check();
await page.getByLabel('Upload document').setInputFiles('./sample.pdf');

// Keyboard
await page.keyboard.press('Enter');
await page.keyboard.press('Control+A');

// Navigation
await page.goto('/dashboard');
await page.goBack();
await page.waitForURL('/success');

Prefer explicit waits like waitForURL, waitForResponse or web-first assertions over waitForTimeout.

Playwright ships web-first assertions that auto-retry until the condition is met or timeout expires.

await expect(page).toHaveURL('/dashboard');
await expect(page).toHaveTitle(/Dashboard/);

await expect(page.getByText('Welcome!')).toBeVisible();
await expect(page.getByTestId('spinner')).toBeHidden();
await expect(page.getByRole('heading')).toHaveText('Dashboard');
await expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled();
await expect(page.getByLabel('Remember me')).toBeChecked();
await expect(page.getByLabel('Email')).toHaveValue('user@example.com');
await expect(page.locator('.product-card')).toHaveCount(12);

Soft assertions (expect.soft) collect failures without halting the test — great for asserting many dashboard widgets at once.

Configure desktop and mobile projects in playwright.config.ts:

projects: [
  { name: 'chrome',         use: { ...devices['Desktop Chrome'] } },
  { name: 'firefox',        use: { ...devices['Desktop Firefox'] } },
  { name: 'safari',         use: { ...devices['Desktop Safari'] } },
  { name: 'mobile-android', use: { ...devices['Pixel 7'] } },
  { name: 'mobile-ios',     use: { ...devices['iPhone 14'] } },
]

Run a specific project: npx playwright test --project=firefox.

Fixtures provide dependency injection and shared setup/teardown. Built-in fixtures include page, context, browser and request. Define custom fixtures by extending base:

export const test = base.extend<MyFixtures>({
  loggedInPage: async ({ page }, use) => {
    await page.goto('/login');
    await page.getByLabel('Email').fill('user@example.com');
    await page.getByLabel('Password').fill('password123');
    await page.getByRole('button', { name: 'Login' }).click();
    await page.waitForURL('/dashboard');
    await use(page);
  },
});

Use beforeAll / afterAll for expensive once-per-file setup, and beforeEach / afterEach for per-test state.

POM is the gold-standard pattern for maintainable test automation — encapsulate selectors and actions in reusable classes.

// pages/LoginPage.ts
export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('Email');
    this.passwordInput = page.getByLabel('Password');
    this.submitButton = page.getByRole('button', { name: 'Login' });
  }

  async navigate() { await this.page.goto('/login'); }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }
}

Recommended folder structure: tests/, pages/, fixtures/, test-data/, and playwright.config.ts at the root.

Playwright's built-in request fixture handles API testing directly.

test('GET /api/users returns 200', async ({ request }) => {
  const response = await request.get('https://api.example.com/users');
  expect(response.status()).toBe(200);
  const body = await response.json();
  expect(body.users.length).toBeGreaterThan(0);
});

A powerful pattern: use the API to set up state, then verify via the UI — fast and reliable. You can also mock network calls with page.route() to test error states and loading spinners deterministically.

See our API testing interview guide for deeper coverage.

// Visual regression
await expect(page).toHaveScreenshot('homepage.png');
await expect(card).toHaveScreenshot('product-card.png', { maxDiffPixelRatio: 0.01 });

Update baselines after intentional UI changes with npx playwright test --update-snapshots.

Strategy 1 — Save and reuse storage state. Log in once in an auth.setup.ts project, call page.context().storageState({ path: 'auth/user.json' }), then point dependent projects at that file via use: { storageState: 'auth/user.json' } with dependencies: ['setup'].

Strategy 2 — API-based login (fastest). Hit your /api/auth/login endpoint, then inject the token into localStorage with page.addInitScript before any page loads — skipping the UI entirely.

Playwright runs tests in parallel by default. Tune fullyParallel and workers in the config. Use test.describe.configure({ mode: 'serial' }) to force sequential execution where needed.

A minimal GitHub Actions workflow:

- uses: actions/setup-node@v4
  with: { node-version: 20 }
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
- uses: actions/upload-artifact@v4
  if: always()
  with: { name: playwright-report, path: playwright-report/ }

For large suites, shard across machines: npx playwright test --shard=1/4 through 4/4 in a matrix job.

• npx playwright test --debug — interactive Inspector to step through actions.
• npx playwright test --ui — visual runner with timeline and live preview.
• npx playwright test --headed --slow-mo=500 — watch tests run slowly.
• npx playwright show-trace trace.zip — Trace Viewer with DOM snapshots, network and console.
• await page.pause() — pause execution mid-test in headed mode.

Do:

• Use role-based locators — resilient to CSS changes.
• Add data-testid attributes for complex cases.
• Use npx playwright codegen to scaffold tests fast.
• Keep tests independent — never rely on execution order.
• Store secrets in environment variables.
• Set sensible global and per-test timeouts.

Don't:

• Use page.waitForTimeout() — brittle and slow.
• Mix selectors with test logic — keep them in Page Objects.
• Ignore HTML reports — npx playwright show-report after every CI run.

For AI-assisted scripting, see our GitHub Copilot for QA guide.

Verdict: Playwright wins for enterprise QA teams that need cross-browser coverage, multi-language support and first-class TypeScript. Cypress remains strong for Chrome-only frontend teams. Selenium makes sense only for shops with massive existing Selenium investments.

You now have a complete playbook: installation, locators, interactions, assertions, fixtures, POM, API testing, visual testing, authentication, CI/CD and debugging. Playwright is not just a testing tool — it's a complete browser-automation platform built for the demands of modern web apps.

Ready to practice automation reasoning before your next interview? Try our AI Mock Interview or browse Playwright interview questions.