This guide explains how to set up TestDriver in CI/CD pipelines, using GitHub Actions as an example. The same principles can be applied to other CI/CD platforms like GitLab CI, Jenkins, or CircleCI.

​
Prerequisites

  1. Add API key to secrets: Obtain your API key from TestDriver and store it as a CI/CD secret as TD_API_KEY. Also make sure to add the TD_WEBSITE secret to the repository with the value of the website you are testing if its a web based application.
  2. Test Files: Ensure your test files are saved in the testdriver/ directory of your repository.

​
Create a CI/CD workflow

This example uses GitHub Actions, but the same approach can be adapted for other CI/CD platforms:
  1. Create a new file in your repository: .github/workflows/testdriver.yaml.
If you have already initialized the project with npx testdriverai@latest init, the workflow file will already be created.
  1. Add the following workflow configuration:

​
Example GitHub Actions workflow

.github/workflows/testdriver.yaml
name: TestDriver / Run / Regressions

on:
  push:
    branches: ["main"]
  pull_request:
  workflow_dispatch:
  schedule:
    - cron: "0 13 * * *" # Every day at 1 PM UTC (adjust if needed for timezone)

permissions:
  contents: read
  pull-requests: read

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

      - name: Run TestDriver
        run: npx testdriverai@latest run testdriver/testdriver.yaml
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}
          TD_WEBSITE: ${{ secrets.TD_WEBSITE }}

​
Trigger the workflow

  1. Push changes to the main branch or open a pull request.
  2. Alternatively, manually trigger the workflow from the Actions tab in your GitHub repository.
  3. The scheduled trigger will run tests daily at 1 PM UTC for regression testing.

​
View results

  1. Navigate to the Actions tab in your GitHub repository (or equivalent CI/CD dashboard).
  2. Select the workflow run to view the test results. You will also find the link to the test recording at the end of the run, the url is of the format: https://app.dashcam.io/replay/1234567890
You can also intregate our supported reporting platform to get more currated results.
For other CI/CD platforms, adapt the workflow syntax to match your platform’s requirements while keeping the same TestDriver CLI commands and environment variables.

​
Debugging tests

TestDriver provides a powerful debugging interface through its platform. This interface allows you to analyze test runs, identify failures, and optimize your test suite with detailed visual and textual feedback.

​
1. Step-by-step execution logs

  • View each step of the test execution, including:
    • The action performed (for example, clicking a button, typing text).
    • The expected outcome (for example, verifying a specific element is visible).
    • The result (pass, fail, or skipped).
  • Logs provide detailed context for each step, making it easier to pinpoint where and why a test failed.

​
2. Visual feedback

  • Screenshots: See what the application looked like at each step of the test.
  • GIF Previews: Watch a replay of the entire test execution to understand the flow and identify UI issues.
  • Highlighting: Elements interacted with during the test are highlighted in screenshots, helping you verify that the correct elements were targeted.

​
3. Error details

  • For failed steps, TestDriver provides:
    • Error messages: Detailed descriptions of what went wrong (for example, “Element not found”).
    • Stack traces: For advanced debugging of backend or script-related issues.
    • Suggestions: Recommendations for fixing common issues, such as adjusting prompts or improving element descriptions.

​
4. Test history

  • Access the history of test runs to:
    • Compare results across different builds or environments.
    • Identify flaky tests by analyzing patterns in failures.
    • Track improvements or regressions over time.

​
5. Environment context

  • View the environment details for each test run, including:
    • Operating system and browser version.
    • Screen resolution and viewport size.
    • Network conditions (if applicable).

​
6. Collaboration tools

  • Share test results with your team by generating a shareable link.
  • Add comments or annotations to specific steps to facilitate discussions and debugging.

​
How it works

  1. Trigger: The GitHub workflow is triggered based on the conditions defined in the on section.
  2. Fetch the test files: The test files are fetched from the repository based off the current branch.
  3. Running the tests: The TestDriver CLI is installed and the tests are run via the run command.
  4. Authentication: The TD_API_KEY environment variable authenticates your account.
  5. Dashcam Recording: Dashcam begins recording the test execution.
  6. Test Execution: The TestDriver CLI executes your commands on the cloud VM.
  7. Test Summary: TestDriver summarizes the test and sets the exit code based on the pass or fail state.
  8. Cleanup: The recording is uploaded to the TestDriver platform and the VM is destroyed, and all data is wiped.

​
Additional features

  • Parallel testing: You can run multiple tests in parallel. The number of parallel instances depends on the plan you are on.
  • Environment Variables: Pass custom environment variables to configure credentials that are required for the tests.
  • Chaining Workflows: A common workflow involves waiting for staging to deploy and testing against the staging environment by passing in the deployed url as TD_WEBSITE or the staging build’s installation url depending on the kind of application you are testing.