Prevent

Prevent regressions by letting TestDriver run and repair itself on every change. Once you’ve explored, taught it your app, run it, validated outcomes, adapted to your UI, and learned to debug with screenshots, the last step is closing the loop: wire TestDriver into your pull requests so regressions never reach production. Your AI agent can run tests on every PR, investigate failures, and propose fixes — and you can drive all of it from GitHub itself, whether you’re at your desk or on your phone.

Use TestDriver in GitHub

TestDriver works directly in GitHub’s web interface and mobile app. The same MCP server that powers VS Code integration also works in GitHub, letting you create and manage tests from anywhere.

How It Works

When you add a TestDriver agent file to your repository at .github/agents/testdriver.agent.md, GitHub Copilot can use TestDriver’s MCP tools directly in:

GitHub.com (web browser)
GitHub Mobile app (iOS/Android)
Pull request conversations
Issue comments

Using TestDriver in GitHub Web

Navigate to Your Repository

Open your repository on GitHub.com. Make sure you have the TestDriver agent file at .github/agents/testdriver.agent.md.

Start a Copilot Chat

Click the Copilot icon in the GitHub interface to open a chat. You can find this in:

The repository’s Code tab
Pull request pages
Issue pages

Invoke the TestDriver Agent

Start your message with @testdriver:

@testdriver Create a test that verifies the homepage loads correctly at https://myapp.com

The agent will spawn a sandbox environment and begin executing, just like in VS Code.

View Screenshots in Chat

As the test runs, screenshots appear directly in the chat. You can see what the AI sees and provide guidance if needed.

Creating Tests from PR Comments

You can create tests directly from pull request reviews. Comment on a PR and mention Copilot:

@copilot create a TestDriver test that verifies this new feature works.
Test the checkout flow with a guest user.

Copilot will:

Use the TestDriver MCP server
Create a test based on your description
Commit the test file to the PR branch

This is useful for:

Adding test coverage during code review
Verifying bug fixes before merging
Creating regression tests for new features

Creating Tests from Issues

You can also create tests from issue comments:

@copilot Use TestDriver to create a test that reproduces this bug.
Navigate to /settings, change the theme, and verify it persists after refresh.

The test will be created in a new branch and linked to the issue.

Mobile App Support

The GitHub Mobile app supports Copilot chat, which means you can use TestDriver from your phone:

Open the GitHub app
Navigate to your repository
Tap the Copilot icon
Type @testdriver followed by your request

Screenshots and test progress appear in the chat, letting you create and debug tests on the go.

Example: PR Review Workflow

Here’s a complete workflow for adding tests during code review:

Developer Opens PR

A developer opens a pull request with a new feature.

Reviewer Requests Tests

The reviewer comments:

@copilot Create a TestDriver test for this user registration flow.
Test both successful registration and validation errors.

Copilot Creates Tests

Copilot spawns TestDriver, creates the tests, and commits them to the PR branch.

Tests Run in CI

The new tests run automatically in CI, validating the feature works as expected.

Agent File Reference

The agent file at .github/agents/testdriver.agent.md contains the configuration for GitHub Copilot to use TestDriver. Here’s the structure:

---
name: testdriver
description: An expert at creating and refining automated tests using TestDriver.ai
mcp-servers:
  testdriver:
    command: npx
    args:
      - -p
      - testdriverai
      - testdriverai-mcp
    env:
      TD_API_KEY: ${TD_API_KEY}
---

# TestDriver Expert

You are an expert at writing automated tests using TestDriver...

The TD_API_KEY is pulled from your repository secrets when running in GitHub Actions or from your environment when using the web interface.

Make sure TD_API_KEY is set in your repository secrets for CI workflows. Go to Settings → Secrets and variables → Actions to add it.

Auto-Healing Tests

Auto-healing tests automatically fix themselves when your application changes. By integrating an AI coding agent with TestDriver in your CI pipeline, you can have AI investigate test failures and propose fixes. The example below uses GitHub Copilot in GitHub Actions, but the same approach works with any AI agent that can run TestDriver’s MCP server.

How It Works

When a test fails in CI:

GitHub Actions detects the failure
The AI agent spawns TestDriver with access to the MCP server
The agent investigates by running the failing test and analyzing what changed
The agent creates a fix by updating the test code
A pull request is opened with the proposed changes for review

Setting Up Auto-Healing

Add Repository Secrets

Add your TestDriver API key to your repository secrets:

Go to Settings → Secrets and variables → Actions
Click New repository secret
Add TD_API_KEY with your API key value

Create the Auto-Heal Workflow

Add a GitHub Actions workflow that triggers on test failures:

.github/workflows/auto-heal.yml

name: Auto-Heal Tests

on:
  workflow_run:
    workflows: ["Tests"]  # Your main test workflow
    types: [completed]
    branches: [main]

