> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testdino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js CLI for Playwright

> Install @testdino/playwright and stream Playwright test results to TestDino live, with config setup, CLI flags, and CI usage.

`@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](/guides/generate-api-keys))
* Git initialized repository (for commit and branch metadata)

## Set up with an AI agent

<Prompt description="Use this pre-built prompt to integrate @testdino/playwright into your project." actions={["copy", "cursor"]}>
  Integrate TestDino into this Playwright (Node.js) project so test results stream live via @testdino/playwright.

  **Install**

  ```bash theme={null}
  npm install @testdino/playwright
  ```

  **Add TestDino to playwright.config.ts|js|mjs, keeping any existing reporter entries:**

  ```typescript theme={null}
  import { defineConfig } from '@playwright/test';

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

  **Run the tests:**

  ```bash theme={null}
  export TESTDINO_TOKEN=your-api-key
  npx playwright test
  ```

  **Rules**

  * Read the token from process.env.TESTDINO\_TOKEN. Never hardcode or commit a real token.
  * Do not add a post-run upload step. Results stream during the run.

  Docs: [https://docs.testdino.com/cli/testdino-playwright-nodejs](https://docs.testdino.com/cli/testdino-playwright-nodejs)
</Prompt>

## Quick Reference

| Topic | Link | Best for |
| :- | :- | :- |
| Install the package | [Installation](#installation) | First-time setup |
| Add TestDino to your config | [Set up](#set-up) | Streaming results |
| CLI flags | [CLI flags](#cli-flags) | Passing options on `tdpw` |
| Config file | [Config file](#config-file) | `testdino.config.ts` and reporter options |
| Label a run | [Run-level tags](#run-level-tags) | `--tags` on `tdpw`, not Playwright |
| Group sharded runs | [Sharded runs](#sharded-runs) | CI with shards |
| Merge separate CI jobs | [Split mode](#split-mode) | Hand-partitioned jobs |
| Re-run past failures | [Re-run failed tests](#re-run-failed-tests) | `--rerun` and `--from-run` |
| Code coverage | [Code coverage](#code-coverage) | Istanbul coverage |

## Installation

```bash theme={null}
npm install @testdino/playwright
```

View `@testdino/playwright` on [npm ↗](https://www.npmjs.com/package/@testdino/playwright).

## 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.

```typescript playwright.config.ts theme={null}
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.

```bash theme={null}
export TESTDINO_TOKEN="$TESTDINO_TOKEN"
npx playwright test
```

<Accordion title="Prefer not to edit your config?">
  Run `tdpw test` instead of `npx playwright test`. Same result, no config change.

  ```bash theme={null}
  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`.
</Accordion>

## CLI flags

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

```bash theme={null}
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. |
| `--coverage` | - | `coverage.enabled` | Collect Istanbul code coverage. |
| `--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. `--coverage` on the CLI only sets `enabled`; `include`, `exclude`, and `thresholds` stay in config. Learn how to set run labels in [Run-level tags](#run-level-tags). Learn how to partition jobs in [Split mode](/guides/playwright-split-mode).

<AccordionGroup>
  <Accordion title="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`, `--coverage`, or `--no-artifacts`, so it exits before the test run starts.

    Use the TestDino wrapper:

    ```bash theme={null}
    npx tdpw test -t "$TESTDINO_TOKEN" --tags "regression,smoke"
    ```

    To keep `npx playwright test`, set the matching environment variable or config field from the table above. For run labels, only `tags` in the reporter options works without `tdpw`. `--split` has no alternative: it is `tdpw` only.
  </Accordion>

  <Accordion title="--debug did not open the Playwright Inspector">
    `tdpw` consumes `--debug` for TestDino logs. It does not forward it to Playwright.

    ```bash theme={null}
    npx tdpw test -- --debug
    ```

    `TESTDINO_DEBUG=1 npx tdpw test -- --debug` enables both.
  </Accordion>
</AccordionGroup>

## Config file

Place `testdino.config.ts` or `testdino.config.js` in the project root. The same fields work as options on `['@testdino/playwright', { ... }]` in `playwright.config`.

```typescript testdino.config.ts theme={null}
export default {
  token: process.env.TESTDINO_TOKEN,
  tags: ['regression', 'smoke'],
  debug: false,
  artifacts: true,
  coverage: {
    enabled: true,
    include: ['src/**'],
    exclude: ['**/node_modules/**'],
    thresholds: {
      lines: 80,
      branches: 60,
      functions: 80,
      statements: 80,
    },
  },
};
```

| 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](/guides/playwright-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`. |
| `coverage` | `object` | Istanbul collection. `enabled` is required when the object is present. |
| `coverage.enabled` | `boolean` | Turn collection on or off. |
| `coverage.include` | `string[]` | Glob patterns to include. |
| `coverage.exclude` | `string[]` | Glob patterns to exclude. |
| `coverage.thresholds` | `object` | `lines`, `branches`, `functions`, `statements` percents. |

Learn coverage setup in [Code Coverage](/guides/playwright-code-coverage).

## 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.

```bash theme={null}
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.

<Note>
  `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.
</Note>

<Tabs>
  <Tab title="Environment">
    ```bash theme={null}
    TESTDINO_TAGS=regression,smoke npx tdpw test
    ```
  </Tab>

  <Tab title="testdino.config.ts">
    ```typescript testdino.config.ts theme={null}
    export default {
      token: process.env.TESTDINO_TOKEN,
      tags: ['regression', 'smoke'],
    };
    ```
  </Tab>

  <Tab title="playwright.config.ts">
    ```typescript playwright.config.ts theme={null}
    import { defineConfig } from '@playwright/test';

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

| 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](/platform/playwright-test-runs#run-level-tags). They are separate from [test annotations](/guides/playwright-test-annotations).

## Sharded runs

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

```bash theme={null}
npx tdpw test --ci-run-id "$CI_RUN_ID" -- --shard=1/4
```

In the config path, set `ciRunId` or `TESTDINO_CI_RUN_ID` and pass `--shard` to `npx playwright test` as usual.

## 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.

```bash theme={null}
npx tdpw test -t "$TESTDINO_TOKEN" \
  --split 1/2 --split-id "$SPLIT_ID" --ci-run-id "$SPLIT_ID-1" \
  --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](/guides/playwright-split-mode).

## Re-run failed tests

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

```bash theme={null}
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`. 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](/guides/debug-playwright-failures/rerun-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:

```text theme={null}
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 [Re-run inside the original GitHub run](/guides/debug-playwright-failures/rerun-failed-tests#re-run-inside-the-original-github-run).

## Code coverage

Instrument your app with Istanbul so it exposes `window.__coverage__`, import the TestDino fixture in your tests, then enable coverage:

```bash theme={null}
npx tdpw test --coverage
```

Coverage merges across shards automatically. Learn more in [Code Coverage](/guides/playwright-code-coverage).

## 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_TAGS` | `tags` | Comma-separated run labels. Read by `tdpw` only |
| `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 |

There is no environment variable for `--split` or `--coverage`. `--split` is command-only. Coverage `include`, `exclude`, and `thresholds` stay in the config file.

## 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](/guides/playwright-test-annotations)) |

## 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.

<div className="integration-cards">
  <CardGroup cols={3}>
    <Card title="GitHub Actions" img="https://mintcdn.com/testdino/Ua7R4RmzUY5yacWr/images/github-svgrepo-com.svg?fit=max&auto=format&n=Ua7R4RmzUY5yacWr&q=85&s=0055a83b6d8abc90fa29d665b6d88e39" href="/guides/playwright-github-actions" width="800" height="800" data-path="images/github-svgrepo-com.svg" />

    <Card title="GitLab" img="https://mintcdn.com/testdino/_W5tZrChGQAb05lF/images/gitlab-logo-500-rgb.svg?fit=max&auto=format&n=_W5tZrChGQAb05lF&q=85&s=0fdfd890fe016b0d6cff99fad0a21684" href="/guides/playwright-gitlab-ci-setup" width="256" height="256" data-path="images/gitlab-logo-500-rgb.svg" />

    <Card title="TeamCity" img="https://mintcdn.com/testdino/_W5tZrChGQAb05lF/images/teamcity-icon.svg?fit=max&auto=format&n=_W5tZrChGQAb05lF&q=85&s=eb2a564c91dcf59db6018127d8103797" href="/guides/playwright-teamcity" width="256" height="256" data-path="images/teamcity-icon.svg" />

    <Card title="Azure DevOps" img="https://mintcdn.com/testdino/JwytUEY7x2_fx041/images/azure-devops.svg?fit=max&auto=format&n=JwytUEY7x2_fx041&q=85&s=f8982ec615ae9abd45220ccf3d31d1fd" href="/guides/playwright-azure-devops-pipeline" width="32" height="32" data-path="images/azure-devops.svg" />

    <Card title="CircleCI" img="https://mintcdn.com/testdino/Ua7R4RmzUY5yacWr/images/Circleci-icon-logo.svg?fit=max&auto=format&n=Ua7R4RmzUY5yacWr&q=85&s=a0c70425c249f47ebccd93e7b89aa6bd" href="/guides/playwright-circle-ci-orb" width="104" height="105" data-path="images/Circleci-icon-logo.svg" />

    <Card title="AWS CodeBuild" img="https://mintcdn.com/testdino/Ua7R4RmzUY5yacWr/images/CodeBuild.svg?fit=max&auto=format&n=Ua7R4RmzUY5yacWr&q=85&s=3182ba12e600efaee867fd7448edeeef" href="/guides/playwright-amazon-codebuild" width="80" height="80" data-path="images/CodeBuild.svg" />

    <Card title="Jenkins" img="https://mintcdn.com/testdino/Ua7R4RmzUY5yacWr/images/jenkins.svg?fit=max&auto=format&n=Ua7R4RmzUY5yacWr&q=85&s=e73a6fd9932bc067d6c2cc2d5e898e61" href="/guides/playwright-jenkins" width="800" height="800" data-path="images/jenkins.svg" />
  </CardGroup>
</div>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    echo $TESTDINO_TOKEN
    ```

    Generate a new token from [API Keys](/guides/generate-api-keys) if the issue persists.
  </Accordion>

  <Accordion title="Execution limit reached">
    Your account reached its monthly quota. Tests continue to run normally. Only streaming to TestDino pauses until the quota resets.

    Upgrade your plan or wait for the monthly reset.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Real-Time Test Streaming" icon="bolt" href="/guides/playwright-real-time-test-streaming">
    How real-time streaming works and when to use it
  </Card>

  <Card title="Generate API Keys" icon="key" href="/guides/generate-api-keys">
    Create and manage tokens for the CLI and CI
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.