Playwright Test is the most complete way to write and run Playwright browser tests. Install the test runner and matching browser binaries, create tests with the built-in page fixture and web-first assertions, configure projects for the browsers or devices you support, then use reports and traces to diagnose failures. This guide takes you from an empty project to reliable local and CI test runs.
What Playwright testing includes
Playwright is a browser-automation library, while Playwright Test is its first-party test runner. The runner supplies fixtures such as page, parallel execution, reporters, retries and trace tooling. It is the practical default for end-to-end tests because test setup and failure evidence are integrated rather than assembled from separate packages.
Playwright can drive Chromium, Firefox and WebKit. Projects can also target branded Chrome or Edge installations and emulated device profiles. Choose the smallest matrix that represents your supported browsers; every additional browser increases installation time, execution time and CI storage.
The documentation is rolling rather than tied to one fixed package version. Browser binaries are version-coupled to Playwright, so rerun browser installation after upgrading the package. Check the official documentation for version-specific changes, especially component testing: the experimental React and Vue packages have been removed and existing users may need the migration path described there.
Recommended Free Tools
#1 Best Overall
Install Playwright and its browsers
1. Create or open a Node.js project
From your application or test repository, initialize a package if one does not already exist:
mkdir my-app-tests
cd my-app-tests
npm init -y2. Install Playwright Test
npm install -D @playwright/testThis installs the runner and its test API. Keep it in devDependencies so production deployments do not download test tooling.
3. Download browser binaries
Install the default browser set with:
npx playwright installYou can install only what your suite needs, for example:
npx playwright install chromium
npx playwright install webkitOn Linux CI machines, install operating-system dependencies as well:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutenpx playwright install --with-deps chromiumInstalling only required browsers saves download time and disk space. If a package update reports a missing executable, run the install command again; the new Playwright version may require different binaries.
Write your first test
Minimal navigation and assertion
Create tests/home.spec.js:
import { test, expect } from '@playwright/test';
test('home page has the expected title', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveTitle(/Example Domain/);
await expect(page.getByRole('heading', { name: 'Example Domain' })).toBeVisible();
});The { page } parameter requests a built-in fixture. Playwright creates an isolated page for that test, and the runner tears it down afterward. Locators such as getByRole, getByLabel and getByText describe how a user finds an element. Prefer them over fragile CSS or XPath selectors.
Test a user flow
import { test, expect } from '@playwright/test';
test('user can sign in', async ({ page }) => {
await page.goto('http://localhost:3000/login');
await page.getByLabel('Email').fill('qa@example.test');
await page.getByLabel('Password').fill('correct-password');
await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});Web-first assertions wait for the expected browser state and retry until the timeout, rather than checking once immediately. Avoid arbitrary sleeps such as waitForTimeout; wait for a locator, URL, response or application-specific condition instead.
Use a local development server
Configure the runner to start your app before tests. Create playwright.config.js:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
timeout: 30_000,
use: {
baseURL: 'http://127.0.0.1:3000',
trace: 'on-first-retry',
},
webServer: {
command: 'npm run dev',
url: 'http://127.0.0.1:3000',
reuseExistingServer: !process.env.CI,
},
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
],
});Adjust the command and URL to your application. A project is a named set of browser, device and context options. You can add branded Chrome or Edge channels and mobile device profiles when those environments matter to your users.
Run Playwright tests
Routine headless runs
npx playwright testThis runs every configured project. Select one project when narrowing a failure:
npx playwright test --project=chromiumRun one file, test or line
npx playwright test tests/home.spec.js
npx playwright test -g "user can sign in"
npx playwright test tests/home.spec.js:3See the browser
npx playwright test --headedHeaded mode opens the browser and is useful when navigation, focus, popups or responsive layout need visual inspection. It is slower and should not replace normal headless CI runs.
Use UI Mode
npx playwright test --uiUI Mode lets you browse tests, inspect steps, use watch mode and pick locators interactively. It is often faster for diagnosing a selector or setup problem than repeatedly editing and rerunning a command.
Run with a different worker count
npx playwright test --workers=2Test files run in parallel by default. Tests declared in one file run in declaration order unless you configure within-file parallelism. Increase workers only when the machine and test data can support it; reduce them on constrained CI runners or when a shared backend becomes a bottleneck.
Make tests independent and reliable
Isolate state
Workers are separate processes with separate browser instances. Parallel tests cannot safely share process globals, logged-in sessions or mutable records. Create distinct users or records per test (or per worker), reset state through an API or database fixture, and avoid depending on another test’s side effects.
Choose explicit waits
- Use locator assertions for visible or enabled UI state.
- Use
expect(page).toHaveURL()for navigation completion. - Use response or request waits when an API result controls the next assertion.
- Use a selector wait or a short, justified delay only for a real external condition that cannot be observed otherwise.
Control time and environment
Set a realistic test timeout and keep application timeouts separate. Configure timezone, locale, geolocation, permissions, viewport and color scheme in the project when your product behavior depends on them. Do not let a developer laptop’s timezone or installed fonts define expected output.
Capture useful failure evidence
The recommended CI setting is trace: 'on-first-retry'. Successful tests remain light, while the first retry retains actions, snapshots and related context for a failure. Open the generated trace with:
npx playwright show-trace path/to/trace.zipTrace Viewer exposes the action timeline and DOM snapshots. The lower-level browserContext.tracing API does not record test assertions; Playwright Test configuration captures the more complete test trace. See the API reference at playwright.dev/docs/api/class-tracing.html.
Read the HTML report
npx playwright show-reportThe HTML report groups passes, retries and failures by project and test. Keep report and trace artifacts from CI failures so a developer can reproduce the exact browser state instead of guessing from a stack trace.
Configure browser and device coverage
| Coverage choice | When it is useful | Trade-off |
|---|---|---|
| Chromium | Fast baseline and Chrome-family behavior | Does not reveal Firefox or WebKit differences |
| Firefox | Firefox-specific layout, standards and input behavior | Additional binary and runtime |
| WebKit | Safari-engine coverage on supported hosts | Additional installation and execution time |
| Branded Chrome or Edge | Validation against a vendor-installed browser | Requires that channel to be available on the runner |
| Emulated device | Viewport, touch, user agent and mobile-oriented flows | Emulation is not identical to physical hardware |
Run all projects for release confidence, or use a focused project during development. Keep the matrix in source control so local and CI coverage are explicit and repeatable.
Component testing with Playwright
The documented component-testing approach runs a normal Playwright end-to-end test against a small story gallery served by your development server. Components render in a real browser, so layout, events and interaction are exercised rather than simulated in a lightweight DOM.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteThe built-in mount() fixture drives component mounting. Because the experimental React and Vue component packages were removed, verify the current component-testing page and migration guidance against the version installed in your project before changing an existing setup.
Debugging failures: a practical checklist
“Executable doesn’t exist” or browser launch failure
Cause: browser binaries were not installed, or they belong to another Playwright version.
Fix: run npx playwright install (or the specific browser command). On Linux, add --with-deps. Repeat after every Playwright upgrade.
Timeout waiting for a locator
Cause: the locator is ambiguous, the page is on the wrong route, the element is inside a frame, or the application never reaches the expected state.
Free tools Windows power users keep installed
One-click scans. No signup required.
Fix: run the test in UI Mode or headed mode, inspect the trace snapshot, use a role- or label-based locator, assert the URL before the element, and target the correct frame when applicable. Do not “fix” an incorrect locator by adding a long sleep.
Works locally but fails in CI
Cause: missing system dependencies, different environment variables, insufficient resources, shared test data or timing assumptions.
Fix: install browsers and dependencies in the CI image, pin the same package lockfile, configure the required web server and secrets, isolate records per worker, and retain the first-retry trace. Lower workers if the runner is resource-constrained.
Flaky parallel failures
Cause: tests mutate the same account, file, port or backend record.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Fix: allocate unique data per test or worker and remove process-global state. If order matters, the tests are not independent; redesign the fixture rather than relying on declaration order.
Trace is missing assertions
Cause: tracing was started through the low-level browser-context API.
Fix: configure tracing in Playwright Test, preferably on-first-retry in CI, then inspect the resulting trace archive with Trace Viewer.
Performance, reliability and CI cost
- Install selectively: download only browsers represented in the job.
- Parallelize safely: file-level parallelism is the default; cap workers to the machine and backend capacity.
- Keep retries diagnostic: one retry with a trace gives evidence without tracing every successful test.
- Reuse setup carefully: shared authentication state can reduce login time, but never share mutable business data between tests.
- Split pipelines by purpose: run a fast Chromium smoke project on every change and the full browser matrix at the confidence level your release requires.
Measure suite duration and artifact volume in your own CI environment. Browser count, worker count, application startup time and trace retention dominate practical cost; there is no universal optimal setting.
Or skip the browser setup
If your immediate need is a clean image or PDF rather than an interactive assertion, ScreenshotNeo provides a website screenshot API and MCP server. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP tools—take_screenshot, get_page_info and capture_pdf—let Claude, Cursor and other MCP clients request captures.
One call returns an image or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the parameter reference and all options in the ScreenshotNeo documentation. A free account includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create the free ScreenshotNeo account.
FAQ
Is Playwright only for end-to-end testing?
No. Its documented component approach mounts components in a real browser through a story gallery, while the same runner can cover full user journeys.
Should I run every browser on every commit?
Not necessarily. Use a focused project for quick feedback and schedule the broader Chromium, Firefox and WebKit matrix where your release policy requires it.
Why did an upgrade break browser launching?
Playwright versions expect matching browser binaries. Reinstall the required browsers after updating the package.
What is the best first artifact for a CI failure?
Configure trace: 'on-first-retry', then open the trace archive in Trace Viewer to inspect actions and DOM snapshots.
Frequently Asked Questions
Can Playwright test APIs as well as pages?
Yes. Use Playwright’s request capabilities or page-driven flows to exercise HTTP behavior alongside browser assertions; keep API setup separate from UI expectations so failures remain diagnosable.
How do I run just one browser project?
Pass its configured name, for example npx playwright test --project=chromium.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Are emulated mobile tests equivalent to real phones?
No. Emulation changes browser settings such as viewport, touch and user agent, but it does not reproduce every hardware, network and operating-system condition.
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.
