Orchestration Setup

Setup instructions for Playwright Orchestration

Migrating from v1? See Migration Guide.

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

How does it work

At a high level:

• creates a list of tests for orchestration using pwc-p discover

• establishes an orchestration session with Currents servers

• assigns work to available CI machines using historical execution and timing data

• records results to Currents for troubleshooting and analysis

@currents/playwright includes a CLI command pwc-p that implements Playwright Orchestration.

1. pwc-p discover - runs Playwright in discovery mode and writes the list of tests to be orchestrated to a file.

2. pwc-p run - initiates the orchestrated execution based on the previous step.

Setup

Install @currents/playwright

npm i @currents/playwright@latest

• Run pwc-p discover to create a discovery file with tests selected for orchestration, you can apply the same filters and CLI arguments as for playwright command.

• Run pwc-p run with --pwc-discovery-file to execute the orchestration. Run pwc-p run --help to see the available flags or refer to @currents/playwright.

npx pwc-p discover --pwc-discovery-file <discovery-path> [...filters]
npx pwc-p run --pwc-discovery-file <discovery-path> --key <currents-record-key> --project-id <currents-project-id> --ci-build-id <ci-build-id>

A successfully created orchestration prints an output similar to this.

$ npx pwc-p run --key *secret* --project-id WeZwSj --ci-build-id example-001
🚀 Starting orchestration session...
📦 Currents reporter: 2.0.0
  - ci build id: example-001
  - project id: WeZwSj
  - orchestration id: 11b601f500893bacfa169acb126b6239
  - machine id: bA0qyMOxUiCz9XT0
🎭 Playwright: 1.60.0 5 tests in 1 project [chromium]

🌐 Executing orchestrated task: [chromium] test2.spec.ts, test.spec.ts
ℹ️  Batch size: 3
🌐 Run URL: https://app.currents.dev/run/4aefcb5cd3bb5c89
#...

Currents automatically balances tests between all available CI machines, which makes --shard redundant, it should be removed.

Read more about CI Build ID and Reporting Strategy.

When to use discover

pwc-p discover is required when you want to explicitly select tests for orchestration. For example:

• Filtering tests by tag: --grep / -g @smoke

• Filtering tests by last run outcome: --last-failed (see Re-running Only Failed Tests)

• Filtering tests by Playwright project: --project chromium

• Explicit spec file location: playwright test <spec-file-path>

Apply the desired arguments and parameters as if you are running playwright command, for example:

# Create discovery file with filters applied
npx pwc-p discover --pwc-discovery-file ./test-list --grep @smoke --project chromium

# Use the discovery file as an input for orchestration
npx pwc-p run --pwc-discovery-file ./test-list --key currents-record-key --project-id currents-project-id --ci-build-id ci-build-id

Omitting discovery stage selects all tests for orchestration.

Scenario	Commands
Run the full suite (no filters)	pwc-p run ...
Filter tests with Playwright flags	first pwc-p discover ... then pwc-p run ...

Discovery output

Creates a discovery file at a destination, then use the file as an input for pwc-p run command

npx pwc-p discover --pwc-discovery-file tests.txt --grep @smoke --project frontend
npx pwc-p run --pwc-discovery-file tests.txt ...

Additional methods for providing discovery file:

• CURRENTS_DISCOVERY_FILE environment variable

• orchestration.discoveryFile in currents.config.ts

CURRENTS_DISCOVERY_FILE or orchestration.discoveryFile are the recommended options for CI environments, as this setup applies to both discover and run commands.

Examples

Filter with grep:

npx pwc-p discover --pwc-discovery-file tests.txt --grep @smoke
npx pwc-p run --pwc-discovery-file tests.txt --key <record-key> --project-id <project-id> --ci-build-id <ci-build-id>

Filter with last-failed:

npx pwc-p discover --pwc-discovery-file tests.txt --last-failed
npx pwc-p run --pwc-discovery-file tests.txt --key <record-key> --project-id <project-id> --ci-build-id <ci-build-id>

Add tags on the recorded run (no discovery step):

npx pwc-p run --key <record-key> --project-id <project-id> --ci-build-id <ci-build-id> --tag tagA --tag tagB

Run pwc-p discover --help or pwc-p run --help to see the list of supported flags.

Orchestration in CI

Provider-specific orchestration examples are being updated for discover and run. Use these pages as starting points:

• GitHub Actions

• GitHub Actions: re-run only failed tests

• GitHub Actions + NX

• GitLab CI/CD

• NX

• Jenkins

• CircleCI

• Azure DevOps

• AWS CodeBuild

• Harness

Orchestration and Reporters

Additional Reporters

pwc-p run 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 reporters as a CLI parameter.

pwc-p run --key <record-key> --project-id <id> --ci-build-id <build-id> --reporter="./myreporter/my-awesome-reporter.ts"

Manual Configuration

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()],

  // ... rest of playwright configuration
};

• Optional: Update the pwc-p run CLI command

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

