/testdriver-ci-cd

name: testdriver:ci-cd
description: Run TestDriver tests in CI/CD with parallel execution and cross-platform support

<!-- Generated from ci-cd.mdx. DO NOT EDIT. -->

TestDriver integrates with the common CI providers. It lets you do automated end-to-end tests on each push and pull request.

Authentication

On **GitHub Actions, use OIDC** through the published `testdriverai/action`. Then there is no `TD_API_KEY` secret to store, copy, or change. The action shows that the workflow runs in your org. TestDriver changes that proof for your team's key at run time. See the GitHub Actions tab below.

For other CI providers (or self-hosted runners without OIDC), use a stored API key from [console.testdriver.ai/settings](https://console.testdriver.ai/settings). Add it as a `TD_API_KEY` secret in the settings of your CI provider.

<Note> Never commit your API key in the code. Always use OIDC or the secrets management of your CI provider. </Note>

CI Provider Examples

<Tabs> <Tab title="GitHub Actions">

Authenticate with OIDC via `testdriverai/action` (recommended)

Use the published [`testdriverai/action`](https://github.com/testdriverai/action). It makes the OIDC token, changes it for your team's API key, and exports `TD_API_KEY` for the steps that come after. **There is no `TD_API_KEY` secret to store or change.**

<Note> Do this one time: authorize the [TestDriver GitHub App](https://console.testdriver.ai) for your org. Then the org → team binding exists. If your org authorized the App before OIDC support was available, authorize it again one time. If the App is not authorized, the action fails with a console link. (Or it uses the `api-key` secret if you give one.) </Note>

    name: TestDriver Tests

    on:
      push:
        branches: [main]
      pull_request:
        branches: [main]

    jobs:
      test:
        runs-on: ubuntu-latest
        permissions:
          id-token: write   # REQUIRED to mint an OIDC token
          contents: read

        steps:
          - uses: actions/checkout@v4

          - uses: actions/setup-node@v4
            with:
              node-version: '20'
              cache: 'npm'

          - run: npm ci

          - name: Authenticate to TestDriver
            uses: testdriverai/action@stable   # pin @stable / @canary / @test to your SDK channel
            with:
              api-key: ${{ secrets.TD_API_KEY }}   # optional fallback if OIDC isn't set up

          - name: Run TestDriver tests
            run: npx vitest run

Stored-key fallback

Only if you can't use OIDC (e.g. self-hosted runners without an OIDC provider). Add the key as a secret and pass it via `env`:

1. Navigate to your GitHub repository 2. Go to **Settings** → **Secrets and variables** → **Actions** 3. Click **New repository secret** 4. Name: `TD_API_KEY`, Value: your API key 5. Click **Add secret**

Basic Workflow

Create `.github/workflows/testdriver.yml`:

    name: TestDriver Tests

    on:
      push:
        branches: [main]
      pull_request:
        branches: [main]

    jobs:
      test:
        runs-on: ubuntu-latest
        
        steps:
          - uses: actions/checkout@v4
          
          - uses: actions/setup-node@v4
            with:
              node-version: '20'
              cache: 'npm'
          
          - run: npm ci
          
          - name: Run TestDriver tests
            env:
              TD_API_KEY: ${{ secrets.TD_API_KEY }}
            run: vitest --run

Parallel Execution

Use matrix strategy to run tests in parallel:

    name: TestDriver Tests (Parallel)

    on: [push, pull_request]

    jobs:
      test:
        runs-on: ubuntu-latest
        strategy:
          fail-fast: false
          matrix:
            shard: [1, 2, 3, 4]
        
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '20'
              cache: 'npm'
          - run: npm ci
          - name: Run tests (shard ${{ matrix.shard }}/4)
            env:
              TD_API_KEY: ${{ secrets.TD_API_KEY }}
            run: vitest --run --shard=${{ matrix.shard }}/4

Multi-Platform Testing

    name: TestDriver Tests (Multi-Platform)

    on: [push, pull_request]

    jobs:
      test:
        runs-on: ubuntu-latest
        strategy:
          fail-fast: false
          matrix:
            td-os: [linux, windows]
        
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '20'
              cache: 'npm'
          - run: npm ci
          - name: Run tests on ${{ matrix.td-os }}
            env:
              TD_API_KEY: ${{ secrets.TD_API_KEY }}
              TD_OS: ${{ matrix.td-os }}
            run: vitest --run

</Tab>

<Tab title="GitLab CI">

Adding Secrets

1. Go to your GitLab project 2. Navigate to **Settings** → **CI/CD** → **Variables** 3. Click **Add variable** 4. Key: `TD_API_KEY`, Value: your API key 5. Check **Mask variable** and click **Add variable**

Basic Pipeline

Create `.gitlab-ci.yml`:

    stages:
      - test

    testdriver:
      stage: test
      image: node:20
      cache:
        paths:
          - node_modules/
      script:
        - npm ci
        - vitest --run
      variables:
        TD_API_KEY: $TD_API_KEY

Parallel Execution

    stages:
      - test

    .testdriver-base:
      stage: test
      image: node:20
      cache:
        paths:
          - node_modules/
      before_script:
        - npm ci
      variables: