Playwright Cheatsheet

Assertions

Use this Playwright reference while you build software engineering projects, review code for technical interview prep, or polish examples for a software engineer resume.

Locator assertions (auto-retry)

All expect(locator).* assertions poll until the condition holds or the timeout expires. They do not throw immediately.

Visibility & presence

await expect(locator).toBeVisible();
await expect(locator).toBeHidden();
await expect(locator).toBeAttached();               // in DOM, may be hidden
await expect(locator).toBeAttached({ attached: false }); // not in DOM

Count

await expect(locator).toHaveCount(5);

Text content

await expect(locator).toHaveText('Exact string');
await expect(locator).toHaveText(/partial regex/i);
await expect(locator).toContainText('substring');
await expect(locator).toContainText(/pattern/);

// Multiple elements — array of matchers
await expect(page.getByRole('listitem')).toHaveText(['One', 'Two', 'Three']);
await expect(page.getByRole('listitem')).toContainText(['A', 'B']);

Input values

await expect(locator).toHaveValue('current value');
await expect(locator).toHaveValue(/regex/);
await expect(locator).toHaveValues(['opt1', 'opt2']);  // multi-select
await expect(locator).toBeChecked();
await expect(locator).toBeChecked({ checked: false }); // explicitly unchecked

Form state

await expect(locator).toBeEnabled();
await expect(locator).toBeDisabled();
await expect(locator).toBeEditable();
await expect(locator).toBeFocused();

Attributes & class

await expect(locator).toHaveAttribute('href', 'https://example.com');
await expect(locator).toHaveAttribute('aria-label', /close/i);
await expect(locator).toHaveClass('active');
await expect(locator).toHaveClass(/btn-\w+/);
await expect(locator).toHaveClass(['btn', 'btn-primary']); // all present

CSS / style

await expect(locator).toHaveCSS('color', 'rgb(255, 0, 0)');
await expect(locator).toHaveCSS('display', 'none');

ID

await expect(locator).toHaveId('main-header');

Role

await expect(locator).toHaveRole('button');

Bounding box / screenshot (visual)

await expect(locator).toHaveScreenshot('button.png');
await expect(locator).toHaveScreenshot({ maxDiffPixels: 50 });
await expect(locator).toHaveScreenshot({ threshold: 0.2 });     // 0–1 pixel ratio

Page assertions

await expect(page).toHaveTitle('My App');
await expect(page).toHaveTitle(/dashboard/i);
await expect(page).toHaveURL('https://example.com/home');
await expect(page).toHaveURL(/\/home$/);
await expect(page).toHaveScreenshot('full-page.png');
await expect(page).toHaveScreenshot({ fullPage: true });

Response / API assertions

await expect(response).toBeOK();         // status 200–299

Negation

Prepend .not to any assertion:

await expect(locator).not.toBeVisible();
await expect(locator).not.toHaveText('Error');
await expect(page).not.toHaveURL(/login/);

Soft assertions

// Doesn't stop the test on failure — all failures collected at end
await expect.soft(locator).toHaveText('Expected');
await expect.soft(page).toHaveURL('/dashboard');

expect.poll — custom async predicate

await expect.poll(
  async () => (await page.request.get('/api/status')).json(),
  { intervals: [1000, 2000, 5000], timeout: 20_000 }
).toMatchObject({ ready: true });

expect.toPass — retry a block

await expect(async () => {
  const items = await page.getByRole('listitem').count();
  expect(items).toBeGreaterThan(4);
}).toPass({ timeout: 10_000 });

Assertion options

All expect(locator).* methods accept:

Option	Default	Description
`timeout`	`5000` ms	How long to retry
`message`	—	Custom failure message prepended to error

await expect(locator, 'nav should be visible after login')
  .toBeVisible({ timeout: 10_000 });

Built-in value matchers (non-async)

Used inside expect.poll, expect.toPass, or for plain JS values:

expect(value).toBe(exact);
expect(value).toEqual(deepEqual);
expect(value).toMatchObject({ key: 'val' });
expect(array).toContain('item');
expect(array).toHaveLength(3);
expect(value).toBeTruthy();
expect(value).toBeFalsy();
expect(value).toBeNull();
expect(value).toBeUndefined();
expect(value).toBeDefined();
expect(num).toBeGreaterThan(0);
expect(num).toBeLessThanOrEqual(100);
expect(str).toMatch(/regex/);
expect(fn).toThrow('message');

Snapshot assertions

// Text snapshot — stored in __snapshots__/
await expect(locator).toMatchAriaSnapshot();        // ARIA tree snapshot
expect(text).toMatchSnapshot('name.txt');           // stored text

// Screenshot snapshots
await expect(page).toHaveScreenshot('page.png');
await expect(locator).toHaveScreenshot('element.png');

// Update snapshots:
//   npx playwright test --update-snapshots