jobs:
  auto-heal:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm ci

      - name: Run failing tests and capture output
        id: tests
        continue-on-error: true
        run: |
          vitest run 2>&1 | tee test-output.txt
          echo "output<<EOF" >> $GITHUB_OUTPUT
          cat test-output.txt >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}

      - name: Invoke Copilot to fix tests
        uses: github/copilot-action@v1
        with:
          prompt: |
            @testdriver The following tests failed:

            ${{ steps.tests.outputs.output }}

            Please investigate each failure by:
            1. Running the failing test
            2. Analyzing what changed in the UI or behavior
            3. Updating the test code to fix the issue

            Create a commit with your changes.
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v5
        with:
          title: "Auto-heal: Fix failing tests"
          body: |
            This PR was automatically generated by the auto-heal workflow.

            ## Changes
            The following tests were updated to fix failures detected in CI.

            ## Review
            Please review the changes carefully before merging.
          branch: auto-heal/${{ github.run_id }}
          commit-message: "fix: auto-heal failing tests"

Configure Test Workflow

Make sure your main test workflow has a name that matches the workflows trigger:

.github/workflows/tests.yml

name: Tests  # Must match the workflow_run trigger

on:
  push:
    branches: [main]
  pull_request:

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

Example: Button Text Change

Here’s what auto-healing looks like when a button’s text changes:

Application Changes

A developer changes a button’s text from “Submit” to “Send”:

<!-- Before -->
<button>Submit</button>

<!-- After -->
<button>Send</button>

Test Fails

The test fails because it’s looking for the old text:

// This now fails
const submitButton = await testdriver.find("Submit button");

Auto-Heal Triggers

The auto-heal workflow runs, and the AI agent investigates:

The test is looking for a "Submit button" but I see a "Send button"
on the page. The button functionality is the same, just the text changed.
I'll update the test to use the new text.

PR Created

A pull request is opened with the fix:

// Updated by auto-heal
const submitButton = await testdriver.find("Send button");

Configuration Options

Selective Auto-Healing

You can limit auto-healing to specific test files or patterns:

- name: Run failing tests
  run: |
    # Only heal tests in the e2e directory
    vitest run tests/e2e/ 2>&1 | tee test-output.txt

Manual Approval

For safety, you can require manual approval before auto-heal runs:

jobs:
  auto-heal:
    environment: auto-heal  # Requires approval

Configure the environment in Settings → Environments with required reviewers.

Limiting Changes

Add instructions to constrain what the AI can change:

- name: Invoke Copilot to fix tests
  uses: github/copilot-action@v1
  with:
    prompt: |
      @testdriver Fix the failing tests.

      Rules:
      - Only update element selectors and text matching
      - Do not change test logic or assertions
      - Do not add or remove tests
      - Keep changes minimal

Best Practices

Always review auto-heal PRs

Auto-heal is a tool, not a replacement for human judgment. Review all changes before merging to ensure the test still validates what you intended.

Use descriptive element descriptions

Tests with clear, semantic descriptions are easier for the AI to heal:

// ✅ Good - describes purpose
await testdriver.find("primary call-to-action button in the hero section");

// ❌ Bad - too vague
await testdriver.find("button");

Set up notifications

Configure GitHub notifications or Slack integration to be alerted when auto-heal PRs are created.

Track heal rate

Monitor how often tests need healing. High heal rates may indicate:

Tests are too brittle
Application is changing rapidly
Element descriptions need improvement

Limitations

Auto-healing works best for:

Element text changes
Layout and styling updates
Minor UI restructuring

It may struggle with:

Major workflow changes
New features requiring new assertions
Complex multi-step interactions

For significant changes, create new tests by going back to Explore and generating them with the TestDriver agent.

View Your Runs

Open the TestDriver console to monitor test runs, healing PRs, and CI results across your projects.

Overview

Guide

Scaling

Actions

SDK Reference

Use TestDriver in GitHub

How It Works

Using TestDriver in GitHub Web

Creating Tests from PR Comments

Creating Tests from Issues

Mobile App Support

Example: PR Review Workflow

Agent File Reference

Auto-Healing Tests

How It Works

Setting Up Auto-Healing

Example: Button Text Change

Configuration Options

Selective Auto-Healing

Manual Approval

Limiting Changes

Best Practices

Limitations

View Your Runs

​Use TestDriver in GitHub

​How It Works

​Using TestDriver in GitHub Web

​Creating Tests from PR Comments

​Creating Tests from Issues

​Mobile App Support

​Example: PR Review Workflow

​Agent File Reference

​Auto-Healing Tests

​How It Works

​Setting Up Auto-Healing

​Example: Button Text Change

​Configuration Options

​Selective Auto-Healing

​Manual Approval

​Limiting Changes

​Best Practices

​Limitations

View Your Runs

Use TestDriver in GitHub

How It Works

Using TestDriver in GitHub Web

Creating Tests from PR Comments

Creating Tests from Issues

Mobile App Support

Example: PR Review Workflow

Agent File Reference

Auto-Healing Tests

How It Works

Setting Up Auto-Healing

Example: Button Text Change

Configuration Options

Selective Auto-Healing

Manual Approval

Limiting Changes

Best Practices

Limitations