Playwright Configuration#

The playwright.config.ts file is central to controlling how Playwright tests execute in the PPUX repository. This configuration enables test authors to customize all aspects of the test runs through a combination of default settings and environment variables.

Process Environment Config Variables#

Process environment config variables allow you to customize test execution without modifying the config file. These variables can be set in your terminal, CI pipeline, or .env file to control test behavior:

  • ACCOUNT_ALIAS - Alias for the test account, used for authentication

  • BROWSER - Browser to run tests on: chromium / firefox / webkit (Default: chromium)

  • CONFIG_DIR - Directory containing the config.json file (Default: process.cwd())

  • CREATE_BUGS_FOR_FAILURES - Whether to create bug reports for test failures (Default: false)

  • ENV_TYPE - Test environment type: makershell, unifiedclient, etc. (Default: makershell)

  • HEADLESS - Run tests in headless mode: true / false (Default: false)

  • OUTPUT_DIR - Directory for test artifacts, authentication state, tokens and cookies (Default: process.cwd())

  • REPEAT - Number of times to repeat each test, useful for debugging flaky tests (Default: 0)

  • RETRIES - Number of retry attempts for failed tests (Default: 0)

  • RUN_ENV - Test run environment: prod / tie / test (Default: prod)

  • RUN_GEO - Geography for PROD environment: us, asia, etc. (Default: us)

  • RUN_TYPE - Test run type for filtering tests in pipelines (comma-separated for multiple types)

  • SEND_EMAIL_NOTIFICATION - Send email notifications for test results (Default: false)

  • SEND_FAILURE_EMAIL_NOTIFICATION - Send email notifications for failed tests (Default: false)

  • PUSH_FAILURES_TO_TELEMETRY - Push test result telemetry to ARIA (Default: false)

  • SLOW_DOWN_MS - Slow down test execution by specified milliseconds (useful for debugging)

  • TEST_DIR - Directory to scan for test files (Default: src)

  • TEST_RUN_NAME - Name of the test run for identification in reports

  • TEST_TIMEOUT - Timeout for each test in milliseconds (Default: 4 minutes)

  • WORKERS - Number of concurrent worker processes for test execution (Default: 1)

Configuration File Structure#

The playwright.config.ts file contains comprehensive configuration for all aspects of test execution:

import { PlaywrightTestConfig } from "@playwright/test";
import { BrowserTypes } from "@paeng/playwright-solution";
import { ProcessEnvironmentConfig } from "./src/utils/processEnvironmentConfig";
import { TimeOut } from "./src/utils/common";
import path from "path";
import { getBaseUrl } from "./src/utils/appUtils";
import { playwrightTestRunName, storageStatePath } from "./src/utils/common";

const handlebarPath = path.join(__dirname, "./src/handlebars");

