Prevent regressions

Catch regressions before they merge, and fix tests when your app changes.

Stop regressions before they reach your main branch.

• Run your tests on every pull request.
• Let the TestDriver agent review each change.
• Ask the agent to fix a test when your app changes.

TestDriver tests don’t use selectors, so many UI changes never break them.

Tests that adapt to UI changes

A TestDriver test describes elements the way a person would, such as “the Sign in button in the header”. It finds them by looking at the screen.

These changes don’t break the test, because the description still matches what’s on screen:

• Restyling a button.
• Moving it.
• Rewriting the markup around it.

A selector-based test would fail on the same change.

When the screen does change, the cache notices that it no longer matches the last passing run. It asks the AI to find the element again and learns its new location for the next run.

Descriptions that say what an element is and where it sits survive change best:

// Survives restyling and layout changes
await testdriver.find('primary Sign up button in the hero section').click();

// Too vague: may match the wrong button after a redesign
await testdriver.find('button').click();

Run tests on every pull request

Run your suite in GitHub Actions, so a change that breaks a flow fails its pull request.

The testdriverai/action step authenticates with GitHub OIDC, so there’s no API key secret to store. npx testdriverai init writes a workflow like this for you:

.github/workflows/testdriver.yml

name: TestDriver.ai Tests

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

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # lets the job mint the OIDC token TestDriver accepts
      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
      - name: Run TestDriver tests
        run: npx vitest run

OIDC needs the TestDriver GitHub app authorized for your organization.

For other CI providers and runner setups, see Run tests in CI/CD.

Review every pull request

With the TestDriver GitHub app installed, the TestDriver agent reviews each pull request when it’s opened and after every push.

• It reads the change for bugs.
• When the change is something a user would see, it runs it in a sandbox to prove what it finds.

This catches regressions that your existing tests don’t cover. See the TestDriver agent for what a review contains.

Fix a test when your app changes

Sometimes a test fails because the app changed on purpose, such as a renamed button or a reworked flow. Ask the TestDriver agent to update the test.

On GitHub, mention it on the pull request or an issue:

@testdriverai The checkout test fails after this redesign because the Submit button is now called Place order. Update the test.

The agent then:

1. Reruns the flow in a sandbox and sees the current screen.
2. Updates the test.
3. Opens a pull request with the fix for you to review.

You can make the same request from your editor through the Claude Code plugin or the VS Code extension.

Review the agent’s fix before you merge it. A test updated to pass may no longer check what you meant. Confirm that the assertions still describe the behavior you want.

When updating a test isn’t enough

Updating a description or an assertion works well when an element is renamed, restyled, or moved.

When a flow changes substantially, such as a new step in checkout or a redesigned form, describe the new flow. Have the agent generate a fresh test instead.

Next steps

Run tests in CI/CD

Set up GitHub Actions and other CI providers.

The TestDriver agent

How the agent reviews pull requests and fixes tests.

Locate elements

Write descriptions that keep working as your UI changes.

Debug a failing test

See what the screen showed when a test failed.