Node.js CLI for Playwright

@testdino/playwright streams Playwright test results to TestDino as a run executes. Results appear on the dashboard during the run, with no separate upload step. Paste the AI prompt below, or follow Installation and Set up.

Prerequisites

Node.js >= 18.0.0
@playwright/test >= 1.52.0
TestDino API token (generate one)
Git initialized repository (for commit and branch metadata)

Set up with an AI agent

Use this pre-built prompt to integrate @testdino/playwright into your project.

Open in Cursor

Quick Reference

Topic	Link	Best for
Install the package	Installation	First-time setup
Add TestDino to your config	Set up	Streaming results
CLI flags	CLI flags	Passing options on `tdpw`
Config file	Config file	`testdino.config.ts` and reporter options
Label a run	Run-level tags	`--tags` on `tdpw`, not Playwright
Group sharded runs	Sharded runs	CI with shards
Merge separate CI jobs	Split mode	Hand-partitioned jobs
Distribute across machines	Swarm mode	Balancing a suite at runtime
Re-run past failures	Re-run failed tests	`--rerun` and `--from-run`

Installation

npm install @testdino/playwright

View @testdino/playwright on npm ↗.

Set up

Add TestDino to the reporter array in your Playwright config. This is the only entry TestDino needs. Other reporters (html, list) are optional and yours to keep.

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [
    ['@testdino/playwright', {
      token: process.env.TESTDINO_TOKEN,
    }],
  ],
});

Set your token and run tests the way you already do. Results stream to TestDino as the run executes.

export TESTDINO_TOKEN="your-api-key"
npx playwright test

Prefer not to edit your config?

Run tdpw test instead of npx playwright test. Same result, no config change.

npx tdpw test -t "$TESTDINO_TOKEN"

It wraps npx playwright test, so any Playwright flag passes through, for example npx tdpw test --project=chromium --shard=1/3.

CLI flags

Set the token with -t or the TESTDINO_TOKEN environment variable. All other flags are optional.

npx tdpw test -t "$TESTDINO_TOKEN" --tags "regression,smoke"

These flags belong to tdpw test. Playwright does not define them, except --debug, which tdpw consumes for TestDino logs. Pass Playwright flags through tdpw as usual: npx tdpw test --tags regression,smoke --project=chromium.

Flag	Environment variable	Config file / reporter	Description
`-t, --token <token>`	`TESTDINO_TOKEN`	`token`	API token. Required.
`--ci-run-id <id>`	`TESTDINO_CI_RUN_ID`	`ciRunId`	Group sharded jobs into a single test run.
`--split <current/total>`	-	-	This job’s split position, for example `1/3`. Command only.
`--split-id <id>`	`TESTDINO_SPLIT_ID`	`splitId`	Group ID shared by every job of one split run. Required with `--split`.
`--tags <csv>`	`TESTDINO_TAGS`	`tags`	Run labels, comma-separated. The flag, `TESTDINO_TAGS`, and `testdino.config.ts` require version 2.7.6 or later.
`--rerun <scope>`	-	-	Re-run a past test run’s `failed`, `flaky`, or `failed-and-flaky` test cases. Command only.
`--from-run <runId>`	-	-	The test run to re-run from. Required with `--rerun`. Command only.
`--test-ids <ids>`	-	-	Comma-separated test case ids to run, overriding the `--rerun` scope. Command only.
`--exclude-ids <ids>`	-	-	Comma-separated test case ids to drop from the `--rerun` scope. Command only.
`--rerun-tags <csv>`	`TESTDINO_RERUN_TAGS`	-	Run labels added to a `--rerun` test run, on top of `--tags`. Refused without `--rerun`; the env var is ignored on a normal test run. Requires version 2.7.6 or later.
`--no-artifacts`	-	`artifacts: false`	Skip screenshot, video, and trace uploads.
`--debug`	`TESTDINO_DEBUG`	`debug`	Print TestDino debug logs. Not forwarded to Playwright.

First non-empty source wins: CLI flag, then testdino.config.ts, then Playwright reporter options, then the environment variable. --split has no config or env equivalent. Learn how to set run labels in Run-level tags. Learn how to partition jobs in Split mode.

error: unknown option '--tags'

You passed a TestDino flag to npx playwright test. Playwright does not define --tags, --token, --ci-run-id, --split, --split-id, or --no-artifacts, so it exits before the test run starts.Use the TestDino wrapper:

npx tdpw test -t "$TESTDINO_TOKEN" --tags "regression,smoke"

To keep npx playwright test, set the matching field in the reporter options in playwright.config. That path does not read testdino.config.ts or any TestDino environment variable except TESTDINO_TOKEN. --split has no alternative: it is tdpw only.

--debug did not open the Playwright Inspector

tdpw consumes --debug for TestDino logs, including after --. It does not forward it to Playwright. Open the Playwright Inspector with Playwright’s PWDEBUG environment variable instead:

PWDEBUG=1 npx tdpw test

