Integrating into CI/CD

TestDriver integrates seamlessly with popular CI providers, enabling automated end-to-end testing on every push and pull request.

Adding Your API Key

TestDriver requires an API key to authenticate with the TestDriver cloud. Store this securely as a secret in your CI provider.

Get Your API Key

Go to console.testdriver.ai/team and copy your team’s API key

Add Secret to Your CI Provider

Add TD_API_KEY as a secret environment variable in your CI provider’s settings.

Never commit your API key directly in code. Always use your CI provider’s secrets management.

CI Provider Examples

GitHub Actions
GitLab CI
CircleCI
Azure Pipelines
Jenkins

Adding Secrets

Navigate to your GitHub repository
Go to Settings → Secrets and variables → Actions
Click New repository secret
Name: TD_API_KEY, Value: your API key
Click Add secret

Basic Workflow

Create .github/workflows/testdriver.yml:

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

.github/workflows/testdriver-parallel.yml

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

.github/workflows/testdriver-multiplatform.yml

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

Adding Secrets

Go to your GitLab project
Navigate to Settings → CI/CD → Variables
Click Add variable
Key: TD_API_KEY, Value: your API key
Check Mask variable and click Add variable

Basic Pipeline

Create .gitlab-ci.yml:

.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

.gitlab-ci.yml

stages:
  - test

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

testdriver-shard-1:
  extends: .testdriver-base
  script:
    - vitest --run --shard=1/4

testdriver-shard-2:
  extends: .testdriver-base
  script:
    - vitest --run --shard=2/4

testdriver-shard-3:
  extends: .testdriver-base
  script:
    - vitest --run --shard=3/4

testdriver-shard-4:
  extends: .testdriver-base
  script:
    - vitest --run --shard=4/4

Multi-Platform Testing

.gitlab-ci.yml

stages:
  - test

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

testdriver-linux:
  extends: .testdriver-base
  variables:
    TD_OS: linux
  script:
    - vitest --run

testdriver-windows:
  extends: .testdriver-base
  variables:
    TD_OS: windows
  script:
    - vitest --run

Adding Secrets

Go to your CircleCI project
Click Project Settings → Environment Variables
Click Add Environment Variable
Name: TD_API_KEY, Value: your API key

Basic Config

Create .circleci/config.yml:

.circleci/config.yml

version: 2.1

jobs:
  test:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - restore_cache:
          keys:
            - npm-deps-{{ checksum "package-lock.json" }}
      - run: npm ci
      - save_cache:
          key: npm-deps-{{ checksum "package-lock.json" }}
          paths:
            - node_modules
      - run:
          name: Run TestDriver tests
          command: vitest --run
          environment:
            TD_API_KEY: ${TD_API_KEY}

workflows:
  test:
    jobs:
      - test

Parallel Execution

.circleci/config.yml

version: 2.1

jobs:
  test:
    docker:
      - image: cimg/node:20.0
    parallelism: 4
    steps:
      - checkout
      - restore_cache:
          keys:
            - npm-deps-{{ checksum "package-lock.json" }}
      - run: npm ci
      - save_cache:
          key: npm-deps-{{ checksum "package-lock.json" }}
          paths:
            - node_modules
      - run:
          name: Run TestDriver tests
          command: |
            vitest --run --shard=$((CIRCLE_NODE_INDEX + 1))/$CIRCLE_NODE_TOTAL
          environment:
            TD_API_KEY: ${TD_API_KEY}

workflows:
  test:
    jobs:
      - test

Multi-Platform Testing

.circleci/config.yml

version: 2.1

jobs:
  test:
    docker:
      - image: cimg/node:20.0
    parameters:
      td-os:
        type: string
    steps:
      - checkout
      - run: npm ci
      - run:
          name: Run TestDriver tests on << parameters.td-os >>
          command: vitest --run
          environment:
            TD_API_KEY: ${TD_API_KEY}
            TD_OS: << parameters.td-os >>

workflows:
  test:
    jobs:
      - test:
          td-os: linux
      - test:
          td-os: windows

Adding Secrets

Go to your Azure DevOps project
Navigate to Pipelines → Library → Variable groups
Create a new variable group or edit existing
Add variable: TD_API_KEY with your API key
Click the lock icon to make it secret

Basic Pipeline

Create azure-pipelines.yml:

azure-pipelines.yml

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
    displayName: 'Setup Node.js'

  - script: npm ci
    displayName: 'Install dependencies'

  - script: vitest --run
    displayName: 'Run TestDriver tests'
    env:
      TD_API_KEY: $(TD_API_KEY)

Parallel Execution

azure-pipelines.yml

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

strategy:
  matrix:
    shard1:
      SHARD: '1/4'
    shard2:
      SHARD: '2/4'
    shard3:
      SHARD: '3/4'
    shard4:
      SHARD: '4/4'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'

  - script: npm ci
    displayName: 'Install dependencies'

  - script: vitest --run --shard=$(SHARD)
    displayName: 'Run TestDriver tests'
    env:
      TD_API_KEY: $(TD_API_KEY)

Multi-Platform Testing

azure-pipelines.yml

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

