🎯 What You Will Learn
Understand Playwright's browser model, supported engines, isolation, auto-waiting, and where it fits beside Selenium and unit tests.
- Explain what Playwright automates
- Choose between CLI automation, Playwright Test, and the library
- Recognize where end-to-end tests add value
- Avoid using browser automation for the wrong problems
The Browser Automation Problem
Modern web applications change after clicks, network responses, animations, and client-side rendering. A useful automation tool must control the browser while understanding those changing states.
Playwright provides one API for Chromium, Firefox, and WebKit, so the same workflow can exercise the major browser engines.
The Three Playwright Shapes
Playwright CLI is ideal for direct terminal and agent workflows. Playwright Test adds assertions, isolation, projects, retries, and reports. The Playwright library is the lower-level choice for custom Node.js programs.
| Choice | Best fit |
|---|---|
| CLI | Exploration, debugging, scripted browser work, and agents |
| Test | Repeatable end-to-end tests committed with an application |
| Library | Custom browser services and specialized automation programs |
See Playwright Control a Browser
The fastest way to understand the tool is to open a page and inspect the browser's accessible structure.
- Point PWCLI at the bundled wrapper or use playwright-cli globally.
- Open the official website in headed mode.
- Take a snapshot before trying to interact.
PWCLI="$HOME/.codex/skills/playwright/scripts/playwright_cli.sh"
"$PWCLI" -s=intro open https://playwright.dev --headed
"$PWCLI" -s=intro snapshotWhy Auto-waiting Matters
Before a click, Playwright checks that one element matches, is visible and stable, receives events, and is enabled. This removes many hand-written delays.
Auto-waiting is not magic: a wrong locator, permanent overlay, or disabled control still fails with a useful timeout.
Better default: Wait for user-visible state or use a web-first assertion instead of adding arbitrary sleep calls.
Isolation Makes Runs Repeatable
Playwright Test creates isolated browser contexts. Each context behaves like a clean profile with its own cookies and local storage, which prevents one test from silently changing another.
import { test, expect } from '@playwright/test';
test('home page loads', async ({ page }) => {
await page.goto('https://playwright.dev/');
await expect(page).toHaveTitle(/Playwright/);
});Good Playwright Use Cases
Use Playwright for journeys that need a real browser: signing in, completing checkout, validating navigation, testing responsive layouts, capturing screenshots, or reproducing a frontend failure.
- Choose a user-critical journey.
- Keep the test independent from other tests.
- Assert the result a user would actually observe.
When Not to Reach for a Browser
A browser is slower than a unit test or direct API test. Pure calculations, small validation functions, and backend contract checks usually belong lower in the test pyramid.
Keep the suite focused: Do not reproduce every unit-test branch through the UI. Reserve browser coverage for integration boundaries and meaningful user behavior.
Choose Your Starting Path
Start with the CLI when you need to explore a page or automate a one-off workflow. Start with Playwright Test when the behavior must run repeatedly in local development and CI.
# Direct browser automation
"$PWCLI" open https://example.com --headed
# Committed end-to-end test project
npm init playwright@latest
npx playwright testRecap
- Playwright controls Chromium, Firefox, and WebKit.
- CLI, Test, and Library workflows solve different problems.
- Auto-waiting and isolated contexts improve reliability.
- Browser tests should cover important user journeys, not every code branch.
Checkpoint: You have completed the workflow and have a repeatable reference for your next Playwright project.