Environments

How to label and filter Currents runs by environment (e.g. staging, production)

Availability

• Setting an environment is available in @currents/playwright version 2.1.0+.

• Filtering by environment in the Dashboard (Runs + Analytics) and the REST API is available for all projects.

An environment is a label that describes where or under which conditions a test run was executed — for example staging, production, preview, or a CI matrix dimension such as a target region or device pool. Attaching an environment lets you compare and filter results across deployment targets without mixing them into the same metrics.

Common uses:

• Separate staging vs production smoke runs in the same project.

• Compare stability of the same suite across regions (e.g. us-east, eu-west).

• Slice Analytics (run status, duration, flakiness, test results) by deployment target.

Run with multiple group-level environments: production, staging

Environments vs. Tags

Both classify runs, but they serve different purposes:

	Environment	Tags
Cardinality	One value per run or per Playwright project	Many values per run/group/test
Intent	Where the tests ran (deployment target)	Arbitrary classification (feature, team, lifecycle)
Source	Reporter config / project metadata	Test titles, project metadata, run config

A run can still end up with multiple environments when different Playwright projects within the same run set different values — see How environments aggregate to a run below.

Setting the environment

The environment is a run-level value, with an optional per-project override. It can be provided through any of the standard configuration sources.

currents.config.ts

import type { CurrentsConfig } from "@currents/playwright";

const config: CurrentsConfig = {
  recordKey: process.env.CURRENTS_RECORD_KEY ?? "",
  projectId: process.env.CURRENTS_PROJECT_ID ?? "",
  environment: process.env.DEPLOY_ENV ?? "staging",
};

export default config;

CURRENTS_ENVIRONMENT environment variable

CURRENTS_ENVIRONMENT=production npx playwright test

--pwc-environment CLI option

Supported by pwc, pwc-p discover, and pwc-p run:

npx pwc --pwc-environment staging

Inline reporter option

// playwright.config.ts
import { currentsReporter } from "@currents/playwright";

export default defineConfig({
  reporter: [
    currentsReporter({
      recordKey: process.env.CURRENTS_RECORD_KEY,
      projectId: process.env.CURRENTS_PROJECT_ID,
      environment: "staging",
    }),
  ],
});

Per-project override

Set metadata.pwc.environment on a Playwright project to override the run-level environment for that project only:

// playwright.config.ts
export default defineConfig({
  projects: [
    {
      name: "chromium",
      metadata: { pwc: { environment: "staging" } }, // 👈 per-project
      use: { ...devices["Desktop Chrome"] },
    },
    {
      name: "firefox",
      metadata: { pwc: { environment: "production" } }, // 👈 per-project
      use: { ...devices["Desktop Firefox"] },
    },
  ],
});

Precedence of configuration options

When the environment is defined in more than one place, Currents resolves the value as follows (highest priority first):

• Per-project projects[].metadata.pwc.environment, if set for the project;

• Otherwise the run-level value:

  • CURRENTS_ENVIRONMENT environment variable, if provided; otherwise

  • --pwc-environment CLI option, if provided; otherwise

  • environment from the inline reporter options in playwright.config.ts; otherwise

  • environment from currents.config.ts; otherwise

  • no environment is attached.

How environments aggregate to a run

The environment is resolved per Playwright project and attached to the corresponding group when results are reported. At the run level, Currents collects the distinct environments from all groups into a list.

For the per-project example above, the resulting run is associated with both staging and production, and shows up when filtering by either value:

Item	Environment
Run	staging, production
Group chromium	staging
Group firefox	production

If every project shares the same value (or you only set a run-level value), the run is associated with that single environment.

Filtering in the Dashboard

Once runs carry an environment, an Environment filter is available in the Runs and across Analytics. Selecting one or more environments narrows every metric on the page to runs that ran in those environments.

Filtering via the REST API

Both the runs and insights endpoints accept an environments[] query parameter (repeat it to pass multiple values). Runs that match any of the supplied environments are returned.

See the API reference for the full list of query parameters.