Skip to main content
Split mode merges several manually partitioned Playwright jobs into one TestDino test run. Each job runs the specs you assign it, tagged with --split i/N, and TestDino aggregates them into a single run with per-split results.
Split mode requires @testdino/playwright 2.3.0 or later. Earlier versions exit with error: unknown option '--split'.

​
Quick Reference

​
Pick split mode or sharding

Sharding and split mode both spread one test run across parallel continuous integration (CI) jobs. They differ in who decides the partition. Use sharding when every job runs the same suite and Playwright balances the load. Use split mode when the jobs differ: an API project on one runner, browser tests on another, or a slow spec isolated so it stops blocking the rest. Split mode and sharding combine. A split can itself be sharded, covered in Shard a split.

​
Group jobs with a split ID

--split-id is the only grouping ID split mode needs. Every job that passes the same split ID joins one test run, and --split i/N identifies each job’s position within it. Together with Playwright’s own --shard, that pair identifies every job in the group, including the shards inside a split. A group of 3 splits where split 2 runs on 2 shards needs 1 split ID across its 4 jobs: Jobs 2 and 3 share a split position, so their shards merge into split 2 rather than becoming separate splits.
--ci-run-id is optional in split mode. The split and shard indexes already identify each job, and the reporter generates a CI run ID when you omit the flag. Pass it only when another system needs to correlate the job by a known ID.

​
Run a split group

Split mode runs from the tdpw test command. --split is a command-line flag with no config file or environment variable equivalent, which keeps a static value from pinning every machine to the same position. Only splitId is also readable from a config file.
--split labels the results TestDino files for this job. It does not select which tests run. Assign the tests yourself with spec paths, --project, or --grep.
The 3 jobs produce one test run on the Test Runs page, labeled SPLITTED, with 3 splits in its Splits panel. Active Test Runs section showing test run #127 with a SPLITTED badge, a segmented progress bar reading Split 2 of 3, and per-split tabs with Split 2 expanded to its shard 1 workers

​
Set the split ID in a config file

splitId is the one split-mode option a config file can carry. Set it there when the group ID is stable, and pass --split per job on the command line.
testdino.config.ts
The command-line --split-id flag wins over a config file value, and TESTDINO_SPLIT_ID applies when neither is set.

​
Configure a CI matrix

One workflow run is one split group. Set the group ID once as TESTDINO_SPLIT_ID at the workflow level so every job inherits it, then give each matrix entry its own --split position. Derive the group ID from a value that is stable across the jobs of a run and distinct across re-runs. In GitHub Actions that is github.run_id paired with github.run_attempt.
.github/workflows/playwright-split.yml
Each job reads the group ID from TESTDINO_SPLIT_ID, so no --split-id flag appears in the command. Splits 1 and 3 run unsharded while split 2 runs across 2 shards, and no CI run ID is passed anywhere. Keep both settings below in place, or the group loses a split: If your provider cancels in-progress jobs on a new push, exclude split jobs from that rule. A cancelled job leaves its split unreported.

​
Shard a split

A split can use Playwright sharding internally. Pass --shard alongside --split, and give every shard of that split the same --split position.
Split 2 then expands in the Splits panel to a per-shard table. Splits in one group are independent: split 1 can be unsharded while split 2 runs across 2 shards, and shard numbering restarts inside each split.

​
CLI flags

Split mode adds 2 flags to tdpw test. Learn about the remaining flags in the Node.js CLI reference. --split and --split-id are required together. Passing one without the other exits with Split mode requires both a position (--split) and a group id. Split positions stay on the command line because a config file value would pin every machine in the matrix to the same position. splitId is the exception: set it in testdino.config.ts or as TESTDINO_SPLIT_ID. --ci-run-id is optional and is not a split-mode flag. It works the same as in a standard run, and split grouping ignores it.

​
Read the Splits panel

A split run carries a SPLITTED badge in the Test Runs list and on the run detail. Its Summary tab shows a Splits section in place of the Shards section, headed with the split count and total test cases. Run detail Summary tab showing the Splits panel with a 2 of 3 reported badge, a passed Split 1 row, a running Split 2 row, and a notice that Split 3 did not report The imbalance badge names the slowest split. Because you assign the specs in split mode, rebalancing means moving specs off that split onto a faster one.

​
When counts are unreliable

If 2 splits report the same test cases, TestDino cannot attribute those cases to one split. The panel shows Per-split counts may be unreliable and dims the per-split totals. Split statuses stay accurate; only the counts are approximate. A split whose cases collapsed into an overlapping split shows its status with no totals of its own. The cause is almost always a spec assigned to more than one job. Each spec belongs to exactly one split. A split that never reports is named under the panel header, and the test run is marked incomplete.

​
Filter by split and shard

Split and shard are independent filters on the Summary tab, and both accept multiple values. Selecting split 2 and shard 1 shows split 2’s test cases that ran on its own shard 1, not every shard 1 in the run. Active filters are reflected in the page URL, so a filtered view is shareable.

​
Watch a split group in real time

Split groups stream like any other test run. The Active Test Runs section shows the group as one run with a segmented progress bar, one segment per split, and per-split tabs for the splits currently executing. Sharded splits nest their shards under the split tab. Progress advances per split as each job reports, so a group whose jobs run concurrently fills in steps rather than smoothly. Aggregate counts stay correct throughout. TestDino finalizes the test run once every declared split has reported. If a split never reports, the group finalizes after an idle grace period of roughly 10 minutes instead of waiting indefinitely. Learn more about streaming in Real-Time Reporting.

​
Troubleshooting

The installed reporter predates split mode. Upgrade to @testdino/playwright 2.3.0 or later:
--split was passed without a group ID. Add --split-id, or set TESTDINO_SPLIT_ID in the environment:
The jobs did not share one group ID. Set it from a CI value that is identical across every job of the run, such as github.run_id, and confirm each job resolved it to the same string.
2 or more splits reported the same test cases. Check the spec paths, --project, and --grep for each split: a spec matched by 2 jobs is reported twice. Split statuses remain accurate while counts stay approximate.
The job for that split ended before reporting, usually a cancelled job, a failed setup step, or a runner timeout. Set fail-fast: false and exclude split jobs from cancel-in-progress concurrency rules.
Shards merge by their --split position. 2 jobs that pass the same --split i/N merge into a single split. Give every split a distinct position, and every shard of that split the same position paired with its own --shard.

Node.js CLI

Flags, environment variables, and sharded runs

Real-Time Reporting

Live progress while a test run executes

Test Runs

Filter runs and read the run detail tabs

CI Setup

Pipeline configs for every CI provider