Playwright

Picture a small to-do app. You type "Buy milk", press Enter, and the item appears in the list. Each time someone changes the app, somebody should check that this still works. Doing it by hand is called manual testing: open the app, type, press, look.

Manual checks are slow, boring and easy to forget. After the tenth change nobody re-checks the sign-in page, and that is when it breaks. An automated test is a small program that does the checking for you, the same way every time, in seconds.

Test

A small program that uses your app and checks the result is what you expected.

Manual testing

A person clicking through the app to see whether it works.

Automated test

A test written as code, so a computer can run it again and again.

Almost every test, in any language, has the same three parts. Testers call them arrange, act, assert. Read it as a recipe for one check.

1. Arrange: get to the starting point. Open the to-do app with an empty list.
2. Act: do the thing a person would do. Type "Buy milk" and press Enter.
3. Assert: check what should now be true. The list shows one item, "Buy milk".

If the check holds, the test passes. If it does not, the test fails and tells you what it expected and what it found. A failing test is not a disaster: it is the test doing its job, catching a problem before a real person does.

Tests come in sizes. A unit test checks one small piece of code on its own, like a function that adds up a cart’s total. An integration test checks a few pieces working together. An end-to-end test (often written E2E) checks the whole app the way a person uses it: a real browser, real pages, real clicks.

Unit test

A test of one small piece of code, run without a browser.

End-to-end (E2E) test

A test that drives the real app in a real browser, start to finish.

End-to-end tests are the most realistic, but they are slower and have more parts that can go wrong. Teams usually write many unit tests, some integration tests, and a smaller set of end-to-end tests for the journeys that matter most. People draw this as a pyramid.

Unit tests run your code without a screen. They cannot see what a browser adds on top: how the page is laid out, whether a button is hidden behind another one, whether a script fails to load. A real browser test catches the bugs people actually meet.

Playwright is a free, open-source tool from Microsoft for end-to-end testing. You write tests in JavaScript or TypeScript; Playwright opens a browser, visits your pages, clicks, types, and checks what it sees. It can drive the three main browser engines: Chromium (Chrome and Edge), Firefox, and WebKit (Safari).

• Playwright Test is the test runner: it finds your tests, runs them, and reports results.
• It waits for the page to be ready on its own, so tests do not need pauses.
• It comes with tools to record, debug and replay tests.

• It checks what a person cares about: "the item appears", not "a function was called".
• It fails for one reason: when it breaks, you know where to look.
• It gives the same answer every time: a test that passes and fails at random is called flaky, and people stop trusting it.
• It is cheap to read: someone new can tell what it checks in a few seconds.

Flaky test

A test that sometimes passes and sometimes fails with no change to the code.

• A test prepares, acts and checks: arrange, act, assert.
• Unit tests check small pieces quickly; end-to-end tests check whole journeys in a browser.
• Keep many small tests and a focused set of end-to-end tests.
• Playwright drives Chromium, Firefox and WebKit from code.
• A good test checks what users see, fails for one reason, and never flakes.

When you visit an address, the browser asks a server (a computer somewhere that hosts the app) for the page. The server answers with HTML: plain text made of tags that say what is on the page. <h1> is a big heading, <button> is a button, <input> is a box to type in.

1<h1>My to-dos</h1>2<label for="new">What needs doing?</label>3<input id="new" />4<ul>5  <li>Buy milk</li>6  <li>Walk the dog</li>7</ul>

Server

The computer that stores the app and sends pages to browsers.

HTML

The text that describes what is on a page, written as tags like <button>.

Element

One thing on the page made from a tag: a heading, a button, a list item.

The browser reads the HTML and builds a tree of elements in memory, called the DOM (Document Object Model). Elements sit inside other elements, like folders in folders. The page you see is drawn from this tree, and when the tree changes, the screen changes.

DOM

The live tree of elements the browser builds from HTML. Scripts change it; the screen follows.

Most apps also send JavaScript, a programming language the browser runs. It listens for what you do and changes the DOM: when you press Enter in the to-do box, a script adds a new <li> to the list. Nothing reloads; the tree just grows.

This matters for testing because changes take time. The script might first ask the server to save the item, wait for the answer, and only then add it. A test that looks for the new item too early will not find it.

