Playwright Multi-Project Configuration (Projects)

This chapter introduces how to run tests on multiple browsers and devices through Projects configuration, as well as the usage of project dependencies.

What is a Project

In Playwright, a Project represents a group oftests that run under specific browser and device configurations.

By configuring multiple Projects, you can run the same set of test code on Chromium, Firefox, WebKit, and mobile devices.

Basic Multi-Browser Configuration

Example

// File path: playwright.config.ts
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 tests for a specific browser:

# 仅在 Chromium 上运行
npx playwright test --project=chromium

# 在 Chromium 和 Firefox 上运行
npx playwright test --project=chromium --project=firefox

devices Device Presets

Playwright includes a large number of built-in device presets (from@playwright/testofdevices), which simulate the viewport, User-Agent, pixel ratio, etc. of real devices.

Example

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

export default defineConfig({
  projects: [
    // Desktop
    {
      name: 'desktop-chrome',
      use: { ...devices['Desktop Chrome'] },
    },

    // Mobile
    {
      name: 'mobile-iphone',
      use: { ...devices['iPhone 15'] },
    },
    {
      name: 'mobile-pixel',
      use: { ...devices['Pixel 7'] },
    },

    // Tablet
    {
      name: 'tablet-ipad',
      use: { ...devices['iPad Pro'] },
    },
  ],
});

Commonly used device presets:

Preset NameDevice TypeViewport Size
Desktop ChromeDesktop1280×720
Desktop FirefoxDesktop1280×720
Desktop SafariDesktop1280×720
iPhone 15Mobile393×852
Pixel 7Mobile412×915
iPad ProTablet1024×1366

Custom Project Configuration

You can in the Project'suseoverride global configuration:

Example

export default defineConfig({
  use: {
    baseURL: 'http://localhost:3000',
    locale: 'zh-CN',
    timezone: 'Asia/Shanghai',
  },

  projects: [
    {
      name: 'chromium-desktop',
      use: {
        ...devices['Desktop Chrome'],
        // Inherit global locale and timezone
      },
    },
    {
      name: 'chromium-mobile',
      use: {
        ...devices['Pixel 7'],
        // Override to English environment
        locale: 'en-US',
        timezone: 'America/New_York',
      },
    },
    // Test dark mode
    {
      name: 'chromium-dark',
      use: {
        ...devices['Desktop Chrome'],
        colorScheme: 'dark',
      },
    },
    // Test light mode
    {
      name: 'chromium-light',
      use: {
        ...devices['Desktop Chrome'],
        colorScheme: 'light',
      },
    },
  ],
});

Project Dependencies

A project can depend on another project, ensuring that the project it depends on runs first.

The most common usage is a Setup project (authentication) runs first, and other projects depend on it.

Example

export default defineConfig({
  projects: [
    // Setup project — generate authentication state
    {
      name: 'setup',
      testMatch: /auth\.setup\.ts/,
    },

    // Test project depends on setup, ensuring authentication state is generated first
    {
      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'],
    },
  ],
});

setupA project will only run once, and all projects that depend on it will wait for it to complete before starting.

Sharing Configuration via testProject

To let multiple projects share configuration without repetition, you can extract a base project:

Example

// File path: playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

const desktopProject = {
  use: {
    ...devices['Desktop Chrome'],
    viewport: { width: 1920, height: 1080 },
    locale: 'zh-CN',
  },
} as const;

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      ...desktopProject,  // Inherit desktopProject's configuration
      use: {
        ...desktopProject.use,  // First inherit
        browserName: 'chromium', // Then override
      },
    },
    {
      name: 'firefox',
      use: {
        ...devices['Desktop Firefox'],
        // Override viewport and locale
        viewport: { width: 1920, height: 1080 },
        locale: 'zh-CN',
      },
    },
  ],
});
Other Extensions