pwc-p run -- [...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 run --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

Orchestration distributes work at the spec-file level and uses two independent settings:

• --workers: Playwright's execution concurrency on a machine (passed straight to playwright test). Controls how many tests run in parallel locally.

• --pwc-batch-size: the number of parallel lanes the orchestrator fills for the machine currently requesting work. Defaults to auto, derived from your Playwright workers (project workers → global workers → 1).

How a batch is built

When a machine requests work, the orchestrator fills batch-size lanes by weight (a spec's weight is its expected duration from history):

1. The heaviest remaining spec goes into the first lane.

2. The other lanes are filled with lighter specs whose weight fits under that heaviest spec.

Because of step 2, batch size is not a hard limit on how many spec files a machine claims, with a batch size of 2 or more, a machine can claim more files than the batch size in a single request. The exception is --pwc-batch-size 1, which claims exactly one spec file per request (no packing).

--pwc-batch-size is a count of parallel lanes, not a count of spec files. With a batch size of 2 or more, a single machine may lock several spec files in one request (the heaviest spec plus lighter ones packed under it).

Batch size vs. workers

For most suites these are effectively one dial, which is why auto ties them together:

• File-level suites (not fully parallel): Playwright runs one file per worker, so usable concurrency is bounded by the number of files in the batch. Keep batch-size == workers (the default). Setting them apart either queues files (batch-size > workers) or idles workers (batch-size < workers).

• Fully parallel suites: Playwright parallelizes individual tests, so one file can keep many workers busy. Here a small batch size with a larger worker count. For example, --pwc-batch-size 1 --workers 4 gives fine-grained, even distribution across machines while still using all workers. See Fully Parallel Mode.

Distribution across machines

The orchestrator is machine-unaware: it doesn't know how many machines will join the run, or when. It fills the machine asking for work right now and doesn't reserve specs for machines that connect later. As a result:

• A fast or early machine can claim a large share of the queue.

• A machine that joins after the queue is already claimed receives no specs and ends its session.

For the most even distribution across a large matrix, use --pwc-batch-size 1. Trade-off: in file-level suites each machine then runs its files one at a time, so you gain even distribution but reduce per-machine parallelism.

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.

Batch size configuration

The batch size can be configured via env variable or cli option.

Starting at @currents/playwright version 1.14.0 and @playwright/test version starting at 1.52.0 the option can be set per project.

This means that the batch size can be handled globally, that also supports automatic detection of global workers, but also the project level workers and batch size is taken into account for defining the batch size.

Batch size for each project is determined by evaluating options in the following order of priority:

1

Global batch size

A global batch size defined via environment variable or CLI option will override any batch size or worker settings defined at the project level.

_{Starting with version 1.13.0, the reporter can automatically detect and use the global worker count as the batch size, if global workers are defined.}

2

Project batch size

currentsBatchSize defined at project level

_{This configuration is available in@currents/playwright version starting at 1.14.0 and @playwright/test version starting at 1.52.0}

3

Project workers

workers defined at project level

_{This configuration is available in@currents/playwright version starting at 1.14.0 and @playwright/test version starting at 1.52.0}

4

Global workers

Globally defined workers

5

Default

If none of the above is defined, batch size is 1

Project level workers

This feature allows you to set the number of workers at project level, enabling each project to specify its own batch size based on the workers.

This is how the workers can be defined:

...
projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
      workers: 2
    },
    {
      name: "firefox",
      use: { ...devices["Desktop Firefox"] },
      workers: 3
    },
  ],
...

Currents will use the batch size auto option by default. This means the reporter will read each project workers setting and use it as batch size.

If no workers are defined for a project, Currents will use the global workers value as batch size.

Project level batch size

The Playwright project configuration can be extended with currentsBatchSize which explicitly sets the batch size per project. Import CurrentsFixtures for typescript suport.

import type { CurrentsFixtures } from "@currents/playwright";
import { defineConfig, devices } from "@playwright/test";

export default defineConfig<CurrentsFixtures>({
  ...
  projects: [
    {
      name: "chromium",
      use: {
        ...devices["Desktop Chrome"],
        currentsBatchSize: 3
      },
      workers: 2,
    },
    {
      name: "firefox",
      use: {
        ...devices["Desktop Firefox"],
        currentsBatchSize: "auto"
      },
    },
  ],
  ...
});

In this example, the chromium project has 2 workers defined. However, since the currentsBatchSize property is set, Currents will use the specified currentsBatchSize instead of the workers value.

For the firefox project, the currentsBatchSize is set to auto, so Currents will use the project's workers value. Since it is not defined, Currents will fall back to the global workers value.

Re-running Only Failed Tests

Orchestrated reruns use pwc-p discover with --last-failed (or flags from the playwright-last-failed action) to build the filtered test list, then pwc-p run with --pwc-discovery-file.

npx pwc-p discover --pwc-discovery-file tests.txt --last-failed
npx pwc-p run --key <record-key> --project-id <project-id> --ci-build-id <ci-build-id> --pwc-discovery-file tests.txt

See Orchestrated runs for the full implementation details.

Limitations and Nuances

• Orchestration works on a file level — it balances test files (rather than individual tests).

• For Fully Parallel Mode, set Batch Size to 1 (and raise Playwright workers) so machines are balanced correctly, a single file's tests still run in parallel across workers.

• Playwright Project dependencies is not supported, if projects depend on one 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 runs playwright multiple times. Beware that global setup or teardown routines run for each invocation of playwright.

Next Steps

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