strategy:
  matrix:
    linux:
      TD_OS: 'linux'
    windows:
      TD_OS: 'windows'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'

  - script: npm ci
    displayName: 'Install dependencies'

  - script: vitest --run
    displayName: 'Run TestDriver tests on $(TD_OS)'
    env:
      TD_API_KEY: $(TD_API_KEY)
      TD_OS: $(TD_OS)

Adding Secrets

Go to Manage Jenkins → Credentials
Select the appropriate domain
Click Add Credentials
Kind: Secret text
ID: td-api-key, Secret: your API key

Basic Pipeline

Create Jenkinsfile:

Jenkinsfile

pipeline {
    agent {
        docker {
            image 'node:20'
        }
    }
    
    environment {
        TD_API_KEY = credentials('td-api-key')
    }
    
    stages {
        stage('Install') {
            steps {
                sh 'npm ci'
            }
        }
        
        stage('Test') {
            steps {
                sh 'vitest --run'
            }
        }
    }
}

Parallel Execution

Jenkinsfile

pipeline {
    agent none
    
    environment {
        TD_API_KEY = credentials('td-api-key')
    }
    
    stages {
        stage('Test') {
            parallel {
                stage('Shard 1') {
                    agent { docker { image 'node:20' } }
                    steps {
                        sh 'npm ci'
                        sh 'vitest --run --shard=1/4'
                    }
                }
                stage('Shard 2') {
                    agent { docker { image 'node:20' } }
                    steps {
                        sh 'npm ci'
                        sh 'vitest --run --shard=2/4'
                    }
                }
                stage('Shard 3') {
                    agent { docker { image 'node:20' } }
                    steps {
                        sh 'npm ci'
                        sh 'vitest --run --shard=3/4'
                    }
                }
                stage('Shard 4') {
                    agent { docker { image 'node:20' } }
                    steps {
                        sh 'npm ci'
                        sh 'vitest --run --shard=4/4'
                    }
                }
            }
        }
    }
}

Multi-Platform Testing

Jenkinsfile

pipeline {
    agent none
    
    environment {
        TD_API_KEY = credentials('td-api-key')
    }
    
    stages {
        stage('Test') {
            parallel {
                stage('Linux') {
                    agent { docker { image 'node:20' } }
                    environment {
                        TD_OS = 'linux'
                    }
                    steps {
                        sh 'npm ci'
                        sh 'vitest --run'
                    }
                }
                stage('Windows') {
                    agent { docker { image 'node:20' } }
                    environment {
                        TD_OS = 'windows'
                    }
                    steps {
                        sh 'npm ci'
                        sh 'vitest --run'
                    }
                }
            }
        }
    }
}

Reading Platform in Tests

When using multi-platform testing, read the TD_OS environment variable in your test:

tests/cross-platform.test.mjs

import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/vitest/hooks";

describe("Cross-platform tests", () => {
  it("should work on both Linux and Windows", async (context) => {
    const os = process.env.TD_OS || 'linux';
    
    const testdriver = TestDriver(context, { 
      os: os  // 'linux' or 'windows'
    });
    
    await testdriver.provision.chrome({
      url: 'https://example.com',
    });

    const result = await testdriver.assert("the page loaded successfully");
    expect(result).toBeTruthy();
  });
});

Viewing Results

All test runs are automatically recorded and visible in your TestDriver dashboard at console.testdriver.ai:

All test runs with pass/fail status
Video replays of each test
Error messages and screenshots on failure
Git commit and branch information
Duration trends over time

Overview

GitHub Copilot

Guide

Running Tests

Scaling

Actions

SDK Reference

Integrating into CI/CD

Adding Your API Key

CI Provider Examples

Adding Secrets

Basic Workflow

Parallel Execution

Multi-Platform Testing

Adding Secrets

Basic Pipeline

Parallel Execution

Multi-Platform Testing

Adding Secrets

Basic Config

Parallel Execution

Multi-Platform Testing

Adding Secrets

Basic Pipeline

Parallel Execution

Multi-Platform Testing

Adding Secrets

Basic Pipeline

Parallel Execution

Multi-Platform Testing

Reading Platform in Tests

Viewing Results

Overview

GitHub Copilot

Guide

Running Tests

Scaling

Actions

SDK Reference

Documentation Index

​Adding Your API Key

​CI Provider Examples

​Adding Secrets

​Basic Workflow

​Parallel Execution

​Multi-Platform Testing

​Adding Secrets

​Basic Pipeline

​Parallel Execution

​Multi-Platform Testing

​Adding Secrets

​Basic Config

​Parallel Execution

​Multi-Platform Testing

​Adding Secrets

​Basic Pipeline

​Parallel Execution

​Multi-Platform Testing

​Adding Secrets

​Basic Pipeline

​Parallel Execution

​Multi-Platform Testing

​Reading Platform in Tests

​Viewing Results

Adding Your API Key

CI Provider Examples

Adding Secrets

Basic Workflow

Parallel Execution

Multi-Platform Testing

Adding Secrets

Basic Pipeline

Parallel Execution

Multi-Platform Testing

Adding Secrets

Basic Config

Parallel Execution

Multi-Platform Testing

Adding Secrets

Basic Pipeline

Parallel Execution

Multi-Platform Testing

Adding Secrets

Basic Pipeline

Parallel Execution

Multi-Platform Testing

Reading Platform in Tests

Viewing Results