Implementation:Microsoft Playwright DefineConfig

Knowledge Sources	Playwright Playwright defineConfig API
Domains	Testing, Browser_Automation
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for declarative test suite configuration provided by the Playwright library, enabling developers to define how tests run across browsers, timeouts, parallelism, and reporters.

Description

The defineConfig function is Playwright's primary mechanism for creating and composing test suite configurations. It accepts one or more configuration objects and merges them into a single unified configuration. The function lives in the @playwright/test package and is the recommended way to define configuration in playwright.config.ts files.

Internally, defineConfig performs deep merging of configuration objects with specific rules for different field types. It tags the resulting configuration with a kDefineConfigWasUsed symbol so the test runner can distinguish between raw objects and properly composed configurations. The merged configuration is later resolved into a FullConfigInternal object by the config loader.

The function supports a variadic signature, allowing base configurations to be extended with overrides. This enables patterns like sharing a base configuration across multiple projects while customizing specific settings per environment.

Usage

Use defineConfig in the playwright.config.ts file at the root of a Playwright project. It is the entry point for all test configuration and should be used whenever defining browser targets, timeouts, reporter settings, web server configurations, or project-level overrides. It is also used when composing configurations from multiple sources (e.g., a shared base config with local overrides).

Code Reference

Source Location

• Repository: playwright
• File: packages/playwright/src/common/configLoader.ts (lines 33-88)
• Resolution: packages/playwright/src/common/config.ts (lines 42-68)

Signature

function defineConfig(config: PlaywrightTestConfig): PlaywrightTestConfig;
function defineConfig<T extends Record<string, any>>(
  config: PlaywrightTestConfig<T>
): PlaywrightTestConfig<T>;
function defineConfig(
  ...configs: PlaywrightTestConfig[]
): PlaywrightTestConfig;

Import

import { defineConfig } from '@playwright/test';

I/O Contract

Inputs

Name	Type	Required	Description
configs	PlaywrightTestConfig[]	Yes (at least one)	One or more configuration objects to merge. Each object can specify any combination of test runner options.
configs[n].testDir	string	No	Directory containing test files, relative to the config file.
configs[n].timeout	number	No	Default timeout for each test in milliseconds.
configs[n].retries	number	No	Number of times to retry failed tests.
configs[n].workers	string	No	Number of parallel workers (e.g., 4 or '50%').
configs[n].reporter	ReporterDescription[]	No	List of reporters to use (e.g., 'html', 'json', 'junit').
configs[n].use	UseOptions	No	Default options for all tests (e.g., browserName, headless, viewport, trace). Deep-merged across configs.
configs[n].projects	ProjectConfig[]	No	Project-specific configurations. Merged by project name across configs.
configs[n].expect	ExpectConfig	No	Default expect options (e.g., timeout, toHaveScreenshot). Deep-merged across configs.
configs[n].webServer	WebServerConfig[]	No	Web server(s) to start before tests. Merged across configs.
configs[n].build	BuildConfig	No	Build configuration for component testing. Deep-merged across configs.

Outputs

Name	Type	Description
config	PlaywrightTestConfig	A merged configuration object tagged with kDefineConfigWasUsed. Scalar fields use last-writer-wins semantics. The expect, use, and build fields are deep-merged. The projects array is merged by project name. The webServer field is concatenated.
(resolved)	FullConfigInternal	After loading, the config is resolved into a FullConfigInternal at config.ts:L42-68 with all paths made absolute and defaults applied.

Usage Examples

Basic Example

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',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
});

Composition Example

import { defineConfig } from '@playwright/test';
import baseConfig from './playwright.base.config';

export default defineConfig(baseConfig, {
  // Override specific settings from the base config
  retries: 3,
  use: {
    // Deep-merged with baseConfig.use
    headless: false,
    video: 'on',
  },
  projects: [
    {
      // Merges with the 'chromium' project from baseConfig by name
      name: 'chromium',
      use: { viewport: { width: 1920, height: 1080 } },
    },
  ],
});

Related Pages

Implements Principle

• Principle:Microsoft_Playwright_Test_Configuration

Requires Environment

• Environment:Microsoft_Playwright_Node_Runtime_Environment