Caching

agent-qa caches action plans for step sub-actions. A repeated run still observes the live page, checks the current screen state, executes actions, records artifacts, and verifies outcomes. The cache only skips redundant planning work when the same step is running in the same source, config, suite, platform, and step-position context.

The default cache directory is .agent-qa/cache.

Why caching speeds up repeated runs

Most test runs spend time asking the planner what action should happen next: click this button, fill this field, wait for this state, or assert this visible result. When a previous run already planned a sub-action for the same step context, agent-qa can reuse that cached action plan instead of asking the LLM to plan it again.

That means caching helps most when you rerun the same test or suite after a small product change, while the test YAML, suite YAML, config, platform, and step order remain stable.

The landing-page cache feature shows the intended impact for similar subsequent runs: 5x faster execution, from 42s -> 8s, and 3x fewer planner tokens. Those gains come from cached action plans skipping redundant planner work when the flow and screen state still match.

Caching does not turn a run into a replay script. The agent still re-observes the page before each sub-action, and a cached action can be rejected, invalidated, or replaced when the run no longer matches the cached path.

Configure cache storage

Cache storage is configured in agent-qa.config.yaml under services.cache:

services:
  cache:
    dir: .agent-qa/cache
    ttl: 7d

services.cache.dir chooses where cache files are written. services.cache.ttl controls how long entries stay fresh.

You can override these from the environment:

AGENT_QA_CACHE_DIR=.agent-qa/cache AGENT_QA_CACHE_TTL=24h agent-qa run tests/login.yaml

Per-run and per-test behavior is controlled through use.cache:

use:
  cache: true

Set use.cache: false in a test or suite override when that workflow should always plan fresh actions.

Run without cache

Use --no-cache when you want a single run to bypass action-cache reads and writes from the normal run path:

>agent-qa run tests/login.yaml --no-cache

The dashboard uses the same runtime behavior. The run options menu exposes Use cache; turning it off sends a no-cache run request and the underlying command runs with --no-cache.

Cache keys

agent-qa builds a step hash from the execution context, then stores sub-actions under that hash. The step hash uses the first 16 hex characters of a SHA-256 digest over:

• config file content
• suite file content
• suite test index
• test file content
• step instruction
• platform
• step index

The current sub-action cache files use this shape:

.agent-qa/cache/<stepHash>/sub-<index>.json

This is why small source changes can intentionally create a new cache context. Changing the config file, moving a test within a suite, editing the test file, changing the step text, switching platform, or moving the step to a different index can all change the key.

Hits, misses, and invalidation

A cache hit returns the stored action plan for a sub-action index. A cache miss asks the planner for a fresh action plan.

Entries are treated as misses when:

• the cache file is missing or invalid JSON
• CACHE_SCHEMA_VERSION does not match the current cache schema
• services.cache.ttl has expired
• a run misses at sub-action index N, which invalidates cached sub-actions from that index forward
• a cached action fails and the run needs to replan from that point
• a cached action contains an old redacted secret marker such as [secret:loginPassword] for a step that uses runtime {{secret:...}} templates

That prefix invalidation keeps a partially stale path from continuing after the first mismatch. The run can still write fresh cache entries for the actions it replans.

Purge cached plans

Purge cache entries for one test file when you know its action path should be rebuilt:

>agent-qa cache purge --test tests/login.yaml

Purge all cached plans when you want a clean cache directory:

>agent-qa cache purge --all --force

Without --force, the all-cache purge asks for confirmation.

Dashboard pages that run tests can also expose cache purge actions. Run detail cache markers show when a step was fully or partially cached, with labels such as All actions cached or 2 of 5 actions cached.

Cache, memory, and configuration

Cache is execution-level reuse. It stores action plans that let repeated runs avoid redundant planning work.

Memory is product context. It stores file-backed observations about products, suites, and tests so future runs can reason with prior evidence.

Configuration is runtime control. It defines targets, browsers, devices, services, hooks, variables, auth, and default run behavior.

Use cache when repeated runs should be faster. Use memory when the agent should remember product behavior. Use configuration when the team needs reviewable defaults and explicit overrides.