Playwright fundamentals - six-module roadmap

1Setup and your first test

Install the Playwright Test runner, look at the generated playwright.config.ts, and run a single spec against a TTA practice page.

graph LR
  A[npm init playwright]:::start --> B[install browsers]
  B --> C[playwright.config.ts]
  C --> D[sample spec]
  D --> E[npx playwright test]:::ok
  classDef start fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a;
  classDef ok fill:#dcfce7,stroke:#15803d,color:#14532d;
                

What the runner gives you

• Project bootstrap. npm init playwright@latest writes playwright.config.ts, a sample spec, a GitHub Actions workflow, and installs the three browser binaries (Chromium, Firefox, WebKit).
• Config knobs you will touch first. testDir, timeout, retries, use.baseURL, use.trace, use.screenshot, and the projects array for cross-browser runs.
• Run modes. npx playwright test for headless CI, --headed to watch in a real window, --ui for the watch-mode panel with time travel, --debug to step with the inspector.

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

test('load TTA practice landing', async ({ page }) => {
  await page.goto('/playwright/widgets/expect.html');
  await expect(page).toHaveTitle(/Assertions/);
});

Exercises

1. Initialise a fresh project, set use.baseURL to https://app.thetestingacademy.com, and write a spec that opens /playwright/widgets/expect.html with a relative path.
2. Add a second project to playwright.config.ts for firefox and run only that project from the CLI with --project=firefox.
3. Run the same spec in three modes - --ui, --headed, and headless - and note which one shows the time-travel timeline.
4. Set retries: 1 in the config, force a failure with expect(page).toHaveTitle('nope'), and confirm the trace from the retry appears in test-results/.

2Locators and selectors

Find elements the way Playwright wants you to - by role, label, and test-id. Fall back to CSS or XPath only when the semantic API isn't enough.

graph TD
  A[getByRole / getByLabel / getByTestId]:::best --> B[getByText / getByPlaceholder]:::good
  B --> C[page.locator css]:::ok
  C --> D[xpath= fallback]:::last
  classDef best fill:#dcfce7,stroke:#15803d,color:#14532d;
  classDef good fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a;
  classDef ok fill:#fef3c7,stroke:#b45309,color:#7c2d12;
  classDef last fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d;
                

Pick your locator in this order

1. Role-based. page.getByRole('button', { name: 'Login' }) is closest to what a real user does and survives style changes.
2. Label / placeholder. For form fields - getByLabel('Email'), getByPlaceholder('[email protected]').
3. Test id. getByTestId('cart-badge') when there is no visible text. Configure testIdAttribute in the config if your app uses a different attribute name.
4. Text. getByText('Add to cart') for ad-hoc spans and links.
5. CSS / XPath. The escape hatch for legacy markup. Prefer chained .locator() + .filter() over long XPath.

Chaining and filtering

Locators compose. The strict mode error you get from a locator that resolves to two elements is your prompt to narrow down with a child locator or a filter.

const row = page.getByRole('row', { name: 'Burj Khalifa' });
const joined = row.getByRole('cell').nth(3);
await expect(joined).toHaveText('2010');

Frames and shadow DOM

For iframes use page.frameLocator('iframe[name=editor]').getByRole('textbox'). Shadow DOM works transparently with the semantic locators - getByRole and getByText pierce open shadow roots automatically. You only need extra ceremony for closed shadow roots, which are rare.

Exercises

1. On /multiple_element_filter.html count the visible product cards with getByRole('article'), then filter to cards containing the text "Out of stock".
2. Open /webtable.html, locate the row for "Burj Khalifa" using getByRole('row'), and read the value in the fourth cell.
3. On the Tall Buildings table at /tables/practice.html, assert the row count and then read the "Joined" column for the third row.
4. Inspect the shadow-DOM widget at /widgets/shadow-dom.html. Find the inner button using getByRole without a manual shadow-piercing selector.
5. Use a CSS escape-hatch locator (page.locator('.alert.alert-danger')) where the role-based one is awkward, then justify in 1 sentence why role would still be better.

3Actions

Click, fill, select, drag, keyboard. Every action auto-waits for the element to be actionable, so most flakiness around "the element wasn't ready" disappears.

