Playwright 13 ๐ญ Configuration โ playwright.config.ts and baseURL setup
The playwright.config.ts file is the control surface for the test run. It declares the projects (Chromium, Firefox, WebKit), the baseURL, the retries, the reporters, the timeouts, and the webServer that starts the application before the tests run. The baseURL is the setting that makes page.goto("/login") resolve against the application’s origin, and it is the one option every project needs.
This chapter covers the config file structure, the baseURL and the webServer that starts the app, and the per-project configuration that runs the same tests on multiple browsers and environments. The sections that follow walk through the config shape, the base URL and server, and the projects that define the cross-browser matrix.
Key point: playwright.config.ts exports defineConfig({ ... }) with a top-level use block for the shared options and a projects array for the per-browser overrides; use.baseURL makes relative navigation work, and webServer starts the application before the tests run.
a. The config structure and the use block
The config exports a defineConfig object. The top-level optionsโtestDir, fullyParallel, forbidOnly, retries, reporterโapply to the whole run. The use block holds the options that are passed to every test: baseURL, trace, screenshot, video, viewport, and the browser launch options.
// playwright.config.ts
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://localhost:3000",
trace: "on-first-retry",
screenshot: "only-on-failure",
},
projects: [
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
],
});
The forbidOnly option is the CI guard against a committed test.only. The retries option is the retry count for a flaky test, and the workers option is the parallelism; the CI setting of 1 runs the tests serially, which is the safer default for a suite that shares a database. The reporter option selects the output format, and the trace option records the trace for a failed test.
The use block’s trace option is the debugging artifact. The "on-first-retry" value records a trace for the first retry of a failed test, which is the trace that shows why the test failed. The "on" value records every test, and the "retain-on-failure" value records every test and keeps the trace only for the failures.
b. The baseURL and the webServer
The use.baseURL is the origin that page.goto resolves relative paths against. The test writes page.goto("/login"), and the config decides whether that resolves to localhost, staging, or production.
use: {
baseURL: "http://localhost:3000",
},
The webServer option starts the application before the tests run and stops it after. It is the replacement for a separate terminal that runs npm run dev while the tests run, and it is the pattern for a CI job that has no separate server.
webServer: {
command: "npm run start",
url: "http://localhost:3000",
reuseExistingServer: !process.env.CI,
timeout: 120_000,
},
The command is the process that starts the server, and the url is the address Playwright polls until it responds. The reuseExistingServer option uses a server that is already running instead of starting a new one, which is the local development pattern; the CI setting starts a fresh server. The timeout is the wait for the server to be ready.
The baseURL and the webServer.url should match. A mismatch produces a test that starts the server on one port and navigates to another, and the failure is a connection refused that looks like a test bug.
c. The projects and the cross-browser matrix
The projects array is the cross-browser matrix. Each project has a name and a use block that overrides the top-level options for that project. The devices export provides the presets for the common browsers and viewports.
projects: [
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
{ name: "firefox", use: { ...devices["Desktop Firefox"] } },
{ name: "webkit", use: { ...devices["Desktop Safari"] } },
{ name: "mobile", use: { ...devices["iPhone 15"] } },
],
The same test file runs once per project. The --project=chromium flag runs one project, and the absence of the flag runs all of them. The devices presets set the viewport, the userAgent, the deviceScaleFactor, and the isMobile flag, which is why a mobile project runs the same test as a desktop one with a different configuration.
The storageState option is the authentication reuse from the earlier chapter, and it is set per project. A project that tests the admin role points at the admin state file, and a project that tests the user role points at the user state file.
{
name: "admin",
use: {
...devices["Desktop Chrome"],
storageState: "playwright/.auth/admin.json",
},
},
The dependencies option orders the projects. A project that lists setup in its dependencies runs after the setup project, which is the pattern for the authentication state file.
The environment-specific configuration uses the process.env values. A CI job that runs against staging sets the BASE_URL environment variable, and the config reads it.
use: {
baseURL: process.env.BASE_URL ?? "http://localhost:3000",
},
The fallback is the local value, and the environment variable is the override. The test does not change between the environments; only the config does.
Complete Example Session
// ============================================
// PART 1: THE CONFIG
// ============================================
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"], ["list"]],
use: {
baseURL: process.env.BASE_URL ?? "http://localhost:3000",
trace: "on-first-retry",
screenshot: "only-on-failure",
},
webServer: {
command: "npm run start",
url: "http://localhost:3000",
reuseExistingServer: !process.env.CI,
},
projects: [
{ name: "setup", testMatch: /.*\.setup\.ts/ },
{
name: "chromium",
use: { ...devices["Desktop Chrome"], storageState: "playwright/.auth/user.json" },
dependencies: ["setup"],
},
{
name: "firefox",
use: { ...devices["Desktop Firefox"], storageState: "playwright/.auth/user.json" },
dependencies: ["setup"],
},
{
name: "webkit",
use: { ...devices["Desktop Safari"], storageState: "playwright/.auth/user.json" },
dependencies: ["setup"],
},
{
name: "mobile",
use: { ...devices["iPhone 15"] },
},
],
});
// ============================================
// PART 2: THE TEST (BASE URL)
// ============================================
// tests/login.spec.ts
import { test, expect } from "@playwright/test";
test("navigates to the dashboard", async ({ page }) => {
await page.goto("/dashboard"); // resolves against baseURL
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
});
// ============================================
// PART 3: THE ENVIRONMENT OVERRIDE
// ============================================
// CI against staging
// BASE_URL=https://staging.example.com npx playwright test
The parts covered the config with the use block, the webServer, the projects matrix, the relative navigation, and the environment override.
Quick Reference
Top-Level Options
| Option | Purpose |
|---|---|
testDir | Test file location |
fullyParallel | Run tests in parallel |
forbidOnly | Fail on test.only in CI |
retries | Retry count |
workers | Parallelism |
reporter | Output format |
use Options
| Option | Purpose |
|---|---|
baseURL | Relative navigation base |
trace | Trace recording |
screenshot | Screenshot on failure |
video | Video recording |
storageState | Auth state file |
Projects
| Project | Use |
|---|---|
chromium | Desktop Chrome |
firefox | Desktop Firefox |
webkit | Desktop Safari |
mobile | iPhone preset |
Best Practices
โ Do This:
// Set baseURL from the environment
baseURL: process.env.BASE_URL ?? "http://localhost:3000" // โ
// Start the server with webServer
webServer: { command: "npm run start", url: "http://localhost:3000" } // โ
// Order the setup project
dependencies: ["setup"] // โ
โ Don’t Do This:
// Hard-code the URL in the test
page.goto("http://localhost:3000/login"); // โ
// Run the server manually in CI
// (use webServer instead) // โ
// Use a different port for baseURL and webServer.url
baseURL: "http://localhost:3001" // webServer on 3000 // โ
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
page.goto fails | No baseURL | Set use.baseURL |
| Server not running | No webServer | Add the config block |
| CI hits localhost | No environment override | BASE_URL |
| Setup runs out of order | No dependencies | Add the array |
Real-World Examples
1. Base URL
use: { baseURL: "http://localhost:3000" }
2. Environment override
baseURL: process.env.BASE_URL ?? "http://localhost:3000"
3. Web server
webServer: { command: "npm run start", url: "http://localhost:3000" }
4. Cross-browser
projects: [{ name: "chromium" }, { name: "firefox" }, { name: "webkit" }]
5. Mobile project
{ name: "mobile", use: { ...devices["iPhone 15"] } }
6. Storage state
use: { storageState: "playwright/.auth/user.json" }
7. Trace on first retry
use: { trace: "on-first-retry" }
8. CI retries
retries: process.env.CI ? 2 : 0
9. Forbid only
forbidOnly: !!process.env.CI
10. Dependencies
dependencies: ["setup"]
Visual
The Config Structure
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ defineConfig({ โ
โ testDir, retries, workers, reporter โ
โ use: { baseURL, trace, screenshot } โ
โ webServer: { command, url } โ
โ projects: [ ... ] โ
โ }) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
The Base URL
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ baseURL: "http://localhost:3000" โ
โ โ
โ page.goto("/login") โ http://localhost:3000/login โ
โ โ
โ BASE_URL=https://staging... โ staging URL โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
The Web Server
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ webServer starts the app โ
โ โ โ
โ โผ โ
โ Playwright polls the URL until it responds โ
โ โ โ
โ โผ โ
โ Tests run โ
โ โ โ
โ โผ โ
โ Server stops โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
The Projects Matrix
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ setup โ chromium (desktop) โ
โ โ firefox (desktop) โ
โ โ webkit (desktop) โ
โ โ mobile (iPhone) โ
โ โ
โ The same tests run once per project. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Summary
| Item | Value |
|---|---|
| Config file | playwright.config.ts |
| Helper | defineConfig |
| Shared options | use block |
| Base URL | use.baseURL |
| Server | webServer |
| Cross-browser | projects array |
| Environment override | process.env.BASE_URL |
| Auth reuse | storageState |
Key takeaways:
- The config is the control surface for the run. The top-level options set the test directory, the retries, the parallelism, and the reporters; the
useblock sets the options that every test receives. use.baseURLmakes relative navigation work. The test writespage.goto("/login"), and the config decides whether that resolves to localhost, staging, or production. Theprocess.env.BASE_URLoverride is the environment-specific pattern.webServerstarts the application before the tests run. It replaces the separate terminal that runs the dev server, and it is the pattern for a CI job that has no separate server. ThebaseURLand thewebServer.urlshould match.- The
projectsarray is the cross-browser matrix. Each project runs the same tests with a different browser or viewport, and the--projectflag selects one. - The
dependenciesarray orders the projects. A test project that depends on the setup project runs after the setup file, which is the pattern for the authentication state.
Remember: The config is the one place where the environment-specific values live. baseURL is the setting every project needs, because it lets the tests use relative paths and the CI job point at a different deployment. webServer is the setting that makes the suite self-contained, and the projects are the matrix that runs the same tests on the browsers the users have. Change the config, not the tests.
Stop using slow, ad-bloated tool sites! ๐คฎ
๐ Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
โ
Finance (Mortgage, Interest, Inflation)
โ
Tech (Base64, JSON, Dev Suite, IP)
โ
Health (BMI, BMR, TDEE)
โ
Productivity (Timer, Workspace, QR)
โก๏ธ Fast & Private
๐ No data leaves your device
๐ 100% Free
๐ Use it now: https://tools.kandz.me
๐ Bookmark itโyouโll need it later!