Skip to main content
In read-write mode, the trace cache stores verified agent.act() steps. The default file store uses .e2e/cache/, configurable through cache.dir; with cache.store, entries go to that custom store instead. The next run replays their actions with no model call and hands back to the live agent when the app stops matching the recording. Judgments (assert, waitFor, extract) are never cached. The cache is on by default. Turn it off per run to check whether a failure comes from the recording rather than the app:

​
When a step is recorded

In read-write mode, an entry is written only once a recorded verification step after the act passes: a locator or engine assertion, a locator waitFor, or an agent.assert or agent.waitFor judgment. Plain-value assertions such as expect(data.total).toBe(3) are not recorded and do not verify a trace. Pair every agent.act() with a recorded check of its outcome:
tests/cart.e2e.ts
A trailing act with no later recorded verification is never cached. In read-write mode, a failed attempt writes only traces verified before the failure and attempts to evict unverified entries. Automatic eviction requires the store’s optional delete method, which the file store provides. Custom stores without it may retain stale entries. read-only mode neither evicts nor records. File-store entries can be removed with e2e cache clear and recorded again in a read-write run. That command rejects custom stores; use that store’s own tools for cleanup.

​
When a replay hands off

A replay checks the recorded end path when the engine reports one, plus any captured end anchors, the element descriptions that appeared or changed during the step. If a recorded path or anchor does not match after the actions run, the step hands off to the live agent to check its outcome. In read-write mode, an entry the agent must repair with further actions is submitted for eviction through the same optional delete method instead of being rewritten with the repairs. Some steps produce no end anchors, for example when only an input value or checkbox state changes. An empty anchor set passes the anchor check. Such a replay can finish after running the actions and checking only its recorded path, without verifying the effect itself. Later assertions in the test still execute on every run; keep those outcome checks in place. Volatile anchors, such as minted ids, countdowns, dates, and clock times, are omitted when stable anchors are available. If every captured anchor is volatile, they are retained and compared exactly. The replay hands off when their values differ, but can finish when they still match. A recorded end path matches up to ids the app mints per record, so a flow that creates a project can replay even when the next project has a new id. Each agent step in the report records how the cache took part under step.cache: self-finalized when a recording replayed the whole step, agent-concluded when a replay handed off mid-step, missed otherwise with a reason. A retry attempt records but never replays.

​
Cache-friendly tests

  • Verify the outcome of every act with a recorded assertion or wait.
  • Create your own data under names unique to the run, so a replay never finds two rows with the recorded name.
  • Clean up in afterEach, not in the last steps, so a run that fails before its cleanup leaves no duplicates for the next one.
  • Give repeated controls distinct accessible names. A target that matches several controls is recorded with its position among them, and a replay honors that position only when the live screen shows exactly as many.

​
Modes

Set one of these alternatives inside the exported config object:
Config fragment
cache.store replaces the file store with your own, for a shared remote cache. See the config reference.

​
Commit your traces

Committing cache entries is opt-in. e2e init adds .e2e/cache/ to .gitignore, so every machine records its own entries and CI starts with none. To share replays, remove that line and commit the directory. Entries a passing local run wrote then replay in CI and on every teammate’s machine. CI stays read-only unless you set cache: 'read-write', which is the right call only when CI restores the directory from its own cache service rather than from git. Treat committed entries as test data: review them in the same pull request as the test change that re-recorded them, and delete the directory when a flow changes enough that the next passing run should record it from scratch.

​
Inspect the cache

The file store names entries by digest, so the directory listing says nothing. The CLI inspects and clears file-store entries only:
Entries are disposable: deleting .e2e/cache/ slows the next run and changes nothing else.

Config reference

mode, store, dir.

CLI reference

e2e cache ls, stats, clear.