Playwright complete notes: from beginner to advanced

Playwright is Microsoft's open-source framework for end-to-end testing of web apps. One API drives Chromium, Firefox and WebKit, waits for elements automatically, and ships its own test runner, reporter, trace viewer and code generator.

• Cross-browser: Chromium (Chrome, Edge), Firefox and WebKit (Safari's engine) — on Windows, macOS and Linux.
• Auto-waiting: actions wait until an element is ready; assertions retry until they pass.
• Isolation: every test gets a fresh browser context — its own cookies and storage — in milliseconds.
• Batteries included: parallel runs, retries, HTML report, traces, codegen, UI mode, API testing and network mocking.
• Languages: TypeScript/JavaScript (primary, gets features first), Python, Java and .NET.

Your test calls the Playwright API; Playwright sends each command over one persistent connection to the browser and receives events back on the same channel. There is no WebDriver server and no HTTP request per command — that is a large part of why Playwright is fast.

• Chromium is driven over the Chrome DevTools Protocol; Firefox and WebKit are Playwright-patched builds with their own protocols.
• Python, Java and .NET clients talk to a bundled Node.js driver over a pipe; the driver talks to the browsers.
• Because the connection is bidirectional, Playwright hears about network requests, dialogs, console messages and navigations the moment they happen.
• Playwright does not use Selenium or WebDriver — it is a separate stack end to end.

Tip: Locally there is nothing extra to start: Playwright launches the browsers itself and talks to them over a pipe. A separate browser server is only involved in remote setups — browserType.launchServer() or a cloud grid you connect to.

You need a current LTS version of Node.js. The official initializer asks four questions — TypeScript or JavaScript, the tests folder, whether to add a GitHub Actions workflow, and whether to install browsers — and generates a working project.

npm init playwright@latest

# or add to an existing project
npm install -D @playwright/test
npx playwright install

# run the example tests and open the report
npx playwright test
npx playwright show-report

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

export default defineConfig({
  testDir: './tests',                 // where tests live
  timeout: 30_000,                    // per test
  expect: { timeout: 5_000 },         // per assertion
  use: {
    baseURL: 'http://localhost:3000', // so page.goto('/login') works
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

Tip: Tests run headless by default and print results in the terminal. Add --headed to watch the browsers, or --ui for the interactive runner with time travel.

A Browser is a running engine. A BrowserContext is an isolated, incognito-like session inside it with its own cookies, storage and permissions. A Page is a single tab inside a context. The test runner creates a fresh context and page for every test, so you rarely create them yourself.

• Analogy: the browser is a building, contexts are separate flats, pages are rooms in a flat.

test('admin sees the user’s message', async ({ browser }) => {
  const adminContext = await browser.newContext({ storageState: 'playwright/.auth/admin.json' });
  const userContext = await browser.newContext({ storageState: 'playwright/.auth/user.json' });
  const admin = await adminContext.newPage();
  const user = await userContext.newPage();

  await user.goto('/chat');
  await user.getByRole('textbox').fill('Hello admin');
  await user.keyboard.press('Enter');

  await admin.goto('/chat');
  await expect(admin.getByText('Hello admin')).toBeVisible();

  await adminContext.close();
  await userContext.close();
});

A locator describes how to find an element and is re-evaluated every time you use it, so it survives re-renders. Prefer locators based on what the user sees — role, label, text — over CSS classes and XPath, which break when markup changes.

await page.getByRole('textbox', { name: 'Email' }).fill('qa@example.com');
await page.getByLabel('Password').fill(process.env.PASSWORD!);
await page.getByRole('checkbox', { name: 'Remember me' }).check();
await page.getByRole('button', { name: 'Sign in' }).click();

// Narrow down instead of using indexes
const row = page.getByRole('row').filter({ hasText: 'Ada Lovelace' });
await row.getByRole('button', { name: 'Edit' }).click();

Watch out: getByText matches a case-insensitive substring and normalises whitespace — pass { exact: true } for an exact match. On lists that can reorder, filter by text or by a child rather than picking by index with .nth().

Before an action, Playwright waits until the element is actionable. For a click that means visible, stable (not animating), receiving events (nothing covering it) and enabled; for fill() it means visible, enabled and editable. Assertions made with expect(locator) retry until they pass or time out. Together they remove almost every sleep and explicit wait.

await page.getByRole('button', { name: 'Login' }).click();
// no waits: both assertions retry until true (5 s by default)
await expect(page).toHaveURL(/\/dashboard/);
await expect(page.getByText('Welcome, QA')).toBeVisible();

Watch out: Auto-waiting covers actions and expect(locator / page) assertions. A value you read yourself is read once: write await expect(locator).toHaveText('x'), which retries, rather than expect(await locator.textContent()).toBe('x'), which doesn't.

Actions are methods on a locator: click, fill, check, selectOption, hover, press, setInputFiles, dragTo. Each one auto-waits for the element to be actionable. Pick the method that matches what the user does — fill for typing a value, selectOption for a native select.

await page.getByPlaceholder('Full name').fill('Ada Lovelace');
await page.getByLabel('Country').selectOption('UA');
await page.getByLabel('City').pressSequentially('Kyi', { delay: 50 });
await page.getByRole('option', { name: 'Kyiv' }).click();
await page.getByLabel('I accept the terms').check();
await page.getByLabel('CV').setInputFiles('fixtures/cv.pdf');
await page.locator('#card-7').dragTo(page.locator('#done'));

Watch out: Each action returns a Promise, so await them one by one: await field.fill('admin'); then await field.press('Tab'). Use { force: true } only when you know why an element isn't actionable — usually an overlay is covering it for real users too.

Real apps embed payment iframes, open links in new tabs, pop confirm dialogs and export files. Playwright handles each with a small pattern — and the rule for tabs, downloads and dialogs is the same: start listening before the click that triggers them.

• Multiple tabs: context.pages() lists every open page in the context.
• Upload: locator.setInputFiles(path | path[]); pass [] to clear.
• Without a dialog handler Playwright dismisses dialogs automatically — so an unexpected confirm() won't hang the test.

const payment = page.frameLocator('iframe[title="Payment"]');
await payment.getByLabel('Card number').fill('4242 4242 4242 4242');

const popupPromise = page.waitForEvent('popup');
await page.getByRole('link', { name: 'Terms' }).click();
const popup = await popupPromise;
await expect(popup).toHaveURL(/terms/);

page.once('dialog', async (dialog) => {
  expect(dialog.message()).toContain('Delete this item?');
  await dialog.accept();          // or dialog.dismiss(), or accept('text') for prompts
});
await page.getByRole('button', { name: 'Delete' }).click();

const downloadPromise = page.waitForEvent('download');
await page.getByRole('button', { name: 'Download report' }).click();
const download = await downloadPromise;
await download.saveAs(`downloads/${download.suggestedFilename()}`);

Tip: One pattern covers popups, downloads, file choosers and responses: create the waitForEvent promise, click, then await the promise.

Actions and assertions already wait, so explicit waits are only for the few cases an assertion can't express — a URL change, a network response, or an element that must disappear.

const saved = page.waitForResponse((r) => r.url().includes('/api/profile') && r.request().method() === 'PUT');
await page.getByRole('button', { name: 'Save' }).click();
expect((await saved).ok()).toBe(true);
await expect(page.getByRole('status')).toHaveText('Saved');

Tip: Timeouts are limits, not waits: setDefaultTimeout() and { timeout } only change how long Playwright keeps trying before it fails. To know a page is ready, assert on the element you need — pages with polling or analytics never go network-idle.

The request fixture sends HTTP calls without a browser — ideal for API tests and for fast setup. page.route() intercepts the browser's own traffic so you can mock responses, patch real ones, change requests or block resources.

• Test error states cheaply: fulfill with status 500 and check the UI's error message.
• Use API calls to create and delete test data; keep the UI for the behaviour under test.

test('creates a user', async ({ request }) => {
  const response = await request.post('/api/users', { data: { name: 'Ada', job: 'QA' } });
  await expect(response).toBeOK();
  const user = await response.json();
  expect(user).toMatchObject({ name: 'Ada' });
});

const api = await playwright.request.newContext({
  baseURL: 'https://api.example.com',
  extraHTTPHeaders: { Authorization: `Bearer ${process.env.API_TOKEN}` },
});

// Mock: never hit the server
await page.route('**/api/users', (route) =>
  route.fulfill({ status: 200, json: { data: [{ id: 1, name: 'Mock User' }] } }),
);

// Patch: real response, one field changed
await page.route('**/api/flags', async (route) => {
  const response = await route.fetch();
  const json = await response.json();
  await route.fulfill({ response, json: { ...json, newCheckout: true } });
});

// Modify the request
await page.route('**/api/search**', (route) => {
  const url = new URL(route.request().url());
  url.searchParams.set('limit', '5');
  return route.continue({ url: url.toString() });
});

Fixtures are Playwright's dependency injection: a test lists what it needs ({ page, loginPage, apiClient }) and gets it, with setup and teardown handled for it. Hooks still exist for simple cases. Tests run in parallel worker processes, and projects run the same tests against different browsers or settings.

• Workers: set workers in the config or --workers=4; fullyParallel: true also parallelises tests inside one file.
• Projects: the same suite on Chromium, Firefox and WebKit, or on mobile viewports, or with a setup project that logs in first.
• Sharding: --shard=1/4 splits the suite across CI machines.

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

export const test = base.extend<{ loginPage: LoginPage }>({
  loginPage: async ({ page }, use) => {
    await use(new LoginPage(page)); // code after use() is teardown
  },
});
export { expect } from '@playwright/test';

test.beforeEach(async ({ page }) => {
  await page.goto('/');
});

test.afterEach(async ({ page }, testInfo) => {
  if (testInfo.status !== testInfo.expectedStatus) console.log(`Failed on ${page.url()}`);
});

Watch out: beforeAll runs once per worker process — with 4 workers, 4 times, and again if a worker restarts after a failure. For one-time global work such as seeding data or logging in, use a setup project with dependencies, or globalSetup.

Playwright's best debugging tool is the trace: a recording of every action with DOM snapshots, network, console and source you can scrub through. Pair it with the HTML report, UI mode for local work and the Inspector for stepping line by line.

use: {
  trace: 'on-first-retry',          // or 'retain-on-failure'
  screenshot: 'only-on-failure',
  video: 'retain-on-failure',
},
reporter: [['html'], ['list']],   // add 'junit' or 'allure-playwright' for CI dashboards

The last year of releases pushed Playwright toward AI agents and toward stricter control of flaky tests. You don't need all of it on day one, but you should know it exists.

test('changes global settings', { lock: 'user-settings' }, async ({ page }) => {
  await page.goto('/settings');
  await page.getByLabel('Language').selectOption('uk');
  await expect(page.getByRole('heading', { level: 1 })).toHaveText('Налаштування');
});

If you can answer these without notes, you know Playwright well enough for most QA automation interviews — and for owning a real suite.

• Write clean tests: one behaviour per test, independent data, no order dependency.
• Trust auto-waiting; delete sleeps.
• Keep page objects thin and assertions in tests.
• Next: build the framework from the scalable-framework guide and practise on the Playwright Sandbox.