To a browser, a click is not one thing. The mouse moves over the element, the button goes down, the button comes up, and only then does a click event fire. Scripts listen for these events and react. A real user also cannot click something hidden, covered by something else, or greyed out.

Event

A message the browser sends when something happens: a click, a key press, a page load.

Besides the page itself, the browser makes many requests: for images, styles, scripts, and data. When the shop shows your cart, a script might request /api/cart and get back JSON, a text format for data. Each request gets a response with a status code: 200 means OK, 404 means not found, 500 means the server broke.

Request / response

The browser asks the server for something; the server answers.

JSON

A text format for data, like { "items": 2 }.

Status code

A number on every response: 200 OK, 404 not found, 500 server error.

Some people use a screen reader, software that reads the page aloud. It does not see colours or layout. It reads a second tree the browser builds, the accessibility tree, where each thing has a role (what kind of thing it is: button, link, heading, textbox) and a name (what it is called: "Add to cart").

• The server sends HTML; the browser builds the DOM, a tree of elements.
• JavaScript changes the DOM over time, so tests must wait for changes.
• A click is a sequence of events, and only works on visible, enabled, uncovered elements.
• Pages request data in the background; responses carry a status code.
• The accessibility tree gives each element a role and a name.

Developers install and run tools by typing commands in a terminal: a window where you type a line, press Enter, and the computer answers in text. On macOS it is the Terminal app, on Windows PowerShell or Windows Terminal, on Linux usually just "Terminal". In this course, a line in a bash block is a command to type there.

1cd my-todo-app2ls

Terminal

A text window where you type commands and read their output.

Command

One line typed into the terminal, like cd my-todo-app.

Folder (directory)

Where files live. A project is one folder with everything inside.

Playwright tests are JavaScript (or TypeScript, JavaScript with types). Outside a browser, JavaScript runs on Node.js, a program you install once from nodejs.org. Node comes with npm, which downloads packages: ready-made code other people publish, like Playwright.

1node --version2npm --version

Node.js

A program that runs JavaScript on your computer, outside the browser.

npm

The tool that installs packages and runs project scripts.

Package

Code someone published for others to install, like @playwright/test.

TypeScript

JavaScript with types, which catch mistakes before the code runs.

Inside your project folder, run the Playwright starter. It asks a few questions; the defaults are fine. Choose TypeScript, keep the tests folder, and say yes to installing browsers.

1npm init playwright@latest

• TypeScript or JavaScript? TypeScript: your editor will catch typos in locators and options.
• Where to put tests? tests is the usual name.
• Add a GitHub Actions workflow? A file that runs tests on GitHub on every change. Yes is handy; module 17 explains it.
• Install browsers? Yes: Playwright downloads its own copies.

Config file

playwright.config.ts: the settings every test shares.

Spec file

A file of tests. "Spec" is short for specification: what the app should do.

Each Playwright version is tested with exact builds of Chromium, Firefox and WebKit, so it downloads those builds into a shared folder on your computer. When you update Playwright, install its browsers again so the two match.

1# all three browsers2npx playwright install3
4# only Chromium, plus the system libraries it needs (Linux)5npx playwright install --with-deps chromium

By default Playwright runs browsers headless: they load and run pages fully, but draw no window on your screen. It is faster and works on servers with no screen at all. When you want to watch, run headed.

• Commands are typed in a terminal; cd moves between folders.
• Node.js runs JavaScript; npm installs packages.
• npm init playwright@latest creates the config, a tests folder and an example.
• Playwright downloads browser builds that match its version: npx playwright install.
• Tests run headless by default; --headed shows the window.

Playwright keeps a public to-do app for practice at demo.playwright.dev/todomvc, so you can run this test without building anything. Make a file tests/todo.spec.ts and type it in. The next slides go through it line by line.

1import { test, expect } from '@playwright/test'2
3test('adds a to-do', async ({ page }) => {4  await page.goto('https://demo.playwright.dev/todomvc')5  const box = page.getByPlaceholder('What needs to be done?')6  await box.fill('Buy milk')7  await box.press('Enter')8  await expect(page.getByTestId('todo-title')).toHaveText('Buy milk')9})

