The default Playwright Test configuration file is playwright.config.ts (TypeScript) or playwright.config.js (JavaScript) in your current project directory. Playwright looks there automatically. Use --config or -c when the file has another name or location.
This guide explains where Playwright looks, what belongs in the file, documented defaults, a practical starter configuration, project setup, and the failures developers most often encounter.
What is the default Playwright config file?
Playwright Test recognizes these conventional filenames:
playwright.config.tsfor a TypeScript configuration.playwright.config.jsfor a JavaScript configuration.
The file is normally placed in the current directory from which you run Playwright. The configuration API describes testDir as defaulting to the configuration file’s directory. If both files exist, select the one you intend to use explicitly rather than relying on an ambiguous project layout.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
For a differently named file, pass its path on the command line:
npx playwright test --config=ci/playwright.config.ts
# The short form is also valid
npx playwright test -c ci/playwright.config.tsThe path may be relative to the directory where you run the command. This option is useful for separate local, CI, or browser-matrix configurations.
Where does Playwright look for the config?
Automatic lookup
Run npx playwright test from the directory containing playwright.config.ts or playwright.config.js. Playwright loads the conventional file and applies its settings to the test run. A common layout is:
project/
playwright.config.ts
tests/
home.spec.ts
package.jsonIf you invoke the command from another directory, the current working directory and the selected config path matter. Make the working directory explicit in CI, or always pass -c.
Recommended Free Tools
Explicit selection
Use -c when you have multiple configurations:
npx playwright test -c playwright.config.ts
npx playwright test -c configs/playwright.ci.config.tsKeep the file extension consistent with the language and module setup used by your project. A configuration can be valid code and still fail to load if the command points to the wrong file.
What belongs in a Playwright configuration?
Playwright separates test-runner options from browser-context options. Runner settings go at the top level. Settings that describe the browser context shared by tests go inside use.
Top-level runner settings
The official basic example includes testDir, fullyParallel, forbidOnly, retries, workers, reporter, use, projects, and webServer. These options control discovery, parallel scheduling, safety checks, retries, worker limits, reporting, projects, and application startup.
Rank #2
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Shared browser settings in use
Put browser-context behavior such as baseURL inside use, not beside it. This distinction prevents a frequent configuration error: a test-runner option accidentally placed where a context option belongs, or vice versa.
Free tools Windows power users keep installed
One-click scans. No signup required.
A basic TypeScript configuration
This is a starting example, not a universal preset. Adjust browser coverage, CI capacity, retries, and server startup to your repository.
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
use: {
baseURL: 'http://127.0.0.1:3000',
trace: 'on-first-retry',
},
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
],
webServer: {
command: 'npm run start',
url: 'http://127.0.0.1:3000',
reuseExistingServer: !process.env.CI,
},
});The example chooses a tests directory, full parallel execution, a CI-only check for accidental test.only, two CI retries, one CI worker, an HTML reporter, a local base URL, a trace on the first retry, a Chromium project, and a local server. Those are example choices; a small project, a cross-browser suite, or a resource-constrained runner may need different values.
The equivalent JavaScript file
If your project uses JavaScript, create playwright.config.js with the same structure:
const { defineConfig, devices } = require('@playwright/test');
module.exports = defineConfig({
testDir: './tests',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
use: {
baseURL: 'http://127.0.0.1:3000',
trace: 'on-first-retry',
},
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
],
webServer: {
command: 'npm run start',
url: 'http://127.0.0.1:3000',
reuseExistingServer: !process.env.CI,
},
});Use either the TypeScript or JavaScript file as your project’s convention. Do not maintain two active defaults unless you deliberately select one with -c.
Documented defaults you should know
Test discovery
By default, Playwright runs files matching .*(test|spec).(js|ts|mjs). A file such as tests/login.spec.ts matches. A file named login.ts does not match unless you change discovery settings or rename it.
Test timeout
Each test has a 30-second timeout by default. The timeout includes the test function, fixtures, and beforeEach hooks. Set a larger or smaller value when an application genuinely needs it, but avoid masking a slow or stuck test with an arbitrary increase.
Retries
Failed tests are not retried by default. Configure retries globally or per project. The example enables two retries only when the CI environment variable is set; local runs remain at zero retries so failures are visible immediately.
Workers
The API documentation says the default worker count is half the logical CPU cores. Worker limits affect parallel execution and may need adjustment to the memory and CPU available in CI.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Reporter
The documented default reporter is dot when the CI environment variable is set and list otherwise. The sample explicitly selects the HTML reporter so you can open a browsable report after a run.
Async expectation timeout
The API reference documents a default timeout of 5,000 milliseconds for asynchronous expect matchers. This is separate from the 30-second test timeout: increasing one does not automatically change the other.
Using baseURL and webServer correctly
baseURL resolves relative navigation
With use.baseURL set, a test can navigate with a relative path:
import { test, expect } from '@playwright/test';
test('home page loads', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveTitle(/Home/);
});The browser resolves / against the configured base URL. Keep this setting under use.
webServer starts and waits for the app
webServer runs a command and waits for the configured URL to become ready. It is useful when tests depend on a local development or preview server. It does not replace baseURL: webServer handles process startup and readiness, while baseURL supplies the URL used by test navigation. They are complementary.
If your CI pipeline starts the application elsewhere, omit webServer and set baseURL to that already-running service.
Projects for browsers, devices, and environments
A project is a named configuration variant. Projects let you run the same tests across browsers, devices, environments, or other settings. Each project can have its own browser or device profile, base URL, retries, and timeout.
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
{
name: 'mobile-chromium',
use: { ...devices['Pixel 5'] },
},
]Choose projects based on the coverage you need and the capacity of the runner. More projects increase coverage but also increase run time and resource use. Run one project by name when diagnosing a failure:
npx playwright test --project=chromiumHow to create and verify the file
- Create
playwright.config.tsorplaywright.config.jsin the directory from which you run Playwright. - Export the configuration using the syntax appropriate to your project.
- Place runner settings at the top level and browser-context settings inside
use. - Put tests in the configured
testDir, or rely on the config-file directory if you have not set one. - Run
npx playwright test. If the file is elsewhere, runnpx playwright test -c path/to/file. - Confirm that the expected test files match the default naming pattern and that any configured
webServerURL becomes reachable.
Troubleshooting common configuration failures
“No tests found”
Check the current directory, the selected -c path, and the configured testDir. Then verify that filenames end in .test.js, .spec.js, .test.ts, .spec.ts, or the documented .mjs variants.
Playwright loads the wrong configuration
Multiple conventional files or a command run from the wrong directory can cause confusion. Pass an explicit path with --config and make that path part of the CI command.
“Cannot use import statement” or export errors
Use the TypeScript example only with a TypeScript-compatible Playwright setup and use the JavaScript export style expected by your project. Do not mix export default and module.exports in one file.
Relative URLs fail
Set use.baseURL. A webServer entry alone starts a process but does not tell page.goto how to resolve a relative path.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows 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 reinstallBest Value
- These are the words in Charlotte's web, high in the barn
- Her spiderweb tells of her feelings for a little pig named Wilbur, as well as the feelings of a little girl named Fern … who loves Wilbur, too
- Their love has been shared by millions of readers
The server never becomes ready
Run the server command manually, verify that it binds to the URL in webServer.url, and check that the port is available. If CI starts the app independently, remove webServer and point baseURL at the existing service.
Runs are too slow or unstable in CI
Review the number of projects and workers against available CPU and memory. The documented default worker count is half the logical CPU cores; an explicit CI limit such as one worker can reduce contention. Retries can help expose intermittent failures, but they do not fix the underlying cause.
HTML output is missing
The default reporter differs between CI and non-CI environments. Select reporter: 'html' when you require an HTML report regardless of environment.
Or skip the browser setup
If your goal is to obtain a clean website image rather than build an end-to-end browser test, ScreenshotNeo provides a single HTTP request. Its API accepts 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 and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing result in X-Page-Verdict and X-Billed headers.
See the ScreenshotNeo documentation for all options, including full-page and selector captures, dark mode, device and viewport controls, retina scale, PDF output, custom CSS and JavaScript, clicks, waits, blocking rules, headers, cookies, user agents, authorization, timezone, geolocation, transparency, resizing, TTL caching, signed image links, asynchronous webhooks, bulk capture, usage, and the OpenAPI specification.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo also has an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
FAQ
Can I name the file something other than playwright.config.ts?
Yes. Pass the alternative path with --config or -c.
Is baseURL the same as webServer?
No. baseURL resolves relative navigation; webServer starts a process and waits for its URL.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Are failed tests retried automatically?
No. Retries are zero by default and must be configured.
What should I recheck after upgrading Playwright?
Verify defaults and option behavior against the documentation for the Playwright version installed in your project, because the documentation pages are rolling and the cited defaults are not tied to a publication year.
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.