TESTDINO_DEBUG=1 PWDEBUG=1 npx tdpw test enables both.

Config file

Place testdino.config.ts or testdino.config.js in the project root. tdpw reads this file; npx playwright test does not. The same fields work as options on ['@testdino/playwright', { ... }] in playwright.config.

testdino.config.ts

export default {
  token: process.env.TESTDINO_TOKEN,
  tags: ['regression', 'smoke'],
  debug: false,
  artifacts: true,
};

Field	Type	Description
`token`	`string`	API token. Required unless `TESTDINO_TOKEN` or `-t` is set.
`ciRunId`	`string`	Group sharded jobs into a single test run.
`splitId`	`string`	Group ID for split mode. Does not set `--split`.
`tags`	`string[]`	Run labels. Empty values are dropped.
`debug`	`boolean`	Print TestDino debug logs. Default `false`.
`artifacts`	`boolean`	Upload screenshots, videos, and traces. Default `true`.

Run-level tags

--tags labels the whole test run in TestDino. It does not select which test cases Playwright executes. Test-case tags (@smoke in test code, --grep) stay on Playwright.

npx tdpw test -t "$TESTDINO_TOKEN" --tags "regression,smoke"

--tags is a tdpw flag. TESTDINO_TAGS and tags in testdino.config.ts are also read by tdpw only. To keep npx playwright test, set tags in the Playwright reporter options.

npx playwright test --tags exits with error: unknown option '--tags'. Use npx tdpw test --tags, or tags in the reporter options. Labels set through tdpw (the flag, TESTDINO_TAGS, or testdino.config.ts) reach the test run from version 2.7.6; earlier versions drop them.

Environment
testdino.config.ts
playwright.config.ts

TESTDINO_TAGS=regression,smoke npx tdpw test

testdino.config.ts

export default {
  token: process.env.TESTDINO_TOKEN,
  tags: ['regression', 'smoke'],
};

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [
    ['@testdino/playwright', {
      token: process.env.TESTDINO_TOKEN,
      tags: ['regression', 'smoke'],
    }],
  ],
});

Source	When it applies
`npx tdpw test --tags <csv>`	Command-line flag on the TestDino wrapper
`tags` in `testdino.config.ts`	Config file in the project root, read by `tdpw`
`tags` in Playwright reporter options	`npx playwright test` or `tdpw`, with the reporter installed
`TESTDINO_TAGS`	Comma-separated env var, read by `tdpw`

First non-empty source wins: CLI flag, then testdino.config.ts, then Playwright reporter options, then TESTDINO_TAGS. These labels appear as run-level chips on Test Runs. They are separate from test annotations.

Sharded runs

Pass the same --ci-run-id to every shard. TestDino groups them into a single logical run on the dashboard.

npx tdpw test --ci-run-id "$CI_RUN_ID" -- --shard=1/4

In the config path, set ciRunId in the reporter options and pass --shard to npx playwright test as usual. npx playwright test does not read TESTDINO_CI_RUN_ID; only tdpw does.

Split mode

Sharding needs every job to run the same command. When your jobs differ, for example an API project on one runner and browser tests on another, use split mode instead. Each job tags its results with --split i/N and a shared --split-id, and TestDino merges them into one test run.

npx tdpw test -t "$TESTDINO_TOKEN" \
  --split 1/2 --split-id "$SPLIT_ID" \
  --project=api tests/checkout-api.spec.ts

--split labels the results. It does not select which test cases run, so assign them yourself with spec paths, --project, or --grep. Requires version 2.3.0 or later. Learn how to build a CI matrix and read the Splits panel in Split mode.

Swarm mode

Sharding and split mode fix each machine’s workload before the run starts, so 1 slow machine holds the test run open. Swarm mode hands each machine the next spec file when it frees up. It is its own command, tdpw swarm, in 2 modes.

# Once per pipeline: start the swarm and capture its ID.
npx tdpw swarm --machines 4 --out swarm.json

# On every machine: join with that ID.
npx tdpw swarm --id "$SWARM_ID" --machine-id "$MACHINE"

Set TESTDINO_MACHINE_ID per matrix leg so a machine keeps 1 identity for the whole run. Requires version 2.10.0 or later and a Team or Enterprise plan. Learn about every flag, the CI matrix, and the Machines panel in Swarm mode.

Re-run failed tests

Re-run only the test cases that failed or were flaky in a past test run:

npx tdpw test -t "$TESTDINO_TOKEN" \
  --rerun failed --from-run test_run_a66fa0ee4f7a28ef5986e907

--rerun takes failed, flaky, or failed-and-flaky. Narrow the selection with --test-ids or --exclude-ids. Put the re-run flags before --. --rerun cannot be combined with --shard, --split, --split-id, --grep, --grep-invert, --last-failed, --test-list, or --test-list-invert. The re-run keeps the original test run’s tags; add more with --rerun-tags (version 2.7.6 or later). Requires version 2.7.0 or later, and Playwright 1.56 or later. An earlier version of the CLI passes the flag through to Playwright, which exits with error: unknown option '--rerun'. Learn how to start one from the dashboard or an AI agent in Re-run failed tests.