1npx playwright test tests/todo.spec.ts

Your test runs in Node.js; the page runs inside the browser, a separate program. Every command travels to the browser and back, which takes a moment. In JavaScript, a function that takes time is asynchronous: it hands back a promise, a placeholder for an answer that is coming. await means "wait here until the answer arrives".

A function that uses await must be marked async, which is why the test function is async ({ page }) => { … }.

Asynchronous

Takes time to finish, so the code waits for it instead of getting an answer at once.

Promise

A value that will exist later. await pauses until it does.

`async` function

A function allowed to use await inside.

Run npx playwright test in the terminal, from the project folder. Playwright finds your spec files, starts browsers, runs each test, and prints a summary.

1Running 3 tests using 3 workers2  3 passed (2.1s)3
4To open last HTML report run:5  npx playwright show-report

Worker

A separate process that runs tests. Several workers run tests at the same time to finish sooner.

Change the expected text to "Buy bread" and run again. The test fails, and the message says exactly what went wrong. Learn to read it top to bottom: which check, what it wanted, what it got, and where.

11) [chromium] › tests/todo.spec.ts:3:1 › adds a to-do2
3  Error: expect(locator).toHaveText(expected) failed4
5  Locator:  getByTestId('todo-title')6  Expected: "Buy bread"7  Received: "Buy milk"8  Timeout:  5000ms9
10  > 8 |   await expect(page.getByTestId('todo-title')).toHaveText('Buy bread')11      |                                                ^

• The first line names the browser, the file, the line and the test.
• Expected is what you asked for; Received is what the page had.
• Timeout shows it kept checking for 5 seconds before giving up.
• The code frame points at the line that failed.

• test(name, async ({ page }) => { … }) declares a test with its own fresh tab.
• page.goto opens an address; locators describe how to find elements.
• Actions like fill and press wait for the element first.
• await expect(locator).toHaveText(…) checks, retrying for up to 5 seconds.
• Every browser command is asynchronous: await it.
• A failure shows the locator, expected, received, and the line.

npx playwright test runs everything. As a suite grows you will often want just a part of it. Everything after test is an option (also called a flag) that changes what runs.

After each run Playwright writes a web page summarising every test, in the playwright-report folder. When a test fails on your machine, it opens by itself; otherwise open it with npx playwright show-report.

• Every test, grouped by file, with pass, fail, flaky or skipped.
• For each test, its steps and how long each took.
• For failures: the error, the code that failed, and any screenshots or traces.
• A search box and filters by browser and status.

Reporter

What turns results into output: a list in the terminal, an HTML page, a file for CI.

`test-results/`

The folder of files from the last run: screenshots, videos and traces of failed tests.

npx playwright test --ui opens a window listing all your tests. Click one to run it. Afterwards, every action is listed on the left; click an action to see the page as it was at that moment, before and after, with the network requests and console messages next to it.

• Watch mode (the eye icon): rerun a test whenever you save its file.
• Pick locator: hover over the page snapshot to get a locator for any element.
• Filters: by name, browser, or status.
• It is the best way to learn, because you can see what each line did.

Codegen (short for code generator) opens a browser and a recorder side by side. As you click and type, it writes the test code for you, choosing locators by role and text where it can.

1npx playwright codegen https://demo.playwright.dev/todomvc

• Add checks with the toolbar buttons: "assert visibility", "assert text", "assert value".
• Copy the code into a spec file, then tidy it: good names, fewer steps, clear checks.
• --device="iPhone 13" records on a simulated phone.

A trace is a file that records a whole test: each action, a snapshot of the page before and after, network requests, console messages and errors. The starter config records one when a test is retried after failing, which is how you debug a failure that happened on another computer.

1# record a trace for every test this time2npx playwright test --trace on3
4# open one5npx playwright show-trace test-results/…/trace.zip

• Pick tests by file, by line, by name (-g) or by project.
• --headed, -x and --last-failed speed up everyday work.
• The HTML report shows every test, its steps and its failures.
• UI mode runs tests and lets you step back through each action.
• Codegen records a draft test; traces record a run to replay later.

