Playwright: the beginner's guide to web test automation

What is Playwright?

Playwright is an open source test framework, developed by Microsoft and released under the Apache 2.0 licence, that drives Chromium, Firefox and WebKit browsers to automate end-to-end tests on Windows, Linux and macOS (source: microsoft/playwright GitHub repository, accessed 29 September 2026). It is used with TypeScript/JavaScript, Python, Java and .NET. Its test runner, Playwright Test, provides everything you need to write, run and debug a suite: assertions, parallelisation, reports and traces.

What Playwright can do

• Test on three browser engines with a single codebase: Chromium (Chrome, Edge), Firefox and WebKit (the Safari engine), headed or headless, locally or in CI, with mobile emulation for Chrome Android and Mobile Safari (source: playwright.dev, accessed 29 September 2026).
• Wait automatically for elements to be ready before acting, and retry assertions until they pass.
• Isolate each test in a fresh browser context, which avoids side effects between tests.
• Parallelise execution by default across all configured browsers (source: playwright.dev, accessed 29 September 2026).
• Generate code by recording your actions (codegen) and replay a run step by step (Trace Viewer).
• Test HTTP APIs with the same runner as UI tests.
• Hand control to AI agents through an MCP server that exposes the browser as accessibility snapshots (source: playwright.dev, accessed 29 September 2026).

If you are new to the topic, start with our guide Test automation: definition, tools, steps (FR), which explains where Playwright tests fit in a complete test strategy.

How do you install Playwright?

To install Playwright, all you need is Node.js and to run npm init playwright@latest in a project folder: the wizard installs Playwright Test and the browsers, creates a configuration file and a first example test, and offers to add a GitHub Actions workflow.

npm init playwright@latest

The wizard asks you to choose between TypeScript and JavaScript (pick TypeScript), the name of the tests folder and whether to add a GitHub Actions workflow. It notably generates (source: playwright.dev, accessed 29 September 2026):

• playwright.config.ts: the configuration (browsers, base URL, reports, traces);
• package.json and package-lock.json;
• tests/example.spec.ts: a first test ready to run.

Check the system requirements before installing: the documentation asks for a recent version of Node.js (22.x, 24.x or 26.x at the time we consulted it) and Windows 11+, macOS 14+ or a recent Linux distribution (Debian 12/13, Ubuntu 22.04 or later) (source: playwright.dev, accessed 29 September 2026).

Running the tests

npx playwright test            # runs the whole suite, headless
npx playwright test --headed   # shows the browsers while the tests run
npx playwright test --ui       # opens UI mode, ideal for learning and debugging
npx playwright show-report     # opens the HTML report of the last run

The configuration file

Here is a short, commented configuration. baseURL lets you write page.goto('/login') instead of the full URL, and trace: 'on-first-retry' records a trace when a test fails and is then retried:

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

How do you write your first Playwright test?

A Playwright test is an asynchronous function declared with test(), which receives a page object, performs actions with await, then checks the result with expect(). The file name must end in .spec.ts to be picked up by the runner.

The example test generated at installation looks like this:

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

test('has a title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('Get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Reading this test line by line

• test('…', async ({ page }) => { … }) declares a test and receives a fresh browser page, isolated from the other tests.
• await page.goto(…) opens the URL. Every action is a promise: without await, the test would carry on without waiting.
• page.getByRole('link', { name: 'Get started' }) targets the link the way a user or a screen reader would.
• await expect(…).toBeVisible() is a "web-first" assertion: it retries until the condition is true or the timeout expires.

A more realistic scenario: logging in

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

test('login successful', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('qa@example.com');
  await page.getByLabel('Password').fill('test-password');
  await page.getByRole('button', { name: 'Log in' }).click();

  await expect(page).toHaveURL(/\/dashboard/);
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});

Notice that no pause is written: Playwright itself waits for the field to be ready, the button to be clickable and the heading to appear.

How do you target elements with Playwright locators?

Playwright locators target elements the way a user perceives them: by role and accessible name (getByRole), by form label (getByLabel), by text (getByText) or by test attribute (getByTestId). They are preferable to CSS or XPath selectors, which break at the slightest change in the page structure.

Chaining and filtering

Locators can be combined. To click the button of a specific row in a list:

const row = page.getByRole('listitem').filter({ hasText: 'Playwright Course' });
await row.getByRole('button', { name: 'Add to basket' }).click();
await expect(page.getByTestId('cart-total')).toHaveText('1 item');

A locator is not the element itself: it is a description, re-evaluated each time it is used. You can therefore declare it once and reuse it after a page reload without a "stale" element error. For larger suites, these locators are grouped into Page Object Model classes, a pattern taught in the certified Playwright course (FR).

How does Playwright's auto-waiting work?

Before each action, Playwright automatically checks that the element is ready ("actionability checks") and waits if it is not; web-first assertions, for their part, retry until the condition is true. The result: no sleep() or fixed wait to write, and far fewer flaky tests.

The checks before a click

Before a click(), Playwright makes sure the locator matches exactly one element, that this element is visible, stable (not mid-animation), receives events (nothing covers it) and is enabled; it waits until all these conditions are met or fails when the timeout expires (source: playwright.dev, accessed 29 September 2026).

Web-first assertions versus one-off checks

// Recommended: retries until the text appears
await expect(page.getByText('Payment accepted')).toBeVisible();

// Avoid: reads the state only once, fails if the page is not up to date yet
expect(await page.getByText('Payment accepted').isVisible()).toBe(true);

The first form waits; the second takes a snapshot of the state at a single moment. This is the most common beginner mistake, and the cause of many tests that "sometimes pass".

What are codegen and the Trace Viewer for?

