Core API Cheat Sheet
Playwright's API centers on three objects: Page, representing a single browser tab you call goto(), locator(), and screenshot() on; Locator, a lazy, auto-retrying reference to one or more elements returned by methods like getByRole(); and expect(), Playwright Test's assertion library extended with web-first, auto-retrying matchers like toBeVisible() and toHaveText(). Almost every test follows the same shape: navigate with page.goto(), find elements with locators, act on them, then assert the resulting state with expect().
Cricket analogy: Page, Locator, and expect() are like the three basics every cricketer learns first, batting stance, grip, and shot selection, the fundamental building blocks every match situation is built from.
Common Locator Methods
The most-used locator methods, in priority order, are getByRole(role, { name }) for interactive elements identified by their accessible role and name, getByLabel(text) for form fields, getByPlaceholder(text) for inputs identified by placeholder, getByText(text) for visible text content, and getByTestId(id) as a fallback tied to a data-testid attribute. Locators can be chained and filtered: .filter({ hasText: 'Delete' }) narrows a list to matching items, and .nth(0) or .first()/.last() select by position when multiple elements match, though positional selection should be a last resort since it's brittle to list reordering.
Cricket analogy: Chaining .filter({hasText}) on a locator is like a scorer filtering the innings list down to 'only sixes hit', narrowing a broad list to exactly the relevant entries.
// Locator cheat sheet
page.getByRole('button', { name: 'Sign up' });
page.getByLabel('Email');
page.getByPlaceholder('Search products');
page.getByText('Order confirmed');
page.getByTestId('cart-total');
// Filtering and positional selection
page.getByRole('listitem').filter({ hasText: 'Wireless Mouse' });
page.getByRole('row').nth(2);
page.getByRole('button').first();Assertions and Actions
Frequently used assertions include toBeVisible(), toBeEnabled(), toHaveText(), toHaveValue(), toHaveCount(), and toHaveURL(), all of which auto-retry until they pass or time out, making them safe to use immediately after an action without an explicit wait. Common actions include click(), fill(), check(), selectOption(), and hover(), each of which auto-waits for the target to be visible, stable, and receive events before Playwright attempts the interaction, and press() for simulating individual keyboard input like Enter or Tab.
Cricket analogy: toHaveCount() checking a list's length is like a scorer confirming the exact number of fours hit in an innings before finalizing the scorecard summary.
Assertion quick list: toBeVisible / toBeHidden, toBeEnabled / toBeDisabled, toHaveText / toContainText, toHaveValue, toHaveCount, toHaveURL, toHaveTitle, toHaveScreenshot (visual comparison). All are auto-retrying when used with expect(locator).
Configuration and CLI Commands
The most common CLI commands are npx playwright test to run the suite, npx playwright test --headed to watch the browser visually, npx playwright test --debug to open the Inspector, npx playwright codegen <url> to record actions into generated code, and npx playwright show-report to open the last HTML report. Key config options in playwright.config.ts include testDir, timeout (per-test), expect.timeout (per-assertion), retries, workers, and use.trace/screenshot/video for controlling what debugging artifacts are captured on failure.
Cricket analogy: npx playwright test --headed watching the run live is like choosing to watch a match live at the stadium rather than only reading the scorecard afterward.
Per-test timeout (the top-level timeout option) and per-assertion timeout (expect.timeout) are different settings. A long-running test can still fail fast on an individual assertion if expect.timeout is too low, even though the overall test timeout hasn't been reached, so tune both deliberately.
- Core objects: Page for navigation, Locator for finding elements, expect() for web-first assertions.
- Locator priority: getByRole, getByLabel, getByPlaceholder, getByText, then getByTestId as fallback.
- Use .filter() and .nth()/.first()/.last() carefully; positional selectors are brittle.
- Common assertions (toBeVisible, toHaveText, toHaveCount) auto-retry until pass or timeout.
- Actions (click, fill, check, selectOption) auto-wait for actionability before interacting.
- Key CLI commands: test, --headed, --debug, codegen, show-report.
- Config knobs: testDir, timeout, expect.timeout, retries, workers, use.trace/screenshot/video.
Practice what you learned
1. Which three objects form the core of most Playwright tests?
2. What is the recommended locator priority order?
3. Why should .nth() and .first() be used sparingly?
4. What does npx playwright codegen do?
5. What is the difference between timeout and expect.timeout in playwright.config.ts?
Was this page helpful?
You May Also Like
Playwright Best Practices
A practical guide to writing reliable, maintainable Playwright tests by choosing the right locators, avoiding flaky waits, and keeping tests isolated and fast.
Playwright Interview Questions
The core Playwright concepts and tricky topics that come up most often in QA and SDET interviews, from auto-waiting to network interception.
Building an E2E Test Suite for a Real App
A practical walkthrough of planning, structuring, and running a Playwright end-to-end test suite for a production application, from config to CI.