Before a test can click or check anything, it has to say which element. A locator is that description. The best descriptions are the ones a person would use: "the Sign in button", "the Email box", "the heading Your cart".

From here on, the course follows a small online shop: a sign-in page, a product list, a cart, and a checkout. This is its sign-in form.

1<h1>Sign in</h1>2<form>3  <label for="email">Email</label>4  <input id="email" type="email" />5  <label for="password">Password</label>6  <input id="password" type="password" />7  <label><input type="checkbox" /> Remember me</label>8  <button type="submit">Sign in</button>9</form>10<a href="/forgot">Forgot your password?</a>

getByRole(role, { name }) looks in the accessibility tree (module 2) for an element with that role and name. It is the locator Playwright recommends first.

1page.getByRole('heading', { name: 'Sign in' })2page.getByRole('textbox', { name: 'Email' })3page.getByRole('checkbox', { name: 'Remember me' })4page.getByRole('button', { name: 'Sign in' })5page.getByRole('link', { name: 'Forgot your password?' })

• The name matches if it contains your text, ignoring case: { name: 'sign' } finds "Sign in".
• { exact: true } demands the whole name, with the same case.
• A regular expression works too: { name: /sign in/i }.
• Extra filters: level for headings ({ level: 1 }), checked, disabled, expanded, pressed, selected.

Regular expression

A text pattern written between slashes, like /sign in/i. The i means "ignore case".

page.locator('#root > div > form > button.btn-blue')

page.getByRole('button', { name: 'Sign in' })

• It survives redesigns. New classes, a new layout, a <div> swapped for a <section>: the button is still a button called "Sign in".
• It reads like the test plan. Anyone can tell what it clicks.
• It checks accessibility for free. If the button loses its name, screen-reader users lose it too, and the test fails.

getByText and getByLabel match parts of the text and ignore case unless you pass { exact: true }, just like name in getByRole.

Some elements have no good role or text, or their text changes (a number, a translated label). For those, developers can add an attribute only tests use, and getByTestId finds it.

1<span data-testid="cart-count">3</span>

1await expect(page.getByTestId('cart-count')).toHaveText('3')

page.locator(selector) accepts a CSS selector (the pattern language stylesheets use, like .price or ul > li) or an XPath (another pattern language for trees). They work, but they tie the test to how the page is built rather than what it shows.

1page.locator('.price')              // CSS: elements with class "price"2page.locator('xpath=//footer//a')   // XPath: links inside the footer

If a locator matches several elements when you click or fill it, Playwright refuses with a strict mode violation rather than guessing. Clicking the wrong one would make the test check the wrong thing.

1Error: strict mode violation: getByRole('button', { name: 'Add' })2resolved to 3 elements:3  1) <button>Add to cart</button> aka getByRole('button', …)4  2) <button>Add to cart</button> aka …5  3) <button>Add to wishlist</button> aka …

The fix is a more precise locator: a fuller name, exact: true, or narrowing to one product, which is the next module.

• Prefer, in order: getByRole, getByLabel, getByPlaceholder, getByText, then getByTestId.
• Names match part of the text, ignoring case; use exact: true or a regular expression to tighten.
• CSS and XPath tie tests to markup: a last resort.
• Actions need exactly one match, or they fail with a strict mode violation.

The shop’s product page lists items, each with the same "Add to cart" button. A locator for "the Add to cart button" matches all of them. You need to say which product’s button.

1<ul>2  <li>3    <h2>Red mug</h2> <p>£8</p>4    <button>Add to cart</button>5  </li>6  <li>7    <h2>Blue teapot</h2> <p>£24</p> <p>Sold out</p>8    <button disabled>Add to cart</button>9  </li>10  <li>11    <h2>Green bowl</h2> <p>£12</p>12    <button>Add to cart</button>13  </li>14</ul>

Every locator has the same getBy… methods as page. Calling one on a locator searches only inside it. Read it left to right: "in the list, the item…, in that item, the button…".

1const products = page.getByRole('listitem')2const mug = products.filter({ hasText: 'Red mug' })3await mug.getByRole('button', { name: 'Add to cart' }).click()

Chaining

Calling a locator method on another locator, to search inside it.

filter takes a locator that matches many elements and keeps only some of them. It does not change where it searches, only which matches count.

