Cache

Overview

The cache system speeds up repeated test runs by comparing screenshots to cached results. When the screen hasn’t changed significantly, cached element positions are reused instead of making an AI call. Cache works at two levels:

Screen cache — pixel diff comparison between the current screenshot and the cached screenshot
Element cache — OpenCV template matching to verify the cached element position is still correct

How It Works

On find(), the SDK sends the current screenshot and cache metadata to the API
The API compares the screenshot against previously cached results for the same cacheKey
If the screen pixel diff is within the screen threshold AND the element template match exceeds the element threshold, the cached position is returned
Otherwise, a new AI call is made and the result is cached

Configuration

Constructor Options

const testdriver = new TestDriver({
  cache: {
    enabled: true,
    thresholds: {
      find: {
        screen: 0.05,     // 5% pixel diff allowed (default)
        element: 0.8,     // 80% OpenCV correlation required (default)
      },
      assert: 0.05,       // 5% pixel diff for assertions (default)
    },
  },
  cacheKey: 'my-custom-key',   // overrides auto-generated key
});

CacheConfig | false

Cache configuration object, or false to disable entirely.

Show properties

boolean

default:true

Enable or disable the cache system. Requires a valid cacheKey to actually activate.

CacheThresholds

Threshold configuration for different command types.

Show properties

FindCacheThresholds

Thresholds for find() and findAll().

Show properties

number

Maximum pixel diff percentage allowed between the current screenshot and the cached screenshot. Lower values require a closer match. Range: 0 to 1.

number

Minimum OpenCV template matching correlation required for the cached element crop. Higher values require a closer match. Range: 0 to 1. Only used for find(), not findAll().

number

Maximum pixel diff allowed for assertion cache hits.

string

Unique key for cache lookups. If not provided, an auto-generated key is created from a SHA-256 hash of the calling test file (first 16 hex characters). The cache key changes automatically when your test file changes, providing automatic cache invalidation.

Disabling Cache

// Via constructor
const testdriver = new TestDriver({ cache: false });

// Via environment variable
// TD_NO_CACHE=true npx vitest run

When cache is disabled, all thresholds are set to -1 internally, causing the API to skip cache lookups.

Per-Command Overrides

Override cache thresholds for individual commands:

// Stricter screen matching for this specific find
const el = await testdriver.find('submit button', {
  cache: {
    thresholds: { screen: 0.01, element: 0.95 },
  },
});

// Custom cache key for a specific assertion
await testdriver.assert('dashboard loaded', {
  cache: { threshold: 0.01 },
  cacheKey: 'dashboard-check',
});

Threshold Priority

Thresholds are resolved in priority order (highest wins):

Priority	Source	Example
1 (highest)	Per-command option	`find(desc, { cache: { thresholds: { screen: 0.1 } } })`
2	Legacy number argument	`find(desc, 0.1)`
3	Global constructor config	`new TestDriver({ cache: { thresholds: { find: { screen: 0.1 } } } })`
4 (lowest)	Hard-coded defaults	`screen: 0.05`, `element: 0.8`, `assert: 0.05`

Auto-Generated Cache Key

When you don’t specify a cacheKey, the SDK automatically generates one:

Walks the call stack to find your test file
Reads the file content
Computes a SHA-256 hash of the content
Uses the first 16 hex characters as the cache key

This means:

Same test file → same cache key → cache hits
Modified test file → different hash → automatic cache invalidation
Different test files → different keys → isolated caches

// Auto-generated cache key from test file hash
const testdriver = new TestDriver();
// cacheKey = "a3f2b1c4d5e6f7a8" (auto)

// Manual override
const testdriver = new TestDriver({ cacheKey: 'login-test-v2' });

Template Matching (OpenCV)

Element cache validation uses OpenCV’s normalized cross-correlation coefficient (TM_CCOEFF_NORMED) to verify that the cached element is still visible at the expected position. Algorithm:

Load the cached element crop (needle) and current screenshot (haystack)
Run cv.matchTemplate() with TM_CCOEFF_NORMED
Binary threshold at the configured element threshold
Find contours to extract match positions
Return matches with { x, y, width, height, centerX, centerY }

Scale factors tried: [1, 0.5, 2, 0.75, 1.25, 1.5] Thresholds tried: [0.9, 0.8, 0.7] (picks highest matching threshold) This accounts for minor scaling differences between screenshots taken at different times or resolutions.

Cache Partitioning

Cache entries are partitioned by:

cacheKey — identifies the test file
os — operating system (linux, windows, darwin)
resolution — screen resolution

This means cache from a Linux run won’t be used for a Windows run, even with the same cache key.

Debugging Cache

API responses include cache metadata:

Field	Description
`cacheHit`	`true` if cache was used
`similarity`	Pixel diff percentage between screenshots
`cacheSimilarity`	OpenCV template match score

Use getDebugInfo() on an element to inspect cache results:

const el = await testdriver.find('submit button');
const debug = el.getDebugInfo();
console.log(debug);
// { cacheHit: true, similarity: 0.02, cacheSimilarity: 0.92, ... }

Types

interface CacheConfig {
  enabled?: boolean;            // Default: true
  thresholds?: CacheThresholds;
}

interface CacheThresholds {
  find?: FindCacheThresholds;
  assert?: number;              // Default: 0.05
}

interface FindCacheThresholds {
  screen?: number;              // Default: 0.05
  element?: number;             // Default: 0.8
}

interface CacheDebugInfo {
  cacheHit: boolean;
  similarity: number;
  cacheSimilarity: number;
}

Overview

Guide

Scaling

Actions

SDK Reference

Overview

How It Works

Configuration

Constructor Options

Disabling Cache

Per-Command Overrides

Threshold Priority

Auto-Generated Cache Key

Template Matching (OpenCV)

Cache Partitioning

Debugging Cache

Types

​Overview

​How It Works

​Configuration

​Constructor Options

​Disabling Cache

​Per-Command Overrides

​Threshold Priority

​Auto-Generated Cache Key

​Template Matching (OpenCV)

​Cache Partitioning

​Debugging Cache

​Types

Overview

How It Works

Configuration

Constructor Options

Disabling Cache

Per-Command Overrides

Threshold Priority

Auto-Generated Cache Key

Template Matching (OpenCV)

Cache Partitioning

Debugging Cache

Types