Environments

An environment is a named deployment or customer configuration that tests run against, such as staging or production. It controls which Playwright projects run, which variables they receive, and whether the suite runs on a schedule. Each environment has:

A name shown in the dashboard.
A unique slug used by the API, CLI, and ENV_SLUG at runtime. Slugs contain lowercase letters, numbers, and hyphens.
Match and ignore patterns that select Playwright projects.
Optional variables and a scheduled trigger.

Manage environments as code

Environment configuration lives in .empiricalrun/ENVIRONMENTS.yaml in the test repository. Add an entry for each deployment or customer configuration:

environments:
  - slug: staging
    name: Staging
    playwright_projects_match:
      - "*"
    playwright_projects_ignore:
      - "*-production"
    env_files:
      - .env.example
      - .env.example.staging
    variables:
      - name: BASE_URL
        value: https://staging.example.com

  - slug: production
    name: Production
    playwright_projects_match:
      - "*-production"

Open a pull request for the change. Empirical does not read ENVIRONMENTS.yaml from a feature branch or an open pull request; the configuration is picked up only after the pull request is merged into the test repository’s default branch. Empirical then syncs the environments automatically. To retry the sync or force Empirical to reread the file from the default branch, go to Settings → Environments and click Sync. The dashboard shows the synced configuration but does not create or edit environments. When an entry is removed from YAML, Empirical disables an existing environment that has run history and deletes one that has never been used. playwright_projects_match and playwright_projects_ignore accept glob patterns. Put exclusions in the ignore list; patterns beginning with ! are rejected.

Environment variables

There are three ways to provide values. Later sources override earlier ones:

env_files from the test repository, merged in listed order.
Inline variables in ENVIRONMENTS.yaml.
Dashboard variables under Settings → Environment variables.

Use tracked template files such as .env.example; do not add .env itself to env_files. Keep secrets in the dashboard, where a variable can apply to all environments or only selected ones. At runtime Empirical writes .env.<slug> and sets ENV_SLUG. If the test repo loads dotenv, it can select the matching file:

import * as dotenv from "dotenv";

const envSlug = process.env.ENV_SLUG?.toLowerCase();
dotenv.config({ path: envSlug ? `.env.${envSlug}` : ".env" });

For a deployment-specific URL supplied by CI, set BUILD_URL as a run-level environment variable override. Run-level overrides take precedence over the environment’s configured values.

Scheduled runs

Add a five-field cron expression to the environment in .empiricalrun/ENVIRONMENTS.yaml. Schedules are evaluated in UTC and cannot be created or edited in the dashboard.

scheduled_trigger:
  cron: "0 2 * * *"
  concurrency:
    group: production-nightly
    on_conflict: wait

The concurrency block is optional. Use wait to prevent scheduled runs from overlapping, or cancel to replace an active run in the same group. See Scheduled runs and Concurrency.

Getting Started

Platform

Features

Integrations

Trigger a test run

Manage environments as code

Environment variables

Scheduled runs

​Manage environments as code

​Environment variables

​Scheduled runs

Manage environments as code

Environment variables

Scheduled runs