Configure the cache

Every option that controls how find() and assert() reuse cached results.

This page lists every cache option, its default, and where you can set it. The cache is on by default, so you only need these to tune or turn it off.

For how caching works and when it helps, see Speed up reruns with caching.

const testdriver = TestDriver(context, {
  cache: {
    thresholds: {
      find: { screen: 0.05, element: 0.8 },
      assert: 0.05,
    },
  },
  cacheKey: 'checkout-flow',
});

Client options

Pass these to TestDriver(context, options) or new TestDriver(options). They apply to every call the client makes.

cache · boolean | object · default: "true"

Pass false to turn the cache off. Pass an object to change the match thresholds.

Show properties

thresholds · object

Show properties

find · object

Thresholds for find() and findAll().

Show properties

screen · number · default: "0.05"

The largest share of pixels that may differ between the current screen and the cached screen, from 0 to 1. 0.05 allows a 5% difference. Lower values require a closer match.

element · number · default: "0.8"

How closely the cached image of the element must match what’s on screen now, from 0 to 1. Higher values require a closer match. Used by find() only, not findAll().

assert · number · default: "0.05"

The largest share of pixels that may differ for assert() to reuse a cached result, from 0 to 1.

cacheKey · string

The key cache entries are stored under. By default, TestDriver generates one from the test file. See Cache keys.

cacheThreshold · object

Deprecated. Use cache.thresholds instead.

Per-call options

Override the client settings for a single call.

find()

const priceLabel = await testdriver.find('Total price label', {
  cacheKey: 'checkout-flow',
  cache: { thresholds: { screen: 0.01, element: 0.95 } },
});

cacheKey · string

Use this key for this call instead of the client’s key.

cache.thresholds.screen · number

Overrides cache.thresholds.find.screen for this call.

cache.thresholds.element · number

Overrides cache.thresholds.find.element for this call.

findAll()

findAll() takes cacheKey and cache.thresholds.screen. It doesn’t use the element threshold.

const productCards = await testdriver.findAll('Product card in the results grid', {
  cache: { thresholds: { screen: 0.02 } },
});

assert()

await testdriver.assert('the order confirmation is visible', {
  cacheKey: 'checkout-flow',
  threshold: 0.01,
});

cacheKey · string

Use this key for this call instead of the client’s key.

threshold · number

Overrides cache.thresholds.assert for this call.

Threshold priority

When a threshold is set in more than one place, the most specific wins:

1. The per-call option, such as find(description, { cache: { thresholds: { screen: 0.1 } } })
2. A legacy number argument, such as find(description, 0.1)
3. The client option, cache.thresholds
4. The defaults: screen 0.05, element 0.8, assert 0.05

Cache keys

Cache entries are stored under a key. By default, TestDriver generates the key from the test file:

• It hashes the contents of the file that creates the client (SHA-256, first 16 hex characters).
• Editing the file changes the hash, so the file starts with a fresh cache.
• Each test file gets its own cache.

Set cacheKey to keep a cache across edits, or to share one between files that use the same screens:

const testdriver = TestDriver(context, { cacheKey: 'checkout-flow' });

If TestDriver can’t read the test file, it can’t generate a key. find() and findAll() then skip the cache unless you set cacheKey.

What must match

A cached entry is reused only when all of these match the run that created it:

• The cache key.
• The exact description passed to find(), or the exact assertion text.
• The sandbox OS and screen resolution.

Entries become usable only after the test that created them passes.

Turn the cache off

Turn the cache off for one client:

const testdriver = TestDriver(context, { cache: false });

Or for a whole run:

TD_NO_CACHE=true npx vitest run

cache: { enabled: false } doesn’t turn the cache off. Use cache: false or TD_NO_CACHE=true.

Inspect a result

Read the cache details from the element that find() returns:

const submitButton = await testdriver.find('Submit button');
const { cache } = submitButton.toJSON();

cache · object

Show properties

hit · boolean

true when the location came from the cache.

strategy · string

How the cached entry was matched.

createdAt · string

When the cached entry was created.

diffPercent · number

The share of pixels that differed between the current screen and the cached screen, from 0 to 1.

imageUrl · string

A link to the cached screenshot.

To browse or clear your team’s cached entries, open the Cache page in the TestDriver console.

Related

Caching

How the cache works and when it helps.

Options

Every client option, with its default.

find()

Locate an element by describing it.

assert()

Check the screen with an AI assertion.