1const available = page2  .getByRole('listitem')3  .({ : 'Sold out' })4await expect(available).(2)

first(), last() and nth(index) pick by position. Positions start at 0, so nth(1) is the second. They are handy, and fragile: if the shop sorts products differently, nth(1) is now another product, and the test silently checks the wrong thing.

await page.getByRole('listitem').nth(2)  .getByRole('button').click()

await page.getByRole('listitem')  .filter({ hasText: 'Green bowl' })  .getByRole('button').click()

Pass an array to toHaveText to check every match, in order. It retries until all of them match, so it suits lists that load or change.

1await expect(page.getByRole('listitem').getByRole('heading'))2  .toHaveText(['Red mug', 'Blue teapot', 'Green bowl'])

a.or(b) matches elements that match either. It helps when the page can show one of two things, like a welcome banner or a cookie dialog. a.and(b) matches elements that match both, to add a condition.

1const signedIn = page.getByRole('heading', { name: 'Your account' })2const error = page.getByRole('alert')3// whichever appears first4await expect(signedIn.or(error)).toBeVisible()5
6const save = page.getByRole('button')7  .and(page.getByTitle('Save changes'))

• Chain getBy… on a locator to search inside it.
• filter keeps matches by text (hasText, hasNotText), by contents (has, hasNot), or visible.
• nth, first and last depend on order: prefer saying which one.
• toHaveText([...]) checks a whole list, in order; toHaveCount checks how many.
• or matches either locator; and matches both.

Actions are methods on a locator. They find the element, wait until it is ready, and then do what a person would do. Here is the shop’s sign-in, start to finish.

1test('signs in', async ({ page }) => {2  await page.goto('http://localhost:3000/sign-in')3  await page.getByLabel('Email').fill('sam@example.com')4  await page.getByLabel('Password').fill('correct-horse')5  await page.getByRole('button', { name: 'Sign in' }).click()6  await expect(page.getByRole('heading', { name: 'Your account' }))7    .toBeVisible()8})

• fill(text) clears the field and puts the text in, in one go.
• clear() empties a field.
• click() clicks the middle of the element; dblclick() double-clicks.
• click({ button: 'right' }) right-clicks; click({ modifiers: ['Shift'] }) holds a key.

localhost

Your own computer, as an address. localhost:3000 is an app running on it, on port 3000.

press(key) presses one key, or a combination joined with +. Key names follow the browser’s: Enter, Tab, Escape, ArrowDown, Backspace, letters like a.

1const box = page.getByPlaceholder('What needs to be done?')2await box.fill('Buy milk')3await box.press('Enter')            // submit4await box.press('ControlOrMeta+a')  // select all, on any OS5await page.keyboard.press('Escape') // to whatever has focus

1await page.getByLabel('Remember me').check()2await page.getByLabel('Gift wrap').uncheck()3await page.getByLabel('Country').selectOption('Spain')4await page.getByRole('radio', { name: 'Express delivery' }).check()5await page.getByLabel('Upload a photo')6  .setInputFiles('tests/files/mug.png')7await page.getByRole('link', { name: 'Help' }).hover()

• check() and uncheck() do nothing if the box is already that way, then make sure it ended up right.
• selectOption picks from a <select> by its value or its visible label.
• setInputFiles fills a file upload field without opening the file picker.
• hover() moves the mouse over, for menus that open on hover.

1await page.getByRole('', { name: 'Standard delivery' })2  .()3await page.getByLabel('I accept the terms').()4await page.getByRole('button', { name: 'Place order' }).()

A person cannot click a button that is hidden, still sliding in, greyed out, or under a popup. Before acting, Playwright waits until the element passes the same checks. This is auto-waiting, and it is why tests need no pauses.

Each action needs only the checks that apply: click needs all but editable, fill needs visible, enabled and editable. If they do not pass in time, the action fails and the error lists what it was waiting for.

Auto-waiting

Playwright waiting, on its own, until an element is ready for the action.

Actionability

The checks an element must pass before an action runs.

click({ force: true }) skips the checks. It makes a red test go green while hiding a real problem: if a user cannot click the button, neither should your test. Fix the cause instead.