const config: PlaywrightTestConfig = {
  name: playwrightTestRunName,
  globalSetup: require.resolve("./src/globals/global-setup"),
  globalTeardown: require.resolve("./src/globals/global-teardown"),
  reportSlowTests: null,
  updateSnapshots: "missing",

  use: {
    browserName: ProcessEnvironmentConfig().browserType as BrowserTypes,
    headless: ProcessEnvironmentConfig().headless,
    viewport: { width: 1920, height: 1080 },
    ignoreHTTPSErrors: true,
    acceptDownloads: true,
    extraHTTPHeaders:
      // The getBaseUrl still relies on global variables.
      // Newer code will use a fixture to do this instead
      process.env.ENV_TYPE && process.env.RUN_GEO && process.env.RUN_ENV
        ? {
            origin: new URL(getBaseUrl()).origin,
          }
        : {},
    screenshot: "only-on-failure",
    video: "retain-on-failure",
    trace: "retain-on-failure",
    locale: "en-US",
    actionTimeout: TimeOut.OneMinuteTimeOut,
    navigationTimeout: TimeOut.OneMinuteTimeOut,
    storageState: storageStatePath,
    launchOptions: {
      headless: ProcessEnvironmentConfig().headless,
      slowMo: Number(process.env.SLOW_DOWN_MS) || 40,
      devtools: process.env.AUTO_OPEN_DEVTOOLS === "true",
      args: [
        "--start-maximized",
        "--no-sandbox",
        "--disable-web-security",
        "--disable-features=IsolateOrigins",
        "--disable-site-isolation-trials",
        "--start-fullscreen",
        "--window-size=1920,1080",
      ],
    },
  },
  expect: {
    timeout: TimeOut.DefaultWaitTime,
  },
  outputDir: path.join(ProcessEnvironmentConfig().outputDirectory, "artifacts"),
  reporter: [
    ["list"],
    [
      "@paeng/playwright-test-reporter",
      {
        testRunName: ProcessEnvironmentConfig().playwrightTestRunName,
        testDirectory: ProcessEnvironmentConfig().testDirectory,
        sendEmail: ProcessEnvironmentConfig().sendEmailNotification,
        sendFailureEmail:
          ProcessEnvironmentConfig().sendFailureEmailNotification,
        emailHandlebarPath: handlebarPath,
        pushToTelemetry: ProcessEnvironmentConfig().pushFailuresToTelemetry,
        createBug: ProcessEnvironmentConfig().createBugForFailures,
      },
    ],
    [
      "junit",
      {
        outputFile:
          ProcessEnvironmentConfig().outputDirectory +
          "/artifacts/testResults/test-results.xml",
      },
    ],
  ],
  repeatEach: ProcessEnvironmentConfig().repeatEach,
  retries: ProcessEnvironmentConfig().retries,
  testDir: ProcessEnvironmentConfig().testDirectory,
  timeout: ProcessEnvironmentConfig().testTimeout,
  testMatch: ["**/?(*.)+(spec|test).+(ts|js)"],
  workers: ProcessEnvironmentConfig().workers,
};

export default config;

Configuration Sections Explained#

General Configuration#

  • name: Identifies the test run in reports, using a dynamically generated name

  • globalSetup: Path to script executed once before all tests begin

  • globalTeardown: Path to script executed once after all tests complete

  • reportSlowTests: Controls reporting of slow-running tests (disabled with null)

  • updateSnapshots: Set to 'missing' to update only missing snapshots

Browser and Test Execution Settings#

use: {
  browserName: ProcessEnvironmentConfig().browserType as BrowserTypes,
  headless: ProcessEnvironmentConfig().headless,
  viewport: { width: 1920, height: 1080 },
  // ...other settings
}

This section configures:

  • The browser to use (from environment variables)

  • Headless mode status

  • Viewport dimensions

  • HTTPS error handling

  • File download behavior

  • Origin headers for cross-domain requests

  • Screenshot, video, and trace capture settings

  • Locale settings

  • Timeouts for actions and navigation

  • Storage state path (for saved authentication)

  • Browser launch options including debugging settings

Assertion Settings#

expect: {
  timeout: TimeOut.DefaultWaitTime,
}

Controls the default timeout for assertions, using a predefined timeout constant.

Output and Reporting#

outputDir: path.join(ProcessEnvironmentConfig().outputDirectory, 'artifacts'),
reporter: [
  ['list'],
  [
    '@paeng/playwright-test-reporter',
    { /* reporter options */ }
  ],
  [
    'junit',
    { /* junit options */ }
  ],
],

Configures:

  • Where test artifacts (screenshots, videos, traces) are stored

  • Which reporters to use:

    • List reporter for console output

    • Custom PPUX reporter with email notifications and telemetry

    • JUnit reporter for CI integration

Test Execution Control#

repeatEach: ProcessEnvironmentConfig().repeatEach,
retries: ProcessEnvironmentConfig().retries,
testDir: ProcessEnvironmentConfig().testDirectory,
timeout: ProcessEnvironmentConfig().testTimeout,
testMatch: ['**/?(*.)+(spec|test).+(ts|js)'],
workers: ProcessEnvironmentConfig().workers,

