/testdriver-caching

name: testdriver:caching
description: How TestDriver learns your app and caches what it discovers for instant, deterministic replays

<!-- Generated from caching.mdx. DO NOT EDIT. -->

After the agent [explored your app](/generating-tests), TestDriver keeps what it found. TestDriver caches each element that the AI vision agent finds. It uses a vision fingerprint. This is a perceptual hash of the screen state at the element location. On the next run, TestDriver matches against that cache. It does not call the AI again. Tests that pass replay quickly, in the same way each time, and at a low cost.

This learning makes TestDriver fast. The cache makes the test run a maximum of **1.7x faster**. It does not do the same AI vision analysis again. The agent thinks only when it sees something new.

// First run: builds cache
await testdriver.find('submit button');

// Second run: exact match
await testdriver.find('submit button');

Automatic Caching

TestDriver enables learning automatically. You do not need configuration. TestDriver computes the cache key from these. The cache key is the fingerprint that TestDriver uses to know what it learned:

• **File hash**: The SHA-256 hash of the test file contents
• **Selector prompt**: The exact text description that you give to `find()`
• **Screenshot context**: The perceptual hash of the present screen state
• **Platform**: The operating system and the browser version

When you change your test file, the hash changes automatically. This makes the old cache entries not valid. Then TestDriver does a new AI analysis with your new test logic.

import { test } from 'vitest';
import { chrome } from 'testdriverai/presets';

test('auto-cached test', async (context) => {
  const { testdriver } = await chrome(context, {
    url: 'https://example.com'
  });

  // First call: AI analyzes screen, saves to cache
  await testdriver.find('More information link'); // 2.1s

  // Second call: cache hit, instant response
  await testdriver.find('More information link'); // 12ms ⚡
});

Managing the Cache

You can clear the cache in the TestDriver console. There, you also find previews of cached elements, the input prompts, and analytics on the cache hit rates.

<Card href="https://console.testdriver.ai/cache" title="TestDriver Cache" icon="database"> Manage and clear your test cache from the TestDriver console. </Card>

Debugging Cache Hits and Misses

You can track what TestDriver has learned by inspecting cache performance in your tests:

test('monitor cache performance', async (context) => {
  const { testdriver } = await chrome(context, { url });

  const element = await testdriver.find('submit button');

  if (element.cacheHit) {
    console.log('✅ Cache hit - instant response');
    console.log('Strategy:', element.cacheStrategy); // 'exact', 'pixeldiff', or 'template'
    console.log('Similarity:', `${(element.similarity * 100).toFixed(1)}%`);
    console.log('Cache age:', element.cacheCreatedAt);
  } else {
    console.log('⏱️  Cache miss - AI analysis performed');
    console.log('New cache entry created');
  }
});

Configuring the Cache

You can configure how TestDriver learns globally when initializing TestDriver:

import { TestDriver } from 'testdriverai';

const testdriver = new TestDriver({
  apiKey: process.env.TD_API_KEY,
  cacheKey: 'my-test-suite', // cache-key for this instance
  cacheDefaults: {
    threshold: 0.05,      // 95% similarity
  }
});

It's also possible to override cache settings per `find()` call:

// Default: 95% similarity required
await testdriver.find('submit button');

// Explicit strict threshold
await testdriver.find('submit button', {
  cacheThreshold: 0.01 // 99% similarity
});

Caching with Variables

Custom cache keys prevent cache pollution when using variables in prompts, dramatically improving cache hit rates—so TestDriver reuses what it learned even when your data changes.

// ❌ Without cache key - creates new cache for each variable value
const email = 'user@example.com';
await testdriver.find(`input for ${email}`); // Cache miss every time

// ✅ With cache key - reuses cache regardless of variable
const email = 'user@example.com';
await testdriver.find(`input for ${email}`, {
  cacheKey: 'email-input'
});

// Also useful for dynamic IDs, names, or other changing data
const orderId = generateOrderId();
await testdriver.find(`order ${orderId} status`, {
  cacheKey: 'order-status'  // Same cache for all orders
});

Next

<Card href="/copilot/running-tests" title="Run" icon="play"> Now that TestDriver has learned your app, run your tests in CI and locally—replaying the cache for fast, deterministic results. </Card>