await page.getByRole('button', { name: 'Pay' }).click({ force: true })

await page.getByRole('button', { name: 'Accept cookies' }).click()await page.getByRole('button', { name: 'Pay' }).click()

When a click leads to another page, you do not need to wait for the navigation yourself. The next locator waits for its element, on whatever page is showing. To check you arrived, assert on the address.

1await page.getByRole('link', { name: 'Checkout' }).click()2await expect(page).toHaveURL(/\/checkout$/)3await expect(page.getByRole('heading', { name: 'Checkout' }))4  .toBeVisible()

• fill, click, press, check, selectOption, setInputFiles, hover: actions on locators.
• Before acting, Playwright waits for the element to be visible, stable, enabled and uncovered.
• A timed-out action’s call log says what it was waiting for.
• Never force: true to get past a real problem.
• After a click that navigates, assert with toHaveURL and the next page’s content.

An assertion is the "check" part of a test. Playwright’s assertions on locators and pages are web-first: they look at the page, and if it is not right yet, they look again, over and over, until it is right or the time runs out (5 seconds by default). Pages change over time, so checks must wait for them.

const shown = await page.getByText('Added to cart').isVisible()expect(shown).toBe(true)

await expect(page.getByText('Added to cart')).toBeVisible()

On the left, isVisible() answers about this instant. If the message appears 100 milliseconds later, the test fails. On the right, the assertion waits for it.

Assertion

A check that a test makes. If it does not hold, the test fails.

Web-first assertion

An assertion that retries against the live page until it passes or times out.

Text matching normalises spaces and line breaks, so layout whitespace does not matter. A regular expression works wherever a string does: toHaveText(/£\d+/) matches "£8" or "£24".

Put .not before any assertion to flip it. It retries too: not.toBeVisible() waits until the element is gone. toBeHidden() means the same as not.toBeVisible(), and passes if the element does not exist at all.

1await page.getByRole('button', { name: 'Remove' }).click()2await expect(page.getByText('Red mug')).not.toBeVisible()3await expect(page.getByRole('listitem')).toHaveCount(0)

1const line = page.getByTestId('cart-line')2await expect(line).toHaveText('Red mug')      // A3await expect(line).toContainText('Red mug')   // B4await expect(line).toHaveText(/Red mug/)      // C

Each assertion waits up to 5 seconds by default. You can change it for one check, or for all checks in the config. Raise it only where the app is really slow, like an order that takes a while to confirm.

1// one check2await expect(page.getByText('Order confirmed'))3  .toBeVisible({ timeout: 15_000 })4
5// playwright.config.ts: every check6export default defineConfig({ expect: { timeout: 10_000 } })

You can also expect ordinary values: numbers, strings, objects. These generic assertions (toBe, toEqual, toContain, toBeGreaterThan…) check once, because a plain value cannot change. Use them for data you already have, and locator assertions for the page.

1const total = 8 + 242expect(total).toBe(32)3expect(['mug', 'teapot']).toContain('mug')4expect({ items: 2 }).toEqual({ items: 2 })

Normally the first failed assertion stops the test. expect.soft records the failure and lets the test carry on, so one run shows every problem on a page. The test is still marked failed at the end.

1await page.goto('http://localhost:3000/cart')2await expect.soft(page.getByTestId('subtotal')).toHaveText('£32')3await expect.soft(page.getByTestId('delivery')).toHaveText('£4')4await expect.soft(page.getByTestId('total')).toHaveText('£36')

Sometimes what you want to check is not on the page: a value from an API, say. expect.poll calls your function again and again until its result passes. expect(…).toPass() retries a whole block of code until none of it throws.

1// keep asking the API until the order is paid2await expect.poll(async () => {3  const res = await page.request.get('/api/orders/latest')4  return (await res.json()).status5}, { timeout: 10_000 }).toBe('paid')6
7// retry a few steps together8await expect(async () => {9  await page.getByRole('button', { name: 'Refresh' }).click()10  await expect(page.getByText('In stock'))11    .toBeVisible({ timeout: 1000 })12}).toPass({ timeout: 15_000 })

