To write and run a Playwright browser test, install @playwright/test and the browsers it uses, create a test with the test and expect APIs, then run npx playwright test. A good test performs a user-visible action and asserts the resulting state; Playwright’s locators and web-first assertions handle much of the waiting for you.
Install Playwright Test and its browsers
Follow the official installation guide for your project’s package manager and current setup. Keep the Playwright package and browser binaries aligned: when the package version changes, follow the browser installation or update instructions rather than assuming an older browser download will work.
For an npm project, the common setup is to install the test package, then install the browsers required by your configuration. In CI, the documented baseline is npm ci, npx playwright install --with-deps, and npx playwright test; the first command installs locked project dependencies, and the second installs browser binaries plus Linux system dependencies where applicable. See the browser installation guide and CI guide for details.
How do I write my first Playwright test?
Create a test file matching the project’s configured test-file pattern. Common names include *.spec.ts and *.test.ts. Import test and expect from @playwright/test:
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
import { test, expect } from '@playwright/test';
test('get started link', async ({ page }) => {
await page.goto('https://playwright.dev/');
await page.getByRole('link', { name: 'Get started' }).click();
await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});Here, test names the scenario, page is the test’s browser page, getByRole finds a link by its user-facing role and accessible name, and click() performs the action. The final line checks that the expected heading is visible. Playwright’s documentation describes tests as actions followed by assertions against expected state; see Writing tests.
Why use locators and web-first assertions?
Prefer locators that reflect how users identify interface elements, such as a role plus accessible name. Playwright waits for an element to be actionable before an interaction, and asynchronous assertions such as toBeVisible(), toHaveText(), toHaveURL(), and toHaveTitle() wait for the expected condition. This is generally more reliable than inserting a fixed sleep and hoping the page is ready. The Best Practices guide covers locator choices.
How is test state isolated?
The page fixture is provided for each test through a fresh BrowserContext. That isolation helps prevent cookies, local storage, or other browser state from one test affecting another. If a test depends on setup or shared data, make that setup explicit rather than relying on whichever test happened to run before it.
How do I run Playwright tests?
From the project directory, run the configured suite headlessly with:
npx playwright testPlaywright runs headless by default. These common options narrow or change the run; consult the running and debugging guide and command-line reference for the full CLI behavior.
| Goal | Command |
|---|---|
| Run one test file | npx playwright test tests/example.spec.ts |
| Run tests whose titles match text or a pattern | npx playwright test -g "get started link" |
| Run a configured browser project | npx playwright test --project=chromium |
| Watch a visible browser | npx playwright test --headed |
| Inspect and step through tests interactively | npx playwright test --ui |
| Open the Playwright Inspector for debugging | npx playwright test --debug |
| Open the HTML report after a run | npx playwright show-report |
Use the file path and project names that actually exist in your repository’s configuration. A command targeting a nonexistent file or project cannot run the selection you intended.
How do I run tests in different browsers?
Playwright projects are named configurations. They can target Chromium, Firefox, WebKit, branded browsers such as Chrome or Edge, and emulated tablet or mobile devices. Choose projects that reflect the browsers and devices your application supports; a suite does not have to run against every configuration on every local change. See Projects for configuration details.
A practical approach is to use one fast, representative project while developing, then run the broader set your team needs in CI or before release. Project selection is done with --project, for example npx playwright test --project=webkit, provided webkit is the project’s configured name.
How should I choose parallelism and retries?
Playwright runs test files in parallel by default; tests in a single file run in order unless parallel execution is configured. Locally, set worker use to fit the machine rather than assuming more workers always improve the run. For CI, Playwright’s guide recommends one worker as a stability and reproducibility baseline. Larger CI systems can distribute work across jobs with sharding. See Parallelism and the CI guide.
Retries can help identify intermittent failures, but they should not be used to make an unstable test look healthy. When a test fails, Playwright discards that worker and starts a new one for the retry. Treat a test that passes only on retry as a signal to investigate the test, application, or environment; see Retries.
How do I debug a failing test?
- Open UI mode: run
npx playwright test --uito inspect tests interactively and examine their steps. - Use the Inspector: run
npx playwright test --debugto debug with Playwright Inspector. - Read the HTML report: run
npx playwright show-reportto filter results and inspect failed tests and their steps. - Check browser launch logs on CI: run
DEBUG=pw:browser npx playwright testto print browser-launch debug logs when diagnosing launch problems.
For a failing assertion, check whether the locator matches the intended user-facing element and whether the asserted state is the behavior the application should reach. Prefer waiting for that state through a web-first assertion over adding a fixed delay.
Run Playwright in CI
A reliable baseline is to install the exact locked dependencies, install the matching browser binaries and operating-system dependencies, and then run the suite. In an npm-based CI job, the documented sequence is:
npm ci
npx playwright install --with-deps
npx playwright testThe CI guide shows GitHub Actions and other providers, as well as retaining the HTML report as an artifact. It advises against treating browser binary caching as the default: restoring a cache can take about as long as downloading, and Linux system dependencies cannot be cached in the same way. On Linux, headed browser runs require Xvfb; the Playwright Docker image and GitHub Action include it. For a large suite, consider sharding across jobs rather than increasing workers without regard to runner capacity.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If the goal is to capture a page image or PDF rather than verify interactive behavior, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. It does not replace Playwright for browser tests, but it can avoid installing and operating a local browser for captures. One cURL request looks like this; see the ScreenshotNeo documentation for parameters and response details:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://playwright.dev/ -o shot.webpScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Common problems and fixes
| Symptom | Likely cause | What to check |
|---|---|---|
| The test command finds no tests | The file does not match the configured test-file pattern, or the command is running from an unexpected directory. | Check the file name, test configuration, and project root; run a specific file path if needed. |
| A browser cannot launch, especially in CI | The browser binary or required operating-system dependencies are missing or mismatched. | Install browsers for the project’s Playwright version; on CI use npx playwright install --with-deps. For launch diagnostics, try DEBUG=pw:browser npx playwright test. |
| A headed Linux run fails | Headed browsers need a display server on Linux. | Use Xvfb in the CI environment; the Playwright Docker image and GitHub Action include it. |
| A test times out waiting for an element | The locator may be wrong, the expected UI may not appear, or the application may be slower or in an error state. | Inspect the page in UI mode or Inspector, verify the role and accessible name, and assert the intended state instead of adding an arbitrary sleep. |
| A retry passes after the first attempt fails | The test or environment may be intermittent. | Investigate the underlying failure; do not treat retry success alone as proof that the test is reliable. |
Frequently asked questions
Can Playwright run tests without a visible browser window?
Yes. Headless execution is the default for npx playwright test; use --headed when you need to watch the browser.
Do Playwright tests only work with Chromium?
No. Projects can be configured for Chromium, Firefox, WebKit, branded browsers, and emulated devices, depending on the project configuration and installed browsers.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