Codegen is Playwright's test generator: it opens a browser, records your actions and writes the matching code, choosing the best locators. The Trace Viewer is the debugging tool: it replays a recorded run action by action, with the page state, network requests, console and screenshots.

Generating a test with codegen

npx playwright codegen demo.playwright.dev/todomvc

Two windows open: the browser, where you click and type, and the inspector, where the code is written live (source: playwright.dev, accessed 29 September 2026). Codegen is excellent for finding a locator or starting a scenario, but always review the result: it records what you do, not what needs to be verified. The assertions remain your job.

Debugging with the Trace Viewer

npx playwright test --trace on               # records a trace for every test
npx playwright show-report                   # opens the report, then a test's trace icon
npx playwright show-trace path/to/trace.zip

The Trace Viewer lets you step forwards and backwards through each action of the test and see what was happening at that moment (source: playwright.dev, accessed 29 September 2026). With trace: 'on-first-retry' in the configuration, a trace is produced automatically when a test fails in CI: you diagnose the failure without reproducing it on your machine.

Can you test an API with Playwright?

Yes: Playwright provides a request fixture that sends HTTP requests (GET, POST, PUT, DELETE…) without opening a browser, with the same runner, the same assertions and the same reports as UI tests. It is used to test an API directly or to prepare data before a UI scenario.

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

test('creates a user via the API', async ({ request }) => {
  const response = await request.post('/api/users', {
    data: { name: 'Ada', email: 'ada@example.com' },
  });
  await expect(response).toBeOK();

  const body = await response.json();
  expect(body.email).toBe('ada@example.com');
});

The base URL and shared headers (an authentication token, for example) are declared once in the configuration with baseURL and extraHTTPHeaders, then apply to all requests of the fixture (source: playwright.dev, accessed 29 September 2026). To compare with Postman and REST Assured, read API testing: definition, tools and examples.

How do you run Playwright in GitHub Actions?

To run Playwright in GitHub Actions, add to the repository a .github/workflows/playwright.yml file that installs the dependencies, installs the browsers with npx playwright install --with-deps, runs npx playwright test and publishes the report as an artefact. The npm init playwright@latest installer can create this file for you.

The workflow suggested by the official documentation (source: playwright.dev, accessed 29 September 2026):

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-node@v6
      with:
        node-version: lts/*
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    - name: Run Playwright tests
      run: npx playwright test
    - uses: actions/upload-artifact@v4
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

On every push or pull request, the suite runs on a fresh Linux machine and the HTML report (with the traces of retried tests) remains downloadable for 30 days. For GitLab CI, Jenkins and pipeline best practices, see Automated tests in a CI/CD pipeline.

Playwright, Cypress or Selenium: which should you choose?

For a new project or to learn in 2026, Playwright is the most complete choice: three browser engines, four languages, auto-waiting and parallelisation included. Cypress remains relevant in JavaScript front-end teams, notably for component testing; Selenium dominates existing suites and historical multi-language environments.

The details, with sources, are in our two comparisons: Playwright vs Cypress: which should you choose in 2026? and Playwright vs Selenium: is it still worth learning Selenium?

How do you learn Playwright?

To learn Playwright, start with guided, free content, practise on a demo application, then consolidate what you have learned (Page Object Model, API tests, CI) in a project you can show. Allow a few weeks of regular practice to be comfortable with the basics.

1. Discover it for free. ADC's free Playwright mini-course (FR) offers 7 lessons of 7 minutes, with no commitment: it is the first module of our certified course.
2. Practise on a demo application. Automate a complete journey (login, add to basket, checkout) with role-based locators and web-first assertions.
3. Structure. Move on to the Page Object Model, factor out the login, add API tests to prepare your data.
4. Industrialise. Plug the suite into GitHub Actions, enable traces, make your reports readable.
5. Validate. ADC's certified Playwright course (FR) covers this path in 40 hours and 6 modules: fundamentals, Page Object Model, API testing and parallelisation, CI/CD with GitHub Actions, reports and debugging, then a certification project.

If your goal is a career change, the QA Automation & AI Tester course (399 hours over 12 weeks) includes Playwright with TypeScript in a complete path: test design, API testing, CI, AI applied to testing, and the ISTQB CTFL v4.0 (Certified Tester Foundation Level) and CT-GenAI v1.1 (Certified Tester Testing with Generative AI) exams included.

Frequently asked questions about Playwright

Is Playwright free?

Yes. Playwright is an open source Microsoft project released under the Apache 2.0 licence: the library, the Playwright Test runner, codegen and the Trace Viewer are free, including for commercial use.

Which language should I choose to learn Playwright?

TypeScript is the most common choice: it is the reference language of the documentation and of the Playwright Test runner. Playwright is also available for Python, Java and .NET if your team already uses one of them. ADC teaches Playwright with TypeScript.

Does Playwright work with Safari?

Playwright drives WebKit, the rendering engine behind Safari, on Windows, Linux and macOS, as well as a Mobile Safari emulation. It does not drive the Safari application itself, but WebKit lets you detect problems specific to that engine.

Do I need to know how to code to use Playwright?

Yes, but the basics are enough to get started: variables, functions, async/await. Codegen helps you write the first lines by recording your actions, but you still need to read and fix the code and write the assertions. ADC's free mini-course is designed for beginners.

Can Playwright replace Postman for API testing?

For automated API tests in CI, often yes: the request fixture sends HTTP requests with the same assertions and reports as UI tests. Postman remains handy for exploring and documenting an API by hand.

How long does it take to learn Playwright?

A few weeks of regular practice to be comfortable with the basics: locators, assertions, configuration and CI. ADC's certified Playwright course covers the complete path in 40 hours, certification project included.

All frequently asked questions: pricing, ISTQB, evening courses, career change (FR)