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

# CircleCI TestDino Setup

> Stream Playwright results from CircleCI to TestDino live, with sharded parallel runs grouped into one run.

Stream Playwright test results to TestDino from CircleCI during the run. `@testdino/playwright` sends results as tests execute, so no separate upload step runs.

## Prerequisites

* A <a href="https://app.testdino.com" target="_blank" rel="noopener noreferrer">TestDino account <Icon icon="arrow-up-right-from-square" size={12} /></a> with a project created
* A TestDino API key ([Generate API Keys](/guides/generate-api-keys))
* <a href="https://github.com/testdino-hq/TestDino-Example" target="_blank" rel="noopener noreferrer">TestDino Example Repository <Icon icon="arrow-up-right-from-square" size={12} /></a> for sample tests and ready-to-use CI configs
* A CircleCI account with access to your repository
* `@testdino/playwright` installed and configured in `playwright.config.ts|js|mjs`:

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

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

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

## Set Up Your API Key

1. Open your project in CircleCI
2. Go to **Project Settings → Environment Variables**
3. Click **Add Environment Variable**
4. Set the name to `TESTDINO_TOKEN`
5. Paste your TestDino API key as the value
6. Save the variable

<Warning>
  **Warning**

  Never commit your API key directly in config files. Always use environment variables.
</Warning>

## Basic Config

<Accordion title=".circleci/config.yml: Basic config">
  ```yaml .circleci/config.yml theme={null}
  version: 2.1

  jobs:
    test:
      docker:
        - image: mcr.microsoft.com/playwright:v1.59.1-noble
      working_directory: ~/project
      environment:
        CI: "true"
      steps:
        - checkout
        - run:
            name: Install dependencies
            command: npm ci
        - run:
            name: Run tests with TestDino
            command: npx playwright test

  workflows:
    test:
      jobs:
        - test
  ```
</Accordion>

<Tip>
  **Tip**

  Set `TESTDINO_TOKEN` in **Project Settings → Environment Variables** so `@testdino/playwright` reads it during the run. Results stream live even when tests fail, so failures land on the dashboard without a `when: always` upload step.
</Tip>

## Sharded Test Runs

For larger test suites, CircleCI parallelism splits tests across multiple containers. Each shard streams its own results, and TestDino groups them into one run when they share a `ci-run-id`.

### How it works

1. CircleCI runs Playwright across 4 shards using `parallelism: 4`
2. Each shard streams its results to TestDino during the run
3. Every shard passes the same `--ci-run-id` so TestDino merges them into a single run
4. No merge or upload job runs after the shards finish

### Full sharded config

<Accordion title=".circleci/config.yml: Sharded config">
  ```yaml .circleci/config.yml theme={null}
  version: 2.1

  jobs:
    test:
      docker:
        - image: mcr.microsoft.com/playwright:v1.59.1-noble
      working_directory: ~/project
      parallelism: 4
      environment:
        CI: "true"
      steps:
        - checkout
        - run:
            name: Install dependencies
            command: npm ci
        - run:
            name: Run shard with TestDino
            command: |
              npx tdpw test --ci-run-id "$CIRCLE_WORKFLOW_ID" -- \
                --shard=$((CIRCLE_NODE_INDEX + 1))/$CIRCLE_NODE_TOTAL

  workflows:
    test:
      jobs:
        - test
  ```
</Accordion>

### Key details

| Config Block                                            | What It Does                                                                                                                               |
| :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `parallelism: 4`                                        | Runs 4 shard containers in parallel                                                                                                        |
| `--shard=$((CIRCLE_NODE_INDEX + 1))/$CIRCLE_NODE_TOTAL` | CircleCI uses 0-based indexing, Playwright uses 1-based                                                                                    |
| `--ci-run-id "$CIRCLE_WORKFLOW_ID"`                     | Groups all shards into one run on the dashboard                                                                                            |
| `TESTDINO_TOKEN`                                        | Read from the project environment variable, used by `@testdino/playwright` to stream results                                               |
| `TESTDINO_SERVER_URL`                                   | Set as a project environment variable to `https://reporter.testdino.com`, or keep `serverUrl` in the `playwright.config` reporter options. |

Set the `ciRunId` reporter option in `playwright.config` to `$CIRCLE_WORKFLOW_ID` if you prefer running `npx playwright test` directly instead of `npx tdpw test`.

## Run Locally

```bash theme={null}
npm ci
npx playwright install --with-deps
export TESTDINO_TOKEN="$TESTDINO_TOKEN"
export TESTDINO_SERVER_URL="https://reporter.testdino.com"
npx playwright test
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Results not appearing on the dashboard">
    Confirm `@testdino/playwright` is in your `playwright.config` `reporter` array and `TESTDINO_TOKEN` is set in the project environment. Results stream during the run, so no separate upload step is required.
  </Accordion>

  <Accordion title="Sharded runs show up as separate runs">
    Pass the same `--ci-run-id "$CIRCLE_WORKFLOW_ID"` (or `ciRunId` reporter option) to every shard. Different values create one run per shard.
  </Accordion>

  <Accordion title="TESTDINO_TOKEN not found">
    Confirm the environment variable is set in **CircleCI → Project Settings → Environment Variables**. Variable names are case-sensitive.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="CI Optimization" icon="gauge-high" href="/guides/playwright-ci-optimization">
    Reduce CI time with smart reruns
  </Card>

  <Card title="Environment Mapping" icon="code-branch" href="/guides/environment-mapping">
    Route test results to Dev, Staging, or Production by branch
  </Card>

  <Card title="Integrations" icon="puzzle-piece" href="/integrations/overview">
    Connect Slack, Jira, Linear, Asana, and more
  </Card>

  <Card title="TestDino MCP" icon="plug" href="/mcp/overview">
    Access test results and fix issues with AI agents
  </Card>
</CardGroup>