{"id":"l-tj-4-1","courseId":"testing-javascript","lang":"en","kind":"lesson","summary":"Set up Playwright for a Vite app, find elements with user-facing locators, and write web-first assertions that wait for the page instead of racing it.","html":"

Everything so far ran in Node, with jsdom pretending to be a browser. That covers most logic and most UI behaviour, but not all of it: real layout, real routing, the real server, a real CSS bug that hides the “Settle up” button on Safari. For the few flows where that matters, you drive a real browser. In 2026 the default tool for that in JavaScript is Playwright.

\n

Setting up

\n
Terminal
npm init playwright@latest
\n

The wizard adds @playwright/test, a playwright.config.ts, an example test and (optionally) a GitHub Actions workflow, and downloads the browsers. Point it at your Vite app and let it start the dev server for you:

\n
playwright.config.ts
import { defineConfig, devices } from '@playwright/test';\n\nexport default defineConfig({\n  testDir: './e2e',\n  fullyParallel: true,\n  retries: process.env.CI ? 2 : 0,\n  use: {\n    baseURL: 'http://localhost:5173',\n    trace: 'on-first-retry',\n  },\n  projects: [\n    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },\n    { name: 'webkit', use: { ...devices['Desktop Safari'] } },\n  ],\n  webServer: {\n    command: 'npm run dev',\n    url: 'http://localhost:5173',\n    reuseExistingServer: !process.env.CI,\n  },\n});
\n

webServer runs npm run dev, waits until the URL responds, runs the tests, then stops it. baseURL lets tests call page.goto('/groups/lisbon'). Run the suite with npx playwright test.

\n

A first end-to-end test

\n
e2e/settle-up.spec.ts
import { test, expect } from '@playwright/test';\n\ntest('adding an expense updates the balances', async ({ page }) => {\n  await page.goto('/groups/lisbon');\n\n  await page.getByLabel('Description').fill('Dinner');\n  await page.getByLabel('Amount').fill('30.00');\n  await page.getByRole('button', { name: 'Add expense' }).click();\n\n  const balances = page.getByRole('list', { name: 'Balances' });\n  await expect(balances.getByRole('listitem')).toHaveText([\n    'Ana is owed $15.00',\n    'Ben owes $15.00',\n  ]);\n});
\n

page is a fresh browser tab, given to the test as a fixture (more on those next lesson). The locators should look familiar: Playwright’s getByRole, getByLabel, getByText, getByPlaceholder, getByAltText, getByTitle and getByTestId follow the same priority idea as Testing Library, for the same reason.

\n

Locators are lazy and strict

\n

A locator is a description of how to find an element, not the element itself. page.getByRole('button', { name: 'Add expense' }) finds nothing until you act on it, and it finds it again every time, so a re-render that replaces the button doesn’t leave you holding a stale reference.

\n

Locators are also strict: if an action’s locator matches two elements, Playwright throws instead of clicking the first. Narrow with chaining and filter:

\n
TypeScript
const taxiRow = page.getByRole('listitem').filter({ hasText: 'Taxi' });\nawait taxiRow.getByRole('button', { name: 'Remove' }).click();
\n

That reads like the instruction you’d give a person (“remove the taxi row”), and it survives reordering. nth(2) and first() exist, but they break the moment the order changes; use them only when order is the point.

\n

Auto-waiting: actions

\n

Before click(), Playwright waits until the element is visible, stable (not mid-animation), enabled, and actually receives events (not covered by a spinner or a cookie banner). fill() waits for visible, enabled and editable. Then it acts. If the conditions never hold, the action fails after the timeout with a message saying which check failed.

\n

That is why end-to-end tests in Playwright rarely need explicit waits. The button that appears after the group loads is clicked when it appears.

\n
\n Top: click waits for visible, stable, receives events and enabled, then clicks. Bottom: toHaveText re-reads the element repeatedly until the text matches or 5 seconds pass.\n click()\n \n visible\n \n stable\n \n receives events\n \n enabled\n \n \n click\n toHaveText()\n \n \n \n \n re-read, no match\n \n matches\n gives up at 5 s\n \n
Actions wait until the element is ready; assertions retry until they pass
\n

Web-first assertions: assertions that wait

\n

The same idea applies to checking results. Playwright’s expect on a locator is asynchronous and retrying:

\n
TypeScript
await expect(page.getByRole('status')).toHaveText('Everyone is settled up');\nawait expect(page.getByRole('listitem')).toHaveCount(0);\nawait expect(page).toHaveURL(/\\/groups\\/lisbon\\/settled/);\nawait expect(page.getByRole('button', { name: 'Settle up' })).toBeDisabled();
\n

Each one re-checks the page until it matches, for up to 5 seconds by default. toHaveText with an array (as in the first test) checks every matched element’s text, in order, which is a compact way to assert a whole list.

\n\n\n

What belongs in an end-to-end test

\n

Because every test here starts a browser context, loads the app and talks to a real server, an end-to-end test costs seconds where a unit test costs milliseconds. Spend that budget on flows where the connection between pieces is the risk: signing in, adding an expense and seeing balances change, settling up, anything involving money or data loss. Don’t use it to check every validation message on the amount field; the component tests from section 3 already do that a hundred times faster. A healthy Splitwise-lite suite might have five to fifteen end-to-end tests and several hundred unit and component tests. If an end-to-end test fails, ask first whether a lower-level test should have caught it.

\n

The exercise asks you to pick the locator that will survive the next redesign. Next lesson: keeping tests independent of each other.

