Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Playwright is a browser-automation library and end-to-end test runner for web applications. It drives Chromium, Firefox and WebKit through one API, while Playwright Test adds test organization, automatic waiting, assertions, tracing and parallel execution. A practical workflow is: write tests around user-visible outcomes, isolate every test, use resilient locators, rely on web-first assertions, generate a first draft with Codegen, and diagnose failures with traces.
What Playwright does
Playwright controls real browser engines so a test can navigate pages, fill forms, click controls and verify what a user sees. Its official overview lists Chromium, Firefox and WebKit support, with TypeScript, Python, .NET and Java APIs.
Keep two layers separate in your mental model:
- Playwright browser automation: the API that launches a browser, creates contexts and pages, and performs actions.
- Playwright Test: the integrated runner that discovers tests, provides fixtures, retries and parallelism, waits for conditions, records traces and reports results.
This distinction matters when choosing a language or integrating with another runner: the browser-control idea is shared, but runner features and workflows can differ by language.
Set up a TypeScript project
The following setup uses the Playwright Test runner. Run it from an empty project directory:
npm init playwright@latestChoose TypeScript when prompted, select the browsers your project needs, and allow the installer to add a test directory and configuration. A minimal test can then look like this:
import { test, expect } from '@playwright/test';
test('customer can sign in', async ({ page }) => {
await page.goto('https://example.com/login');
await page.getByRole('textbox', { name: 'Email' }).fill('[email protected]');
await page.getByLabel('Password').fill(process.env.TEST_PASSWORD ?? 'secret');
await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});Run the suite with:
npx playwright testUse the headed mode while developing:
npx playwright test --headedAfter a failure, open the HTML report:
npx playwright show-reportKeep credentials and other secrets in CI environment variables rather than committing them to a test file.
Design tests around user outcomes
Playwright’s best-practices guidance says automated tests should verify that application code works for end users and avoid implementation details users do not see or use. A useful test describes a task: a shopper can add an item, a member can reset a password, or an administrator can export a report.
Isolate every test
Each test should have its own local storage, session storage, cookies and data. Isolation prevents one test’s login state or database changes from contaminating another and makes failures reproducible. Create the data a test needs, remove or namespace it, and do not depend on the order in which tests happen to run.
Choose stable locators
Prefer locators that express how a user identifies a control:
getByRolefor buttons, links, headings, checkboxes and form controls.getByLabelfor labelled inputs.getByTextwhen visible text is the meaningful contract.- An explicit test ID when your team deliberately defines a testing contract.
Avoid long CSS or XPath chains. They couple a test to layout and implementation details that can change without changing user behavior.
// Prefer
await page.getByRole('button', { name: 'Save changes' }).click();
// Use a deliberate test contract when role or text is unsuitable
await page.getByTestId('invoice-download').click();Use auto-waiting and web-first assertions
Playwright waits for actionability before actions such as clicking. Its web-first assertions also wait and retry while the expected state is becoming true. This is safer than reading a momentary Boolean and asserting immediately.
Free tools Windows power users keep installed
One-click scans. No signup required.
await expect(page.getByRole('status')).toHaveText('Saved');
await expect(page.getByRole('dialog')).toBeVisible();
await expect(page).toHaveURL(//account/billing/);Do not add arbitrary sleeps to hide a race. If a page has a meaningful readiness signal, wait for that selector, URL, response or state instead. A short delay can be appropriate for a deliberately time-based UI, but it should not substitute for a condition your application can expose.
Generate a starting test with Codegen
Codegen records browser interactions and favors role, text and test-ID locators. Start it against a development page:
npx playwright codegen https://example.comPerform the workflow, then copy the generated actions into a test file. Treat the output as a discovery aid, not finished coverage: replace incidental clicks with business-level assertions, remove exploratory steps, parameterize data, and check that the selected locator remains meaningful when the UI changes.
Configure browsers, projects and parallel runs
A configuration can define projects for different engines or device profiles. Running the same user journey across Chromium, Firefox and WebKit exposes engine-specific behavior that a single browser run cannot.
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',
fullyParallel: true,
use: {
baseURL: 'http://127.0.0.1:3000',
trace: 'on-first-retry'
},
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } }
]
});Parallelism shortens feedback time but increases pressure on shared resources. Use isolated test data and make external dependencies deterministic before increasing worker counts. Run one project or one file while diagnosing a failure:
Rank #4
npx playwright test tests/login.spec.ts --project=firefox
npx playwright test tests/login.spec.ts --workers=1Investigate failures with traces
Tracing captures a timeline that can include DOM snapshots, network activity and related debugging context. The recommended configuration records a trace on the first retry, which preserves evidence for intermittent CI failures without tracing every test.
use: {
trace: 'on-first-retry'
}When a retry produces a trace, open it from the HTML report or with the Trace Viewer supplied by Playwright. Check the action immediately before the failure, the locator resolution, the page snapshot, console errors and network requests. Tracing every test can add performance overhead, so reserve always-on tracing for a focused diagnostic run.
A repeatable CI workflow
- Install the project dependencies and the browser binaries required by your configured projects.
- Start the application under test and wait for its health endpoint or a known page condition.
- Run the suite in headless mode with a fixed worker policy appropriate for the CI machine.
- Retain the HTML report and traces from retries as build artifacts.
- Re-run a failed test alone, then with one worker, to distinguish a product defect from shared-state or timing interference.
Retries should provide diagnostic evidence, not conceal a consistently failing test. A test that fails on every retry needs a product, data, locator or environment fix.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Common failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Locator resolves to nothing | Wrong role/name, changed copy or a control inside a frame | Inspect the rendered accessibility tree, use the correct role and name, or target the relevant frame. Add a deliberate test ID only when it is the team’s contract. |
| Click is intercepted or disabled | Overlay, animation or incomplete loading | Wait for the overlay to disappear or for the enabled state; assert the visible condition rather than adding a long sleep. |
| Assertion is flaky | Immediate Boolean read races the UI | Replace it with a web-first assertion such as toBeVisible, toHaveText or toHaveURL. |
| Works alone, fails in the suite | Shared cookies, storage or test data | Restore isolation, generate unique data and remove order dependencies. |
| Only one browser fails | Engine-specific behavior or unsupported assumption | Inspect that project’s trace and network log, then decide whether the application or the test needs a cross-browser fix. |
| CI timeout | Application not ready, slow dependency or overloaded workers | Wait for a real readiness signal, inspect the trace, stabilize dependencies and adjust workers before raising timeouts globally. |
Or skip the browser setup
If your immediate need is a clean image or PDF of a page rather than an interactive end-to-end test, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; bot checks, blank pages, timeouts, failed loads and cache hits are not billed. Its response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers.
One GET request returns PNG, JPEG, WebP or PDF. The API supports full-page and CSS-selector captures, dark mode, device presets, custom viewport and retina scale, PDF paper and page-range controls, custom CSS or JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, selectable caching TTLs, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage data and an OpenAPI specification.
Best Value
cURL (see the ScreenshotNeo documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);An MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for the free plan.
When Playwright is the right choice
Choose Playwright when you need repeatable, user-facing workflows with assertions, isolated state, cross-browser coverage and CI diagnostics. Keep tests focused on behavior a user can observe, use locators that express the interface contract, and preserve traces for failures. For static visual captures, use the ScreenshotNeo call instead of maintaining a browser harness.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsFrequently Asked Questions
Which languages does Playwright officially list?
The official overview lists TypeScript, Python, .NET and Java, alongside Chromium, Firefox and WebKit browser support.
Should every Playwright test record a trace?
No. The recommended pattern is tracing on the first retry; tracing every test can add performance overhead.
Are Codegen locators production-ready automatically?
No. Codegen is a starting point. Review its locators, remove exploratory actions and add assertions that represent the intended user outcome.
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.
