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

# Reporter for the e2e Framework by TesterArmy

> Install @testdino/e2e to stream test runs from the e2e framework by TesterArmy to TestDino, with sharded runs, split mode, and re-runs.

`@testdino/e2e` streams each test run from the [e2e framework by TesterArmy ↗](https://github.com/tester-army/e2e) to TestDino while it executes. The test run appears on the dashboard when e2e starts it, and each test case arrives with its retries, steps, errors, console output, and artifacts as it finishes. Learn what each test case records in [How e2e Reporting Works](https://docs.testdino.com/cli/testdino-e2e-how-it-works.md).

e2e is an open-source framework for end-to-end tests of web and mobile apps. Use this reporter if your tests live in `*.e2e.ts` files and run with `npx e2e run`.

> [!NOTE]
>
> Real-time streaming and re-runs need `@testdino/e2e` 1.1.0 or later. With 1.0.x, the test run appears once it finishes.

For Playwright, use the [Node.js CLI](https://docs.testdino.com/cli/testdino-playwright-nodejs) instead.

## Prerequisites

* `e2e` `>= 0.16.0` and `< 1`, installed in your project
* Node.js version your `e2e` release supports. For example, `e2e` 0.21.3 needs `^22.22.3` or `>= 24.8.0`. The reporter itself needs `>= 22.12.0`.
* TestDino API key ([generate one](https://docs.testdino.com/guides/generate-api-keys.md))
* Git initialized repository (for commit and branch metadata)
* `@types/node`, if you type-check your project with `tsc`

## Installation

```bash theme={null}
npm install -D @testdino/e2e
```

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

## Set up

Add `testdino()` to the `reporters` array in your e2e config. Other reporters, such as `list`, are optional and yours to keep.

```typescript e2e.config.ts theme={null}
import type { E2EConfig } from 'e2e';
import { testdino } from '@testdino/e2e';

export default {
  targets: [/* your targets */],
  reporters: ['list', testdino()],
} satisfies E2EConfig;
```

Set your API key and run your tests:

> [tab] macOS / Linux
>
> ```bash theme={null}
> export TESTDINO_TOKEN="your-api-key"
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={null}
> $env:TESTDINO_TOKEN = "your-api-key"
> ```

The variable lasts until you close the terminal, so run your tests in the same terminal.

```bash theme={null}
npx e2e run
```

When the run finishes, the TestDino line of the e2e output shows a link to the test run, or the number of test cases it uploaded.

## Reporter options

Pass options to `testdino()`. An option set in the config takes precedence over its environment variable.

| Option | Environment variable | Description |
| :- | :- | :- |
| `token` | `TESTDINO_TOKEN` | Project API key. Without it, the reporter uploads nothing. |
| `ciRunId` | `TESTDINO_CI_RUN_ID` | Groups the shards of one run into a single test run. |
| `split` | `TESTDINO_SPLIT` | Split position, for example `2/3`. Needs `splitId`. |
| `splitId` | `TESTDINO_SPLIT_ID` | ID shared by every job of one split run. |
| `tags` | None | Run-level tags, for example `['nightly']`. |
| `artifacts` | None | Set `false` to keep screenshots, videos, and walkthroughs local. |

```typescript e2e.config.ts theme={null}
reporters: ['list', testdino({ tags: ['nightly'], artifacts: false })],
```

## Sharded runs

Set the same `TESTDINO_CI_RUN_ID` on every shard. TestDino merges the shards into 1 test run.

```bash theme={null}
TESTDINO_CI_RUN_ID="$CI_RUN_ID" npx e2e run --shard 1/2
TESTDINO_CI_RUN_ID="$CI_RUN_ID" npx e2e run --shard 2/2
```

On GitHub Actions, use `${{ github.run_id }}-${{ github.run_attempt }}` as the ID. A shard started without `TESTDINO_CI_RUN_ID` uploads as its own test run.

## Split mode

When your jobs run different files, use split mode instead of sharding. Give each job its position and the same split ID. TestDino merges the jobs into 1 test run.

```bash theme={null}
TESTDINO_SPLIT=1/2 TESTDINO_SPLIT_ID="$SPLIT_ID" npx e2e run tests/checkout.e2e.ts
TESTDINO_SPLIT=2/2 TESTDINO_SPLIT_ID="$SPLIT_ID" npx e2e run tests/login.e2e.ts
```

Set both variables. Learn how to read the Splits panel in [Split mode](https://docs.testdino.com/guides/playwright-split-mode.md).

## Run through TestDino in CI

`testdino-e2e run` runs `e2e run` and adds what a reporter cannot do on its own. Use it in CI in place of `npx e2e run`, and put e2e's own options after `--`:

```yaml theme={null}
- name: Run e2e tests
  run: npx -p @testdino/e2e testdino-e2e run -- --workers 2
  env:
    TESTDINO_TOKEN: ${{ secrets.TESTDINO_TOKEN }}
```

* **Test Controls decide the build result.** A test run whose only failures are quarantined, or match a known error, exits `0`. A critical test case that passed only on retry exits `1`. Exit codes `2`, `3`, `4`, and `130` never change. With plain `npx e2e run`, Test Controls do not change the exit code.
* **A GitHub Actions retry runs only what failed.** When you re-run a test run's failures from TestDino, each retried job runs only its own failed test cases. A job that cannot be narrowed safely, for example one passing `--repeat-each`, runs in full and says why. A retry started in GitHub itself, not from TestDino, also runs in full.
* **Run a stored test selection** with `--selection`, as **Run automated tests** does:

  ```bash theme={null}
  npx -p @testdino/e2e testdino-e2e run --selection "$TD_SELECTION"
  ```

  The selection is checked against your checkout first. A selection that would also run test cases nobody selected, or none of whose test cases exist, runs nothing and tells TestDino why. Missing test cases are skipped, or fail the job after the rest ran, as the selection says. A selected setup test runs when a selected test case needs it. A selection of only setup tests runs nothing, because e2e cannot run a setup test alone.

## Re-run failed tests

`testdino-e2e rerun` runs again only the test cases that failed in a TestDino test run. The re-run is a new test run, linked to the original. Run it from the folder with your `e2e.config.ts`, with `TESTDINO_TOKEN` set:

```bash theme={null}
npx -p @testdino/e2e testdino-e2e rerun --from-run "$TEST_RUN_ID"
```

Set `TEST_RUN_ID` to the test run's ID, or copy the full command from the test run's page (below). `-p @testdino/e2e` makes npx use this package, never an unrelated package named `testdino-e2e`.

| Option | Default | Description |
| :- | :- | :- |
| `--from-run` | None | The test run whose test cases run again. Required. |
| `--scope` | `failed` | `failed` (including timed out), `flaky` (passed only after a retry), or `failed-and-flaky`. |
| `--test-ids` | None | Comma-separated test IDs to run instead of the scope. |
| `--exclude-ids` | None | Comma-separated test IDs to leave out of the scope. |
| `--rerun-tags` | None | Comma-separated tags to add to the re-run. |
| `-- <options>` | None | Passed to `e2e run`, for example `-- --workers 2`. |

The command prints `TestDino re-run: 3 of 4 failed test(s) from run …`, then e2e's own output, and ends with e2e's exit code. Each test case runs on the target it failed on. Test cases that are not on your checkout are skipped and named. e2e cannot run a setup test alone, so re-running one also runs the test cases that use it. When nothing is left to re-run, it exits `0` without starting e2e. If TestDino cannot say which test cases to run, it exits `1` and runs nothing. Stopping the command with Ctrl+C or `docker stop` stops the test cases it started.

### Start a re-run from the dashboard

**Re-run** is in the action row on a test run's page. It appears when the test run has finished with at least 1 failed or flaky test case and was uploaded by `@testdino/e2e` 1.1.0 or later. The panel offers **Failed**, **Flaky**, **Both**, and **Custom**, and you can add tags. Run it against **This commit**, **Latest**, or **Another branch**, or choose **Run manually** to copy the command. On GitHub Actions, **This commit** runs the failed jobs again inside the original run, and jobs that use `testdino-e2e run` run only their failed test cases. For how re-runs appear in the run list and how the test cases are chosen, see [Re-run Failed Tests](https://docs.testdino.com/guides/debug-playwright-failures/rerun-failed-tests.md).

### Re-run from an AI agent

For an e2e test run, the `get_rerun_selection` [MCP tool](https://docs.testdino.com/mcp/tools-reference.md#get_rerun_selection) returns the same `testdino-e2e rerun` command, for your agent to run in the project. `rerun_test` starts the re-run in CI, as it does for a Playwright test run.

## Differences from Playwright test runs

e2e test cases appear as they start, traces arrive as walkthroughs in Markdown, and [Test Controls](https://docs.testdino.com/guides/test-controls.md) change the build result only under `testdino-e2e run`. See the full list in [How e2e Reporting Works](https://docs.testdino.com/cli/testdino-e2e-how-it-works.md#differences-from-playwright-test-runs).

## Troubleshooting

> [accordion] skipped (TESTDINO\_TOKEN is not set)
>
> The reporter found no API key. Set `TESTDINO_TOKEN` in the environment that runs `npx e2e run`, or pass `token` to `testdino()`. Generate a new key from [API Keys](https://docs.testdino.com/guides/generate-api-keys.md) if needed.

> [accordion] not recorded (the project is over its execution limit)
>
> Your organization used its executions for this billing cycle. Tests still run, but the test run is not saved. To resume recording, upgrade your plan, or on Pro and Team plans an Owner or Admin can [add executions](https://docs.testdino.com/platform/billing-and-usage/manage-billing.md#add-executions-for-this-cycle) for this cycle.

> [accordion] not uploaded (no event channel the server offered could be reached)
>
> The machine running the tests could not reach TestDino. Check that it allows outbound connections to TestDino, then run the tests again.

> [accordion] shards uploaded as separate runs: set TESTDINO\_CI\_RUN\_ID to merge them
>
> A shard ran without `TESTDINO_CI_RUN_ID`. Set the same value on every shard, as in [Sharded runs](#sharded-runs).

> [accordion] split ignored: a split position and TESTDINO\_SPLIT\_ID are needed together
>
> Only 1 of `TESTDINO_SPLIT` and `TESTDINO_SPLIT_ID` was set. Set both on every job, as in [Split mode](#split-mode).

> [accordion] TestDino re-run: nothing to re-run
>
> The test run has no test cases in the scope you chose. The command exits `0` without starting e2e. Pick another `--scope`, or check the test run on the dashboard.

> [accordion] TestDino re-run: Run … has not finished yet
>
> A test run's failed test cases are known only once it finishes. Wait for it to finish, then run the command again.

> [accordion] TestDino re-run: Run … is unknown, belongs to another project, or is not accessible with this token
>
> Check the test run ID, and that `TESTDINO_TOKEN` is an API key of the project the test run belongs to.

> [accordion] TestDino re-run: Some of run …'s tests can only be told apart by file and line
>
> Some test cases in the selection can be picked only by their file and line, and the re-run command does not select by line, so nothing runs. The message lists their locations. Run each one with `npx e2e run <file>:<line>` instead.

> [accordion] TestDino re-run: … tests are too many to pass to e2e at once on Windows
>
> The selection does not fit on a Windows command line. Re-run a narrower `--scope`, or run the command on macOS or Linux.

> [accordion] TestDino re-run: e2e is not installed in this project
>
> The command did not find e2e from the current folder. Run it from the folder with your project's `package.json`.

## Related

> [card] [How e2e Reporting Works](https://docs.testdino.com/cli/testdino-e2e-how-it-works.md)
>
> What TestDino records for each e2e test case, and the limits

> [card] [Configuration](https://docs.testdino.com/platform/playwright-test-runs/configuration.md)
>
> Review the commit, CI, and targets of a test run

> [card] [Generate API Keys](https://docs.testdino.com/guides/generate-api-keys.md)
>
> Create and manage keys for the reporter and CI


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