On a GitHub Actions retry

From version 2.7.8, when TestDino re-runs failed jobs inside the original GitHub run, each job runs only the test cases that failed in it, with no flag and no change to your command. The job log shows it:

TestDino: GitHub retry (attempt 2) — running the 4 test(s) that failed in run #118, not the full suite.

Otherwise the job runs your command unchanged and the log line that starts with TestDino: running the full command on this GitHub retry gives the reason. That happens when a test case has no result from the earlier attempt, when the same Playwright project runs in more than 1 job, when the retry came from GitHub’s own Re-run buttons, when the command already passes --test-list or --list, or when TestDino cannot be reached. See Run only the failed test cases in each job.

Test Controls

The reporter applies the project’s Test Controls rules when the test run ends: failures of quarantined tests stop failing the build, and a critical test that passes only on retry fails it. Requires version 2.8.0 or later. No flag or config is needed.

Environment variables

Variable	Config field	Description
`TESTDINO_TOKEN`	`token`	Authentication token
`TESTDINO_CI_RUN_ID`	`ciRunId`	Group sharded jobs into a single test run
`TESTDINO_SPLIT_ID`	`splitId`	Group ID for split mode
`TESTDINO_MACHINES`	-	Machine count when starting a swarm
`TESTDINO_MACHINE_ID`	-	This machine’s identity when joining a swarm
`TESTDINO_TAGS`	`tags`	Comma-separated run labels
`TESTDINO_RERUN_TAGS`	-	Comma-separated run labels added to a `--rerun` test run. Ignored on a normal test run
`TESTDINO_DEBUG`	`debug`	Set to `true` or `1` to print TestDino debug logs

npx playwright test reads only TESTDINO_TOKEN. The other variables take effect when you run tdpw. There is no environment variable for --split, which is command-only.

What gets collected

Category	Data
Git	Branch, commit hash, author, message, repository URL
CI	Provider, build ID, PR details
System	OS, CPU, memory, Node.js version
Playwright	Version, workers, projects, shard info
Artifacts	Screenshots, videos, traces (unless `--no-artifacts`)
Annotations	`testdino:` annotations from test metadata (guide)

Use in CI/CD

Set TESTDINO_TOKEN as a CI secret, keep TestDino in your playwright.config, and run npx playwright test. Each guide below has a full pipeline config with sharding and troubleshooting.

GitHub Actions

GitLab

TeamCity

Azure DevOps

CircleCI

AWS CodeBuild

Jenkins

Troubleshooting

Token is required but not provided

Set the token via --token, the TESTDINO_TOKEN environment variable, or the reporter option in playwright.config. Confirm it is set:

echo $TESTDINO_TOKEN

Generate a new token from API Keys if the issue persists.

Execution limit reached

Your organization used its executions for this billing cycle. Tests still run, but the run is not saved and does not appear in TestDino.To resume recording runs, upgrade your plan, or on Pro and Team plans an Owner or Admin can add executions for this cycle. Otherwise recording resumes when the limit resets on your billing date. See Plan and seat limits.

Stream dropped, switched to HTTP fallback

Expected behavior. If the streaming connection drops, events fall back to HTTP delivery automatically. Your tests are never affected.

Real-Time Test Streaming

How real-time streaming works and when to use it

Generate API Keys

Create and manage tokens for the CLI and CI

Getting Started

Connect Your Pipeline

Test Intelligence

Guides

AI-Native Testing

Organization & Access

Integrations

Test Management

Data Security & Privacy

Resources

Prerequisites

Set up with an AI agent

Quick Reference

Installation

Set up

CLI flags

Config file

Run-level tags

Sharded runs

Split mode

Swarm mode

Re-run failed tests

On a GitHub Actions retry

Test Controls

Environment variables

What gets collected

Use in CI/CD

GitHub Actions

GitLab

TeamCity

Azure DevOps

CircleCI

AWS CodeBuild

Jenkins

Troubleshooting

Real-Time Test Streaming

Generate API Keys

​Prerequisites

​Set up with an AI agent

​Quick Reference

​Installation

​Set up

​CLI flags

​Config file

​Run-level tags

​Sharded runs

​Split mode

​Swarm mode

​Re-run failed tests

​On a GitHub Actions retry

​Test Controls

​Environment variables

​What gets collected

​Use in CI/CD

GitHub Actions

GitLab

TeamCity

Azure DevOps

CircleCI

AWS CodeBuild

Jenkins

​Troubleshooting

​Related

Real-Time Test Streaming

Generate API Keys

Prerequisites

Set up with an AI agent

Quick Reference

Installation

Set up

CLI flags

Config file

Run-level tags

Sharded runs

Split mode

Swarm mode

Re-run failed tests

On a GitHub Actions retry

Test Controls

Environment variables

What gets collected

Use in CI/CD

Troubleshooting

Related