• Assertions on locators and pages retry until they pass or time out: always await them.
• toHaveText matches the whole text; toContainText a part; regular expressions match anywhere.
• .not flips any assertion, and still retries.
• Plain-value assertions check once: never read a value from the page and then toBe it.
• expect.soft keeps going; expect.poll and toPass retry custom code.

Playwright gives every test a fresh browser context: like a new private window, with no cookies, no saved data, nothing left from the test before. A test must never rely on another having run first. Tests can then run in any order, alone, or at the same time.

Browser context

An isolated browser session: its own cookies, storage and settings. Each test gets a new one.

test.describe(name, callback) puts tests in a named group. The group name is added in front of each test’s name in reports, and hooks inside apply only to the group.

1import { test, expect } from '@playwright/test'2
3test.describe('cart', () => {4  test('starts empty', async ({ page }) => {5    await page.goto('http://localhost:3000/cart')6    await expect(page.getByText('Your cart is empty')).toBeVisible()7  })8
9  test('shows an added item', async ({ page }) => {10    // …11  })12})

A hook is code Playwright runs at a set moment. beforeEach runs before every test in the file or group, which is the place for the shared "arrange" step.

1test.describe('to-do list', () => {2  test.beforeEach(async ({ page }) => {3    await page.goto('http://localhost:3000/todo')4  })5
6  test('adds an item', async ({ page }) => { /* … */ })7  test('marks an item done', async ({ page }) => { /* … */ })8})

A checkout test does many things. Wrapping parts in test.step gives them names in the report, the trace and UI mode, so a failure says "failed in: pay by card" instead of pointing at line 37.

1test('buys a mug', async ({ page }) => {2  await test.step('add to cart', async () => {3    await page.goto('http://localhost:3000/products')4    await page.getByRole('listitem').filter({ hasText: 'Red mug' })5      .getByRole('button', { name: 'Add to cart' }).click()6  })7  await test.step('check out', async () => {8    await page.getByRole('link', { name: 'Checkout' }).click()9    await page.getByRole('button', { name: 'Place order' }).click()10  })11  await expect(page.getByText('Thank you')).toBeVisible()12})

A tag is a label starting with @. Give tests tags, then run just those with --grep. A common use is a fast smoke set: a handful of tests that show the app basically works.

1test('signs in', { tag: '@smoke' }, async ({ page }) => { /* … */ })2
3test('changes the address', {4  tag: ['@account', '@slow'],5  annotation: { type: 'issue', description: 'Ticket 123' },6}, async ({ page }) => { /* … */ })

1npx playwright test --grep @smoke2npx playwright test --grep-invert @slow

test.describe.configure({ mode: 'serial' }) makes a group run in order and stop at the first failure. It exists for rare cases, but it couples tests: one failure hides the rest, and the group cannot be split across workers.

• Every test gets a fresh context; tests must not depend on each other.
• test.describe groups tests; hooks run code before and after them.
• test.step names parts of a test in reports and traces.
• skip, fixme, fail, slow and only change how a test is run or reported.
• Tags (@smoke) and --grep run chosen groups.

playwright.config.ts exports one object made with defineConfig. The top level says how the runner behaves: where tests are, how long they may take, how many run at once. The use section sets options for the browser in every test.

1import { defineConfig, devices } from '@playwright/test'2
3export default defineConfig({4  testDir: './tests',5  timeout: 30_000,6  retries: process.env.CI ? 2 : 0,7  reporter: 'html',8  use: {9    baseURL: 'http://localhost:3000',10    trace: 'on-first-retry',11  },12  projects: [13    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },14  ],15})

Environment variable

A named setting given to a program from outside, like CI=true.

CI

Continuous integration: a service that runs the tests on every change pushed to the code.

With baseURL set, page.goto('/cart') means http://localhost:3000/cart. Tests get shorter, and the same tests can run against another copy of the app (a staging site, say) by changing one setting.

await page.goto('http://localhost:3000/cart')

await page.goto('/cart')

1use: {2  baseURL: process.env.BASE_URL ?? 'http://localhost:3000',3},

Any use option can also be set for one file or group with test.use({ … }), at the top of the file or inside a describe.

1test.use({ locale: 'fr-FR' })2
3test('shows euros with a comma', async ({ page }) => {4  await page.goto('/products')5  await expect(page.getByText('8,00 €')).toBeVisible()6})

A project is a named set of options. Playwright runs every test once per project. The usual reason is browsers, but a project can be anything: a phone, a language, a signed-in user.

1projects: [2  { name: 'chromium', use: { ...devices['Desktop Chrome'] } },3  { name: 'firefox', use: { ...devices['Desktop Firefox'] } },4  { name: 'webkit', use: { ...devices['Desktop Safari'] } },5  { name: 'phone', use: { ...devices['Pixel 7'] } },6],

devices describes popular phones, tablets and desktops: screen size, pixel density, the browser’s user agent (the name it sends to servers), and whether it has touch. Playwright emulates them: a desktop browser pretends to be the phone.

1test.use({ ...devices['iPhone 13'] })2
3test('menu opens on a phone', async ({ page }) => {4  await page.goto('/')5  await page.getByRole('button', { name: 'Menu' }).tap()6  await expect(page.getByRole('navigation')).toBeVisible()7})

Emulation

One device imitating another: here, a desktop browser acting as a phone.

Viewport

The visible area of the page, in pixels.

Tests need the app running. webServer tells Playwright to start it, wait until its address answers, run the tests, and stop it afterwards.

1webServer: {2  command: 'npm run start',3  url: 'http://localhost:3000',4  reuseExistingServer: !process.env.CI,5  timeout: 120_000,6},

• command starts the app, as you would in a terminal.
• url is checked until it responds; then tests begin.
• reuseExistingServer uses an app you already started yourself, locally; in CI it always starts a fresh one.
• timeout is how long to wait for it to come up.

• Top-level options shape the runner; use options shape each test’s browser.
• baseURL lets tests write short addresses like /cart.
• test.use overrides options for a file or group.
• Projects run the suite once per setup: browsers, phones, languages.
• devices emulates phones and tablets; tap() needs touch.
• webServer starts the app for the run.

In async ({ page }) => …, page is a fixture: a ready-to-use thing Playwright prepares before the test and cleans up after it. The test only names what it needs; Playwright works out how to make it.

Fixture

Something a test asks for by name, set up before it and cleaned up after it.

A test that does not name page gets no tab, so no time is spent opening one. Fixtures can also depend on other fixtures: page needs context, which needs browser. Playwright builds the chain in order and takes it down in reverse.

Say many tests need the to-do app open with two items already in it. Make a fixture for that. test.extend returns a new test function that knows about your fixtures; tests import it instead of the built-in one.

1import { test as base } from '@playwright/test'2import type { Page } from '@playwright/test'3
4export const test = base.extend<{ todoPage: Page }>({5  todoPage: async ({ page }, use) => {6    await page.goto('/todo')7    const box = page.getByPlaceholder('What needs to be done?')8    for (const item of ['Buy milk', 'Walk the dog']) {9      await box.fill(item)10      await box.press('Enter')11    }12    await use(page)13  },14})15export { expect } from '@playwright/test'

Everything after await use(…) runs once the test finishes, whether it passed or failed. Setup and cleanup sit together in one place, which is the big advantage over a pair of hooks.

1type Account = { email: string; password: string }2
3export const test = base.extend<{ account: Account }>({4  account: async ({ request }, use, testInfo) => {5    const email = `shopper-${testInfo.testId}@example.com`6    const password = 'a-test-password'7    await request.post('/api/test/users', {8      data: { email, password },9    })10    await use({ email, password })11    await request.delete(`/api/test/users/${email}`)12  },13})

Teardown

Cleanup after a test: closing, deleting, resetting.

`testInfo`

Facts about the running test: its id, title, retry number, output folder.

Hooks are fine for a quick goto in one file. When setup is shared, has cleanup, or produces a value, use a fixture.

A fixture written as [fn, { auto: true }] runs for every test, even ones that do not name it. It suits things every test should get, like collecting browser errors.

1export const test = base.extend<{ noPageErrors: void }>({2  noPageErrors: [async ({ page }, use) => {3    const errors: Error[] = []4    page.on('pageerror', (error) => errors.push(error))5    await use()6    expect(errors).toEqual([])7  }, { auto: true }],8})