Type-Safe Environment Configuration for Playwright Test

Environment selection is a safety boundary in an end-to-end suite. A misspelled variable should not quietly send tests to a default host, and a missing API credential should not surface after twenty minutes of execution. Type-safe Playwright environment configuration turns untrusted runtime strings into one validated object before Playwright discovers a test.

The central pattern is simple: accept a small input such as TEST_ENV=staging, narrow it to an explicit union, resolve all public endpoints and policies from one map, and validate required secrets separately. Tests then consume stable configuration instead of reading process.env in scattered files.

Treat Environment Variables as Untrusted Input

TypeScript types disappear at runtime. Declaring const env = process.env.TEST_ENV as TestEnvironment silences the compiler but does not validate the value. stagin, an empty string, and an unsupported branch name all pass through that assertion. The suite may use undefined, select a dangerous fallback, or build malformed URLs.

Playwright evaluates its configuration before running tests, which makes the config boundary the right place to reject invalid input. The official configuration guide shows use.baseURL as the base for relative navigations. Resolve that URL once, then keep tests environment-neutral with calls such as page.goto("/login").

Define a Small, Exhaustive Environment Model

Keep the committed map limited to non-secret values: application origins, public API origins, feature expectations, and safe execution policy. The satisfies operator verifies that every supported environment exists and that each entry has the required shape without widening away useful literal information.

type TestEnvironment = "local" | "staging" | "production";

type EnvironmentConfig = {
  appUrl: string;
  apiUrl: string;
  allowDataMutation: boolean;
  defaultTimeoutMs: number;
};

const environments = {
  local: {
    appUrl: "http://127.0.0.1:3000",
    apiUrl: "http://127.0.0.1:3001",
    allowDataMutation: true,
    defaultTimeoutMs: 15_000,
  },
  staging: {
    appUrl: "https://staging.example.test",
    apiUrl: "https://api.staging.example.test",
    allowDataMutation: true,
    defaultTimeoutMs: 25_000,
  },
  production: {
    appUrl: "https://www.example.test",
    apiUrl: "https://api.example.test",
    allowDataMutation: false,
    defaultTimeoutMs: 20_000,
  },
} satisfies Record<TestEnvironment, EnvironmentConfig>;

function isTestEnvironment(value: string): value is TestEnvironment {
  return Object.hasOwn(environments, value);
}

export function resolveEnvironment(
  raw = process.env.TEST_ENV ?? "local",
): EnvironmentConfig & { name: TestEnvironment } {
  if (!isTestEnvironment(raw)) {
    throw new Error(
      `Invalid TEST_ENV "${raw}". Expected local, staging, or production.`,
    );
  }

  return { name: raw, ...environments[raw] };
}

A local default is reasonable for developer convenience only if local is harmless. CI should always set TEST_ENV explicitly. Production should never be a fallback. If a suite can mutate data, carry that policy in the typed object and enforce it where mutation fixtures are created.

Validate URLs and Required Secrets at Startup

A union validates the environment name, not the contents of each external value. If hosts are supplied dynamically, parse them with new URL() and restrict protocols or hostnames according to your deployment model. Keep secret validation focused on presence and scope; do not place the values in thrown errors.