graph LR
  A[action requested]:::s --> B{attached?}
  B -- no --> X[retry until timeout]:::w
  B -- yes --> C{visible?}
  C -- no --> X
  C -- yes --> D{stable?}
  D -- no --> X
  D -- yes --> E{receives events?}
  E -- no --> X
  E -- yes --> F{enabled?}
  F -- no --> X
  F -- yes --> G[click fires]:::ok
  X --> B
  classDef s fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a;
  classDef w fill:#fef3c7,stroke:#b45309,color:#7c2d12;
  classDef ok fill:#dcfce7,stroke:#15803d,color:#14532d;
                

Actionability checks before every click

Playwright waits for the element to be attached, visible, stable, receive events, and not disabled before firing the action. You almost never need a manual waitForSelector.

Filling forms

• fill('Aarav') clears the field and sets the value in one step - this is what you want 95% of the time.
• type('Aarav', { delay: 50 }) simulates key-by-key typing. Use this when the page has a debounced search or a typeahead.
• pressSequentially('Aarav') is the newer, clearer name for the same key-by-key behaviour.
• selectOption('Z to A') works by visible text by default. Pass { value: 'za' } when only the value attribute is stable.
• check() and uncheck() idempotently toggle checkboxes and radios.
• setInputFiles('./fixtures/avatar.png') uploads without ever opening the native file chooser.

Drag and drop, keyboard, dialogs

Drag with source.dragTo(target) for tidy HTML5 drag-and-drop. Use page.mouse for finer-grained control when the app uses pointer events. Press multi-key combos via page.keyboard.press('Control+Shift+P'). For native confirm / alert / prompt, register a handler with page.on('dialog', d => d.accept()) before triggering the action that opens it.

Exercises

1. On /tables/practice.html fill the QA Profile form with fill for every text input, selectOption for the dropdown, check for the checkbox group, and assert the submission summary.
2. On /widgets/dnd.html drag a card from the "Backlog" column to "In Progress" using dragTo, then assert both columns have the new item counts.
3. On /widgets/dialogs.html register a single handler that accepts alert and confirm but cancels prompt. Trigger all three and assert the page state.
4. On /widgets/keyboard-form.html tab between three fields, press Enter to submit, and assert the confirmation toast.
5. On /widgets/upload-download.html upload a small text file with setInputFiles and assert the displayed file name and size.

4Assertions with expect

Web-first assertions retry until they pass or time out. That is the secret to non-flaky tests. Learn the locator-level expects, then layer in soft assertions for full-page checks.

graph LR
  A[expect locator]:::s --> B[check matcher]
  B -- pass --> D[continue]:::ok
  B -- fail --> C[wait 100ms]
  C --> E{timeout reached?}
  E -- no --> B
  E -- yes --> F[throw error]:::bad
  classDef s fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a;
  classDef ok fill:#dcfce7,stroke:#15803d,color:#14532d;
  classDef bad fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d;
                

Web-first auto-waiting

Each expect(locator).toX() retries internally up to the configured timeout (default 5 seconds). You almost never need await page.waitForTimeout(...). Sleeps are a smell - prefer a real assertion or a network wait.

Soft assertions

expect.soft records the failure but lets the test continue, so a single test can check three things on the order-summary page and report all three. Combine soft asserts with a final regular expect to make the test fail at the end.

await expect.soft(page.getByText('Order #')).toBeVisible();
await expect.soft(page.getByText('Total $99.97')).toBeVisible();
await expect(page).toHaveURL(/checkout-complete/);

Exercises

1. On /widgets/expect.html exercise eight different locator-level assertions back to back - visibility, text, value, count, attribute, class, checked, URL.
2. On /webtable.html assert the table has exactly the number of rows the page header claims, then read the second row and check its text.
3. Force a flaky check with a 2-second delayed update on /widgets/toasts.html and prove that expect(locator).toBeVisible() waits without an explicit sleep.
4. Write three soft assertions on the order-confirmation summary, then a final expect(page).toHaveURL. Confirm the test reports all three soft failures when you intentionally break the price line.
5. Use expect.poll to wait for an API-driven counter on the page to reach a target value within 8 seconds.

5Fixtures and hooks

Fixtures replace the setup/teardown gymnastics from other runners. Built-ins give you page, context, and browser. Custom fixtures inject your page objects, your logged-in user, your API client.