These settings control:

  • How many times each test repeats

  • How many retry attempts for failed tests

  • Where to find test files

  • Maximum timeout for test execution

  • File pattern for identifying test files

  • Number of parallel workers for test execution

Customizing Configuration#

For local development and testing, set environment variables in your terminal or .env file:

Windows (PowerShell)#

$env:BROWSER = "chromium"
$env:HEADLESS = "false"
$env:RUN_TYPE = "nightly"
$env:ENV_TYPE = "makerShell"
$env:RUN_ENV = "test"
$env:ACCOUNT_ALIAS = "MakerShell_Nightly_Test_Us"

Linux/macOS#

export BROWSER="chromium"
export HEADLESS="false"
export RUN_TYPE="nightly"
export ENV_TYPE="makerShell"
export RUN_ENV="test"
export ACCOUNT_ALIAS="MakerShell_Nightly_Test_Us"

Using .env File#

Create a .env file in the project root:

BROWSER=chromium
HEADLESS=false
RUN_TYPE=nightly
ENV_TYPE=makerShell
RUN_ENV=test
ACCOUNT_ALIAS=MakerShell_Nightly_Test_Us

ProcessEnvironmentConfig Utility#

The ProcessEnvironmentConfig() function reads environment variables and provides default values. It’s defined in src/utils/processEnvironmentConfig.ts:

export function ProcessEnvironmentConfig(): EnvironmentConfig {
  return {
    accountAlias: process.env.ACCOUNT_ALIAS || "",
    browserType: process.env.BROWSER || "chromium",
    configDirectory: process.env.CONFIG_DIR || process.cwd(),
    createBugForFailures: process.env.CREATE_BUGS_FOR_FAILURES === "true",
    environmentType: process.env.ENV_TYPE?.toLowerCase() || "makershell",
    headless: process.env.HEADLESS === "true",
    outputDirectory: process.env.OUTPUT_DIR || process.cwd(),
    playwrightTestRunName: process.env.TEST_RUN_NAME || "Playwright Tests",
    pushFailuresToTelemetry: process.env.PUSH_FAILURES_TO_TELEMETRY === "true",
    repeatEach: Number(process.env.REPEAT) || 0,
    retries: Number(process.env.RETRIES) || 0,
    runEnvironment: process.env.RUN_ENV?.toLowerCase() || "prod",
    runGeography: process.env.RUN_GEO?.toLowerCase() || "us",
    runType: process.env.RUN_TYPE?.toLowerCase() || "",
    sendEmailNotification: process.env.SEND_EMAIL_NOTIFICATION === "true",
    sendFailureEmailNotification:
      process.env.SEND_FAILURE_EMAIL_NOTIFICATION === "true",
    testDirectory: process.env.TEST_DIR || "src",
    testTimeout: Number(process.env.TEST_TIMEOUT) || 240000, // 4 minutes
    workers: Number(process.env.WORKERS) || 1,
  };
}

Best Practices#

  1. Use environment variables for runtime configuration rather than modifying the config file

  2. Set common variables in .env file for local development

  3. Override critical settings in CI pipelines for different test environments

  4. Start with minimal workers (1-2) during development and increase for CI runs

  5. Enable screenshots, videos, and traces for failure diagnostics

  6. Use the same viewport size across all tests for consistency

  7. Set reasonable timeouts to catch performance issues without causing false failures

Common Configuration Patterns#

Local Development#

HEADLESS=false
WORKERS=1
RETRIES=0
ENV_TYPE=makerShell
RUN_TYPE=nightly

CI Pipeline#

HEADLESS=true
WORKERS=4
RETRIES=2
SEND_EMAIL_NOTIFICATION=true
PUSH_FAILURES_TO_TELEMETRY=true

Performance Testing#

HEADLESS=true
WORKERS=1
REPEAT=3
TEST_TIMEOUT=300000