function requireSecret(name: "E2E_USERNAME" | "E2E_PASSWORD"): string {
  const value = process.env[name]?.trim();
  if (!value) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

function assertHttpUrl(label: string, raw: string): URL {
  const parsed = new URL(raw);
  if (parsed.protocol !== "https:" && parsed.hostname !== "127.0.0.1") {
    throw new Error(`${label} must use HTTPS outside local development.`);
  }
  return parsed;
}

const target = resolveEnvironment();
assertHttpUrl("appUrl", target.appUrl);

export const credentials = {
  username: requireSecret("E2E_USERNAME"),
  password: requireSecret("E2E_PASSWORD"),
};

Do not export credentials from a general helper if most tests do not need them. Prefer an authentication setup file or fixture that reads the validated values and exposes only authenticated state. This reduces accidental logging and makes the secret's consumers easier to audit.

Feed the Typed Object Into Playwright

Build the Playwright config from the resolved target. The config can include a non-secret header naming the test source, but credentials should enter through authentication requests or storage state. A concise startup line is useful in CI as long as it prints only approved metadata.

import { defineConfig, devices } from "@playwright/test";
import { resolveEnvironment } from "./config/environment";

const target = resolveEnvironment();

console.info(
  `[playwright] environment=${target.name} baseURL=${target.appUrl}`,
);

export default defineConfig({
  testDir: "./tests",
  timeout: target.defaultTimeoutMs,
  forbidOnly: Boolean(process.env.CI),
  retries: process.env.CI ? 1 : 0,
  use: {
    baseURL: target.appUrl,
    extraHTTPHeaders: {
      "x-e2e-source": "playwright",
    },
    trace: "on-first-retry",
  },
  projects: [
    {
      name: `${target.name}-chromium`,
      use: { ...devices["Desktop Chrome"] },
    },
  ],
});

The environment is selected once per Playwright process. If you genuinely need to compare staging and production in the same run, represent them as separate projects with separate policies. Otherwise, one target per invocation keeps failures, credentials, and generated data easier to attribute.

Give Tests Typed Access Without Reading the Process

Most tests need only relative navigation. Helpers that call APIs may need the resolved API origin or mutation policy. Provide those through a custom fixture so test code depends on a typed value, not ambient process state.

import { test as base } from "@playwright/test";
import { resolveEnvironment } from "../config/environment";

type EnvironmentFixture = {
  target: ReturnType<typeof resolveEnvironment>;
};

export const test = base.extend<EnvironmentFixture>({
  target: async ({}, use) => {
    await use(resolveEnvironment());
  },
});

export { expect } from "@playwright/test";

This fixture is intentionally read-only. A test can inspect target.allowDataMutation, while a data-creation helper can refuse to run in production. Avoid fixtures that mutate the resolved object because worker behavior then depends on execution order.

Make CI Commands Explicit and Reviewable

Use one documented variable name everywhere. Shell wrappers that map ENV, TARGET, STAGE, and branch names into different meanings create configuration bugs that types cannot repair. CI jobs should show their target at the command boundary:

TEST_ENV=local npx playwright test tests/smoke
TEST_ENV=staging npx playwright test
TEST_ENV=production npx playwright test --grep @synthetic

Store E2E_USERNAME and E2E_PASSWORD in the CI provider's protected secret store. Scope production credentials to the minimum read-only permissions and a dedicated account. Prevent forked or untrusted pipelines from receiving protected secrets. The Playwright process should fail when a selected job lacks a required secret, not substitute a shared developer credential.

Keep local commands equally explicit in package scripts and team documentation. A developer should be able to identify the selected host from the command and startup summary without opening the config. That visibility also makes copied CI logs useful during incident review: responders can distinguish a target-selection error from an application failure before downloading a trace.

Analyze Common Configuration Failures

The most dangerous failure is an implicit fallback. A typo selects local while the test-data helper still points at a remote API, producing a mixed-environment run. Reject unknown values and resolve every endpoint from the same target object.

Another failure comes from unsafe type assertions. as TestEnvironment improves editor silence, not runtime safety. Replace it with a type guard or schema parser. A third failure is reading process.env inside individual tests. That makes behavior depend on where a helper was imported and makes it difficult to print one trustworthy configuration summary.

Finally, watch for secrets in reports and errors. A failed request can attach headers, and a debug statement can expose a token. Mask secrets at the logging boundary, keep authentication artifacts out of version control, and review traces from protected environments before broad retention.

Choose Between One Target and Environment Projects

One validated target per run gives clear ownership, smaller reports, and straightforward secret injection. Its drawback is that cross-environment comparison requires separate invocations. Environment projects put results in one Playwright report and can use different retries or test filters, but they increase concurrency risk and make accidental production execution easier.

Choose based on the workflow. Release pipelines that compare two immutable candidate deployments may benefit from projects. Everyday development usually benefits from TEST_ENV selecting one destination. In either model, the same principles hold: allowlist names, validate at startup, keep credentials external, and encode mutation policy.

Operational Checklist

• Define supported environments as a TypeScript union and exhaustive map.
• Parse runtime strings instead of asserting their types.
• Resolve application and API origins from one selected object.
• Make production impossible as an implicit default.
• Validate required secrets without printing their values.
• Use baseURL so tests navigate with stable relative paths.
• Expose environment details through a read-only fixture when helpers need them.
• Enforce a no-mutation policy for production-oriented tests.
• Print a non-secret target summary before test discovery.
• Keep the same variable names in local scripts and CI jobs.

Action Plan

Create the union and environment map first, then replace direct process.env reads with one resolver. Wire its appUrl into use.baseURL, route API helpers through a typed fixture, and add startup checks for URLs and secret presence. Next, run one command with an invalid environment and confirm it fails before discovering tests. Finish by reviewing CI permissions and production mutation guards. Once those checks are in place, changing targets becomes an explicit operation rather than a hopeful string substitution.