🎯 What You Will Learn
Configure browser projects, run one or every engine, and investigate failures that appear only in a specific browser.
- Configure Chromium, Firefox, and WebKit projects
- Run all engines or one selected project
- Add device-specific settings without copying tests
- Debug browser-only failures with traces and focused commands
Test Browser Engines, Not Just Brands
Chromium, Firefox, and WebKit differ in layout, events, media, and platform behavior. Playwright projects run the same test suite with each configured engine.
Install Browser Binaries
Each Playwright version expects matching browser binaries. Install them after setup and again when a dependency update requires it.
npx playwright install
# Or install selected engines:
npx playwright install chromium firefox webkitConfigure Browser Projects
Use built-in desktop device profiles so each project receives suitable engine and browser settings.
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
],
});Run Every Configured Browser
The default test command executes every project unless the command or config narrows the selection.
npx playwright testFocus on One Browser
Use the project flag while developing a browser-specific fix.
npx playwright test --project=webkit
npx playwright test tests/checkout.spec.ts --project=firefox --headedKeep Behavior Tests Shared
Write tests around user behavior and allow projects to supply browser differences. Duplicating the whole test file per browser creates maintenance drift.
Project metadata: Use testInfo.project.name only when a real browser difference requires a narrow expectation or diagnostic.
Investigate a Browser-only Failure
Run the smallest failing test in the affected project with a trace. Compare layout, computed behavior, events, and network responses instead of assuming the engine is wrong.
npx playwright test tests/editor.spec.ts --project=webkit --trace=on --headedChoose Local and CI Coverage
Run the full browser set before merging user-critical changes. For very large suites, shard across jobs or keep focused smoke coverage per browser and deeper coverage in the primary engine.
| Suite | Suggested coverage |
|---|---|
| Critical journeys | All three engines |
| Feature-specific regression | Affected engines plus primary engine |
| Fast local loop | One project, then all before merge |
Recap
- Playwright projects reuse tests across browser engines.
- Install matching browser binaries after Playwright updates.
- Use --project to isolate a browser failure.
- Trace the smallest failing test before adding browser-specific logic.
Checkpoint: You have completed the workflow and have a repeatable reference for your next Playwright project.