Playwright Projects

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

What is a Project

In Playwright, a Project represents a set of tests that run under a specific browser and device configuration.

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'] },
    },
  ],

});

Running tests on specific browsers:

# Run only on Chromium
npx playwright test --project=chromium

# Run on Chromium and Firefox
npx playwright test --project=chromium --project=firefox

Devices Presets

Playwright comes with a large number of device presets (from devices in @playwright/test), simulating real device viewports, User-Agent, pixel ratio, etc.

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 Name	Device Type	Viewport Size
`Desktop Chrome`	Desktop	1280×720
`Desktop Firefox`	Desktop	1280×720
`Desktop Safari`	Desktop	1280×720
`iPhone 15`	Phone	393×852
`Pixel 7`	Phone	412×915
`iPad Pro`	Tablet	1024×1366

Custom Project Configuration

You can override global configurations in a Project's use:

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 locale
        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 the dependent project runs first.

The most common usage is a Setup project (authentication) running first, with other projects depending on it.

Example

export default defineConfig({

  projects: [
    // Setup project —— generates authentication state
    {
      name: 'setup',
      testMatch: /auth.setup.ts/,
    },
    // Test projects depend 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'],
    },
  ],

});

The setup project only runs once, and all projects that depend on it will wait for it to complete before starting.

Sharing Configuration via testProject

If you want multiple projects to 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 configuration
      use: {
        ...desktopProject.use, // Inherit first
        browserName: 'chromium', // Then override
      },
    },
    {
      name: 'firefox',
      use: {
        ...devices['Desktop Firefox'],
        // Override viewport and locale
        viewport: { width: 1920, height: 1080 },
        locale: 'zh-CN',
      },
    },
  ],

});

YouTip