How to Shard a Playwright Suite Across CI Machines

Playwright sharding splits a test suite into smaller groups so those groups can run at the same time across multiple CI machines. For example, a suite can be divided into four shards and each CI job runs one part:

npx playwright test --shard=1/4
npx playwright test --shard=2/4
npx playwright test --shard=3/4
npx playwright test --shard=4/4

Each CI machine needs the Playwright project, browser/runtime setup, test configuration, and the correct shard assignment.

Leapwork Play simplifies the execution side of this workflow. Instead of manually distributing Playwright shards across CI machines, you can group test cases in a RunList and use Parallel execution to run multiple Playwright test cases simultaneously through Play. The Engineering discussion confirms Parallel as the execution mode for running multiple test flows concurrently.

Try Leapwork Play →

How does Play simplify parallel test distribution?

With Leapwork Play, you do not need to build the same machine-level sharding workflow for tests executed through Play. Play runs multiple test cases concurrently through its execution environment.

The result is similar in purpose to sharding reduce the total time required to execute a large suite by running work concurrently but the execution model is different.

How do you shard Playwright tests across CI machines?

Use Playwright's --shard option with the format:

--shard=<current>/<total>

For example, to divide a suite across three CI machines:

CI machine 1 → npx playwright test --shard=1/3
CI machine 2 → npx playwright test --shard=2/3
CI machine 3 → npx playwright test --shard=3/3

Together, the three jobs execute the complete suite.

The important part is that every CI job uses the same test suite and configuration while receiving a different shard number.

Sharding and Play parallel execution are not the same thing

This distinction is important.

Playwright sharding explicitly divides a test suite into shards that you assign to separate CI jobs or machines.

Play parallel execution runs multiple test cases concurrently through the Play execution workflow.

Requirement	Approach
Explicitly split a Playwright suite across CI machines	Playwright `--shard`
Control which shard each CI job executes	Playwright `--shard=current/total`
Run multiple Playwright test cases concurrently through Play	Play RunList with Parallel execution
Avoid managing browser execution across multiple CI workers for the Play workflow	Run the tests through Play

So Play is not changing how Playwright's --shard option works. It provides another way to scale concurrent Playwright execution without requiring the test author to manually distribute those tests across CI machines.

How Play extends the Playwright scaling workflow

With Playwright sharding	With Leapwork Play
Divide the suite into shards	Add the required test cases to a RunList
Assign each shard to a CI machine/job	Configure the RunList for Parallel execution
Maintain Playwright/browser execution on the CI workers	Run the Playwright tests through Play's execution workflow
Coordinate multiple CI jobs	Work with the RunList as the execution unit
Collect results from the distributed jobs	Review the test case results from the Play run

Play complements Playwright by providing the execution layer around the tests, while Playwright remains the underlying test technology.

How to trigger a Playwright run when a build is ready

Trigger a Leapwork Play RunList from your CI/CD pipeline after the application build or deployment is ready.

The workflow is:

Build or deploy → Trigger Play RunList → Play executes the tests → Check run status

Use the Play trigger API with a trigger secret:

X-Trigger-Secret: <secret>

or:

Authorization: Bearer <secret>

The CI/CD pipeline handles the trigger and monitors the result, while Leapwork Play handles the browser test execution.

How to run Playwright tests in Azure DevOps

The same CI/CD trigger pattern can be used with Azure DevOps. Instead of running the Playwright browser execution directly on the Azure DevOps agent, the pipeline can trigger a Leapwork Play RunList through the Play trigger API.

The workflow is:

Azure DevOps pipeline → Trigger Play RunList → Play executes the tests → Check run status

Authenticate the request using the required trigger secret:

X-Trigger-Secret: <secret>

or:

Authorization: Bearer <secret>

The Azure DevOps pipeline handles the trigger and monitors the result, while Leapwork Play handles the browser test execution.

How to keep tests independent during parallel execution

Use this checklist before increasing Playwright shards or parallel workers:

Identify shared state. Look for anything more than one test can create, update, delete, or depend on.
Give each test or shard its own data. Use unique users, orders, files, authentication state, and application records.
Clean up after each test. Make sure one shard does not depend on data created or removed by another shard.
Run the suite in parallel locally or in CI. Hidden dependencies often appear only when tests stop running sequentially.

Unsafe setup	Parallel-safe setup
Shard/Test A updates User 1. Shard/Test B deletes User 1. These tests can fail depending on execution order.	Shard/Test A uses User A. Shard/Test B uses User B. Each test owns its data, so the tests can run in any order.

Unsafe setup

Parallel-safe setup

Shard/Test A updates User 1.

Shard/Test B deletes User 1.

These tests can fail depending on execution order.

Shard/Test A uses User A.

Shard/Test B uses User B.

Each test owns its data, so the tests can run in any order.

Before increasing the number of shards, confirm that every test can create, use, and clean up its own data without depending on another shard.

How many shards should you use?

Use this approach to decide how many shards to run:

Start with a small shard count.
Run the test suite and measure whether execution time improves.
Increase the shard count only if the faster execution time justifies the extra CI jobs and execution environments.

For direct Playwright execution:

npx playwright test --shard=1/4

This command runs the current CI job as shard 1 of 4.

For Play execution: configure Parallel execution in the RunList instead of translating the Playwright shard count directly into Play. Use the Engineering material as the source for Parallel execution across multiple flows; it does not confirm a one-to-one relationship between Play parallel capacity and Playwright shard counts.

Best practices

Use Play RunLists with Parallel execution when you want Play to manage concurrent execution of multiple Playwright test cases.
Use Playwright --shard when you specifically need to distribute the suite across CI machines.
Keep tests independent before increasing concurrency.
Avoid shared mutable test data between shards or parallel tests.
Make sure each Playwright shard uses the same project and test configuration.
Increase shard or parallel execution counts gradually and measure the result.
Investigate tests that pass sequentially but fail when execution is distributed.

Troubleshooting

Problem	What to check
Some tests never run	Check that every shard number is included exactly once
Same tests appear in multiple CI jobs	Verify the `current/total` shard configuration
Tests fail only after sharding	Check shared data, accounts, state, or environment differences
One shard takes much longer	Check whether the suite is distributed unevenly
Parallel Play execution exposes failures	Check whether the test cases share mutable state
Increasing shards does not improve runtime	Check CI startup overhead, test distribution, and available resources

Frequently asked questions

What is Playwright sharding?

Sharding divides a Playwright test suite into smaller groups that can run independently, typically across multiple CI jobs or machines.

How do I run four Playwright shards?

Run one shard from each CI job:

Is Play parallel execution the same as Playwright sharding?

No. Playwright sharding explicitly divides the suite using --shard. Play's demonstrated workflow uses a RunList with Parallel execution to run multiple test cases concurrently.

How does Leapwork Play help scale Playwright execution?

Add Playwright test cases to a RunList and configure Parallel execution. Play then handles concurrent execution through the Play workflow rather than requiring the test author to manually distribute those test cases across CI machines.

Do tests need to be independent when sharding?

Yes. Tests that share mutable users, data, files, or application state can interfere with one another when they execute concurrently.