Orchestration Setup

Playwright Orchestration setup instructions

Orchestration helps decrease the duration of Playwright tests in CI pipelines. Read our detailed guide on Playwright Parallelization that compares the native sharding with orchestration.

How does it work

@currents/playwright contains a command-line executable pwc-p — a lightweight wrapper that implements Orchestration and runs Playwright behind the scenes.

• it scans the testing suite

• it establishes an orchestration session with Currents servers

• it runs Playwright, executing spec files in the optimal order

• the results are recorded to Currents for troubleshooting and analysis

Setup

Install @currents/playwright

npm i @currents/playwright

Replace playwright command with pwc-p

npx pwc-p --key <record-key> --project-id <project-id> --ci-build-id <ci-build-id>

Read more about CI Build ID and Reporting Strategy

pwc-p accepts additional playwright arguments and flags (see @currents/playwright), for example:

# Add additional playwright arguments and flags:
pwc-p --key <record-key> --project-id <id> --ci-build-id <build-id> -- --workers 2 --timeout 10000

There's no need to define shards,

Make sure to remove --shard flag — Currents uses all the available machines automatically.

A successfully created orchestration prints an output similar to this:

$ npx pwc-p --key **redacted** --project-id **redacted** --ci-build-id `date +%s`  -c ./or8n/playwright.config.ts

🚀 Starting orchestration session...
📦 Currents reporter: 1.1.2 recording CI build 1712134904 for project JJzd65, orchestration id 260264cfa16950ab4dc98d5c54333136
🎭 Playwright: 1.42.1 5 tests in 1 project [chromium]

🌐 Executing orchestrated task: [chromium] spec-or8n-e.spec.ts
🌐 Run URL: https://app.currents.dev/run/9b93659915fe653f
# ...start executing the tests in an optimal order.

Examples

Check out the following example configuration of running orchestration in popular CI providers:

• GitHub Actions
• GitLab CI/CD
• GitHub Actions + NX
• Missing an example? Let us know.

Orchestration and Reporters

Adding Additional Reporters

pwc-p automatically injects Currents reporter @currents/playwright into playwright, replacing all other reporters configured in playwright.config.ts . To add additional reporters use one of the two options

Add additional reporters via a CLI parameter.

# passing additional reporters:
pwc-p --key <record-key> --project-id <id> --ci-build-id <build-id> --reporter="./myreporter/my-awesome-reporter.ts"

Prevent automatic injection of Currents reporter, add it manually.

• Create currents.config.ts with the following contents:

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

const config: CurrentsConfig = {
  recordKey: process.env.CURRENTS_RECORD_KEY,
  projectId: process.env.CURRENTS_PROJECT_ID,
  ciBuildId: "value", // ⚠️ Set the value as described in CI build ID guide
  orchestration: {
    skipReporterInjection: true, // prevent automatic reporter injection
  },
};

export default config;

• Update playwright.config.ts

import { currentsReporter } from "@currents/playwright";
import { PlaywrightTestConfig } from "@playwright/test";

const config: PlaywrightTestConfig = {
  reporter: [
    currentsReporter(), // Currents reporter will use 
    // reporter
  ],

  // ... rest of playwright configuration
}

• Optional: Update pwc-p CLI command

pwc-p reads all the configuration from currents.config.ts - no need to use CLI params.

pwc-p  -- [...playwright-cli-params]

Merging Fragmented Reports

Orchestration dynamically pulls test files from a central server, and each pull starts a fresh Playwright process. This can impact reporters that write output files—since a new process runs for each pull, you may need to handle file overwrites and merge results correctly.

The solution is to use the blob reporter to gather all the fragmented results and merge them.

# The PWTEST_BLOB_DO_NOT_REMOVE env variable is needed 
# to preserve the `blob-report` directory between orchestrated spec runs
PWTEST_BLOB_DO_NOT_REMOVE=1 pwc-p --key <record-key> --project-id <id> --ci-build-id <build-id> --reporter blob

You can generate other reports by passing the blob results to the merge-reports command.

npx playwright merge-reports --reporter=html ./blob-report

Check an example of Github Actions setup here.

Orchestration and Multiple Workers

@currents/playwright#13.0.0+ supports automatic detection of multiple workers and the orchestration adjusts to make the best use of the available workers.

When multiple workers are enabled, the orchestrator creates a "batch" of multiple test files to ensure the most optimal utilization of all the available workers. The batch runs as single playwright command.

As of May 2025, the Playwright Test Runner does not respect the execution order of test files. This means that even if Currents suggests an optimal execution order, Playwright may run files in a different sequence when multiple workers are used. It only affects cases when multiple workers are involved and has a minor impact.

Also see Fully Parallel Mode.

Re-running Only Failed Tests

Re-running only failed tests for orchestrated runs requires collecting the results from multiple machines, or alternatively getting the failed test from Currents API. We have created a set of tools to simplify the setup. See Re-run Only Failed Tests.

Limitations and Nuances

• Orchestration works on a file level - i.e. it balances test files (rather than tests)

• Playwright Project dependencies is not supported - i.e. if you have projects that depend one on another, orchestration will not consider the dependencies. As a workaround, run the dependencies in the desired order explicitly by defining separate CI steps with --project <name> specification.
• Global Setup and Teardown. An orchestrated execution will run playwright command multiple times. Beware, that the global setup or teardown routines will run for each invocation of playwright.

Next Steps

• Use Cloud Spot Instances to reduce your CI bills by 90%

• Explore how to Re-run Only Failed Tests