Caching
How agent-qa replays the actions a passing step took, when it trusts a replay, and how to control the cache.
When a step passes, agent-qa saves every action the step took, in order. The next time the same step meets the same screen, it replays them without asking the model to plan. The step's check still runs, so nothing changes in what the step has to prove, and repeat runs get faster and cheaper.
What is saved
Each saved action finds its target the way a person would: by the element's role and exact accessible name. It holds no screen coordinates and no data from the page.
When a step replays
A cached action is used only when everything it depended on is unchanged:
- the platform;
- the config, suite and test files;
- the step's text and its position in the test;
- the set of variables the run has;
- the screen itself, which must look the same as when the action was saved.
Change any of them and the step asks the model again. If a replayed action fails, its target is gone, or the check rejects the result, the entry is dropped and the step is planned live; a test that then passes is healed. A step that replays its saved actions and then needs one more live turn saves only that turn.
What is never cached
- Steps that type a secret with
{{secret:…}}. - Steps that set or capture variables.
- Steps that judge a claim or extract data with
assertAIorextractAI. - Reading a value from the screen. When a step's check relies on one, the replay stops before it and the model reads the value live.
- Taps or clicks on screen coordinates.
- Typed values the run created in that step.
- Steps replayed from a procedure.
A step that acts and then checks, such as "Select Express delivery and verify the total is $36.00", saves its actions; its check runs again on every replay.
Branches
The cache keeps one folder per git branch under .agent-qa/cache/. A run reads its own branch's entries first, then your default branch's.
On your default branch, agent-qa does not write new entries unless you pass --save-cache. This keeps one-off local runs on main from filling the shared cache. CI runs are the exception: they write on any branch. Outside a git repository, every run counts as the default branch.
npx agent-qa run tests/checkout.yaml --save-cacheControls
| To | Use |
|---|---|
| Skip the cache for one run, reading and writing | agent-qa run --disable-cache |
| Save new entries on the default branch | agent-qa run --save-cache |
| Turn the cache off for a test, suite or the whole project | use: { cache: false } |
| Keep the cache somewhere else | services.cache.dir |
| Clear every entry | agent-qa cache purge --all |
agent-qa cache purge takes only --all.
Reading the summary
Each run ends with a line such as Cache: 1 hits, 0 misses. It counts only steps that could be cached. A step that replays its saved actions and then needs a live turn counts as a miss. When the cache was off for every test, the line reads Cache: disabled; when it was off for some, it adds (disabled for 1 test).
In CI
A CI job starts with an empty .agent-qa/ unless you keep it. To get cache hits across CI runs, persist .agent-qa/cache/ with your CI's cache step. Cached entries hold no secrets, because steps that type a secret are never cached.