​
Overview

TestDriver enables cloud-based testing using TestDriver’s infrastructure directly through the CLI. This guide will walk you through the steps to configure TestDriver for GitHub actions, but the principles apply to other CI/CD platforms as well.

​
Step 1: Get Your API key

To execute TestDriver actions on our virtual machines, you’ll need an API key. Follow these steps to retrieve and configure your API key:
  1. Upgrade Your Account: Ensure you have a paid TestDriver account.
  2. Log In: Go to the Team Page in your TestDriver dashboard.
  3. Copy Your API Key: Locate and copy your API key.
  4. Add the API Key as a GitHub Secret:
  • Navigate to your repository settings in GitHub.
  • Add a new secret named TD_API_KEY and paste your API key.

​
Step 2: Create your workflow

Now it’s time to create your first TestDriver workflow. Add the following configuration to .github/workflows/testdriver.yaml: 
name: TestDriver

permissions:
  actions: read
  contents: read
  statuses: write
  pull-requests: write

on:
  pull_request: # Run on every pull request event
  schedule:
    - cron: "0 * * * *" # Run every hour
  push:
    branches:
      - main # Run on merge to the main branch
  workflow_dispatch: # Manual trigger

jobs:
  test:
    name: "TestDriver"
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run TestDriver tests
        run: npx testdriverai@latset run testdriver/testdriver.yaml
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}
          FORCE_COLOR: "3"

​
Key points:

  • Trigger Conditions: The on section defines when the workflow runs (for example, pull requests, scheduled events, or manual triggers).
  • API Key: The TD_API_KEY environment variable uses the secret for authentication.
  • Test Execution: TestDriver is called directly with your test commands.

​
Step 3: Deploy the workflow

Save the workflow file, create a new branch, and push it to your repository. Then, create a pull request to trigger the workflow. 
git checkout -b testdriver
git commit -am 'Add TestDriver workflow'
git push origin testdriver
gh pr create --web

​
How it works

  1. Trigger: The GitHub workflow is triggered based on the conditions defined in the on section.
  2. Code Checkout: The current branch’s code is checked out in the GitHub runner.
  3. CLI Installation: The TestDriver CLI is installed globally using npm.
  4. Authentication: The TD_API_KEY environment variable authenticates your account.
  5. VM Setup: An ephemeral virtual machine is spawned on TestDriver’s infrastructure.
  6. Code Cloning: The current branch’s code is cloned onto the VM.
  7. Dashcam Recording: Dashcam begins recording the test execution.
  8. Test Execution: The TestDriver CLI executes your commands on the cloud VM.
  9. Test Summary: TestDriver summarizes the test and sets the exit code based on the pass or fail state.
  10. Cleanup: The VM is destroyed, and all data is wiped.

​
Additional features

  • Multiple Commands: You can run multiple TestDriver commands in sequence within your workflow.
  • Environment Variables: Pass custom environment variables to your tests.
  • Staging Workflows: A common workflow involves waiting for staging to deploy before executing tests.

​
Output

For details on interpreting the output of TestDriver, refer to the CLI Output Documentation.

​
Notes

  • TestDriver CLI provides a simple and direct way to run cloud-based testing in your CI/CD pipelines.
  • Ensure your API key is securely stored as a GitHub secret.
  • The CLI automatically handles authentication and cloud VM provisioning when the TD_API_KEY is provided.
  • For advanced workflows, consider using multiple TestDriver commands or custom environment variables.