graph LR
  A[beforeAll]:::all --> B[beforeEach]:::each
  B --> C[test body]:::test
  C --> D[afterEach]:::each
  D --> E{more tests?}
  E -- yes --> B
  E -- no --> F[afterAll]:::all
  classDef all fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a;
  classDef each fill:#fef3c7,stroke:#b45309,color:#7c2d12;
  classDef test fill:#dcfce7,stroke:#15803d,color:#14532d;
                

Built-in fixtures

• page - a fresh browser tab per test, isolated from other tests.
• context - the parent browser context. Use it directly to open extra pages, set cookies, or change viewport on the fly.
• browser - the running Chromium / Firefox / WebKit instance. Rarely needed except for very advanced setups.
• request - a dedicated APIRequestContext for HTTP calls, separate from the browser session.

Custom fixtures with test.extend

Wrap setup so every spec gets a ready-to-use object - a logged-in page, a constructed LoginPage, a seeded cartId. The fixture function returns through await use(value); anything after use runs as teardown.

import { test as base } from '@playwright/test';
type Fix = { signedInPage: Page };

export const test = base.extend<Fix>({
  signedInPage: async ({ page }, use) => {
    await page.goto('/playwright/ttacart/index.html');
    // log in once per test - or load storageState for once-per-suite
    await use(page);
  },
});

Hooks

test.beforeAll and test.afterAll run once per worker. test.beforeEach and test.afterEach run around every test. Wrap multi-step business logic in test.step('checkout - step 1', async () => { ... }) so the HTML report and trace show readable stages.

Exercises

1. Write a beforeEach that lands every test on /widgets/test-modifiers.html and asserts the page title before the test body runs.
2. Create a custom fixture filledForm that opens /tables/practice.html and pre-fills three fields. Two specs should reuse it.
3. Inside a single test, group three logical phases with test.step - "load", "interact", "verify". Confirm the steps show up as collapsible nodes in the HTML report.
4. Use test.info().annotations.push({ type: 'jira', description: 'TTA-123' }) and confirm the annotation appears in the report.

6Test runner basics

Group, filter, parallelise. The Playwright runner is built around describe blocks, modifiers, tags, and a multi-worker model that runs files in parallel.

stateDiagram-v2
  [*] --> pending
  pending --> running
  running --> passed
  running --> failed
  running --> skipped
  failed --> flaky : retry passed
  flaky --> [*]
  passed --> [*]
  failed --> [*]
  skipped --> [*]
                

graph LR
  A[all specs]:::all --> B{grep filter}
  B -- match @smoke --> C[selected smoke specs]:::ok
  B -- no match --> D[excluded]:::skip
  C --> E[run]
  classDef all fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a;
  classDef ok fill:#dcfce7,stroke:#15803d,color:#14532d;
  classDef skip fill:#f1f5f9,stroke:#94a3b8,color:#475569;
                

describe and modifiers

• test.describe('login', () => { ... }) groups related specs.
• test.only isolates one spec during local debugging. CI should fail if .only sneaks in - set forbidOnly: !!process.env.CI in the config.
• test.skip / .fixme / .fail document why a spec is paused, broken, or expected to fail.
• test.slow triples the timeout for that single test. Useful for legitimately slow flows like a multi-step checkout.

Tags via grep

Embed tags right in the title: test('@smoke standard user logs in', ...). Then run them by name with --grep @smoke or invert with --grep-invert @flaky. Tag conventions to start with: @smoke, @regression, @p0, @e2e, @visual.

Parallelism, retries, timeouts

Files run in parallel by default, tests within a file run serially. Override with test.describe.configure({ mode: 'parallel' }) to parallelise inside a file. retries: 1 in CI catches network blips. Per-test timeout via test.setTimeout(60_000); per-action timeout via locator.click({ timeout: 10_000 }).

Exercises

1. Wrap four related specs in a single describe('cart', () => { ... }) and run them serially with describe.configure({ mode: 'serial' }).
2. Tag two specs @smoke and three @regression. Run only smoke from the CLI and confirm the count.
3. Mark one spec test.fixme with a comment explaining the bug ticket, and another test.slow with a 90-second budget.
4. Set workers: 4 in the config, run the full suite, and observe the worker assignment column in the HTML report.
5. Add retries: 1 and intentionally fail a test once - confirm the retry runs and the final status reflects the retry result.