\n","toc":[{"id":"sec-1","text":"Setting up","level":2},{"id":"sec-2","text":"A first end-to-end test","level":2},{"id":"sec-3","text":"Locators are lazy and strict","level":2},{"id":"sec-4","text":"Auto-waiting: actions","level":2},{"id":"sec-5","text":"Web-first assertions: assertions that wait","level":2},{"id":"sec-6","text":"What belongs in an end-to-end test","level":2}],"takeaways":["Playwright drives real Chromium, Firefox and WebKit, and its webServer option starts your dev server before the tests run.","Prefer user-facing locators (getByRole, getByLabel, getByText) and narrow them with filter or chaining instead of CSS paths.","Actions such as click and fill auto-wait until the element is visible, stable, enabled and able to receive events.","Web-first assertions like await expect(locator).toHaveText(...) retry until they pass or time out (5 seconds by default); reading a value and asserting on it once does not."],"further":[{"title":"Playwright — Locators","url":"https://playwright.dev/docs/locators"},{"title":"Playwright — Assertions","url":"https://playwright.dev/docs/test-assertions"},{"title":"Playwright — Auto-waiting","url":"https://playwright.dev/docs/actionability"},{"title":"Playwright — Web server","url":"https://playwright.dev/docs/test-webserver"}],"quiz":[{"q":"

Which assertion keeps working when the balance updates 300 ms after the click?

","options":[{"text":"expect(await page.getByRole('status').textContent()).toBe('Ben owes $5.00')","why":"This reads the text once, immediately; if the update hasn’t landed yet, it fails. Nothing retries."},{"text":"await expect(page.getByRole('status')).toHaveText('Ben owes $5.00')","why":"Correct. A web-first assertion re-reads the element until the text matches or the timeout passes."},{"text":"await page.waitForTimeout(500); expect(await page.getByRole('status').isVisible()).toBe(true)","why":"The sleep is a guess, and the assertion doesn’t check the text at all."}],"answer":1},{"q":"

await page.getByRole('button', { name: 'Remove' }).click() fails with a strict mode violation. What does that mean?

","options":[{"text":"The button is disabled, so Playwright refuses to click.","why":"A disabled button makes the click wait and then time out; strict mode is about how many elements match."},{"text":"The test is running in a browser with strict security settings.","why":"Strict mode is a locator rule, not a browser setting."},{"text":"The locator matches more than one element, so Playwright won’t guess which to act on.","why":"Correct. Narrow it, for example page.getByRole('listitem').filter({ hasText: 'Taxi' }).getByRole('button', { name: 'Remove' })."}],"answer":2},{"q":"

What does Playwright check before it performs click() on a locator?

","options":[{"text":"That the element is visible, stable (not animating), enabled and not covered by another element.","why":"Correct. Those actionability checks are what make most explicit waits unnecessary."},{"text":"Only that the element exists in the DOM.","why":"Existing isn’t enough; a hidden or covered button can’t be clicked by a user, and Playwright waits for it to be clickable."},{"text":"Nothing; it clicks immediately and the test must wait beforehand.","why":"That’s how older tools worked; Playwright auto-waits for actions."}],"answer":0}],"exercise":{"kind":"choice","multiple":false,"options":["css-path","nth","role-filter","text-only","test-id"],"correct":["role-filter"],"title":"Pick the locator that survives a redesign","prompt":"

Splitwise-lite’s expense list renders like this:

\n
HTML
<ul aria-label=\"Expenses\" class=\"mt-4 space-y-2\">\n  <li class=\"row\">Dinner: $45.50 <button class=\"btn btn-ghost\">Remove</button></li>\n  <li class=\"row\">Taxi: $18.00 <button class=\"btn btn-ghost\" data-testid=\"remove-e2\">Remove</button></li>\n  <li class=\"row\">Museum: $24.00 <button class=\"btn btn-ghost\">Remove</button></li>\n</ul>
\n

Next sprint, a designer will switch the list to a card grid, change every class, and sort expenses by date instead of insertion order. Which locator for the Remove button of the Taxi expense is most likely to keep working, and to fail only if users really couldn’t remove the taxi?

\n","hints":["Rule out anything that depends on classes, DOM nesting or position: all three are about to change.","Prefer what a user perceives: the button’s role and name, scoped to the row that mentions Taxi."],"explanation":"

page.getByRole('listitem').filter({ hasText: 'Taxi' }).getByRole('button', { name: 'Remove' }) describes the target the way a person would: the Remove button in the taxi row. It doesn’t care about classes, nesting or order, so the redesign leaves it intact, and it fails if the row stops being a list item with an accessible Remove button, which is a real regression for keyboard and screen reader users. If the redesign uses cards that aren’t list items any more, the test fails loudly and points at a genuine accessibility change, which is worth a conversation. The CSS path and nth(1) break on the first class change or re-sort; the test id survives restyling but proves nothing about what users can see or reach, and only one row has it.

\n","checkLabels":{},"optionText":{"css-path":{"text":"page.locator('ul.space-y-2 > li.row:nth-child(2) > button.btn-ghost')","why":"It encodes classes, nesting and position, all of which the redesign changes, so it breaks even though removing the taxi still works."},"nth":{"text":"page.getByRole('button', { name: 'Remove' }).nth(1)","why":"It relies on the taxi being second. After sorting by date it would silently click a different expense’s Remove button, which is worse than failing."},"role-filter":{"text":"page.getByRole('listitem').filter({ hasText: 'Taxi' }).getByRole('button', { name: 'Remove' })","why":"Correct. It finds the button by role and name inside the row that mentions Taxi, so classes, layout and order can change freely."},"text-only":{"text":"page.getByText('Remove')","why":"It matches three buttons, so any action on it fails with a strict mode violation, and it says nothing about which expense you meant."},"test-id":{"text":"page.getByTestId('remove-e2')","why":"It survives restyling, but test ids are invisible to users and the last resort: the button could lose its label or be hidden from assistive tech and this would still pass."}}},"words":713,"readMinutes":3}