| | |

Playwright 13 ๐ŸŽญ Configuration โ€” playwright.config.ts and baseURL setup

โฑ๏ธ Estimated read: 8 min | |

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

OptionPurpose
testDirTest file location
fullyParallelRun tests in parallel
forbidOnlyFail on test.only in CI
retriesRetry count
workersParallelism
reporterOutput format

use Options

OptionPurpose
baseURLRelative navigation base
traceTrace recording
screenshotScreenshot on failure
videoVideo recording
storageStateAuth state file

Projects

ProjectUse
chromiumDesktop Chrome
firefoxDesktop Firefox
webkitDesktop Safari
mobileiPhone 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

PitfallWhy It HappensFix
page.goto failsNo baseURLSet use.baseURL
Server not runningNo webServerAdd the config block
CI hits localhostNo environment overrideBASE_URL
Setup runs out of orderNo dependenciesAdd 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

ItemValue
Config fileplaywright.config.ts
HelperdefineConfig
Shared optionsuse block
Base URLuse.baseURL
ServerwebServer
Cross-browserprojects array
Environment overrideprocess.env.BASE_URL
Auth reusestorageState

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 use block sets the options that every test receives.
  • use.baseURL makes relative navigation work. The test writes page.goto("/login"), and the config decides whether that resolves to localhost, staging, or production. The process.env.BASE_URL override is the environment-specific pattern.
  • webServer starts 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. The baseURL and the webServer.url should match.
  • The projects array is the cross-browser matrix. Each project runs the same tests with a different browser or viewport, and the --project flag selects one.
  • The dependencies array 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.

Was this helpful?


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!