Caching

Cofactor caches the browser interactions in a flow so later workflow runs can repeat them quickly and check the same outcomes. A cache hit replays actions; it does not reuse a previous test result. Your application is exercised again, with fresh run data and assertions.

• Let Cofactor learn and maintain cached interactions during normal runs.
• Use cache-only runs to find the first interaction that cannot replay.
• Author and repair playbooks through the CLI, without waiting for an agent to rediscover the entire journey.

Availability: Cache-only runs and basic cache authoring require access for your organization. Force replacement, trace authoring, and verified import currently require Cofactor assistance.

01How a flow becomes cached

A playbook describes the interactions needed to complete a flow step. Its cached actions contain the executable interactions, inputs, captured variables, and checks needed to replay them. For code-based browser caching, those interactions are self-contained Playwright snippets executed against the authenticated page. The cache authoring reference defines their payload shape and validation rules.

In a normal workflow run, Cofactor uses deterministic replay when the cache is usable and proven. Otherwise, an agent can follow a playbook, repair an interaction, or perform the step and capture a new candidate. Candidates must pass validation and earn replay proof before normal runs trust them. Editing a flow or changing the application can make a previously usable cache unsuitable.

Dynamic values remain dynamic: macros generate values for the current run, and variables carry that run's values between steps. A cache must preserve those references instead of substituting the names or IDs observed in an earlier recording.

Assertions remain part of the test. A replay that reaches the page but skips a required check is not a working cached flow.

02When Cofactor handles caching

Cofactor captures cache candidates during agent-driven runs and can optimize captured interactions in the background. Cofactor's optimization service works on a temporary fork, verifies the result, and checks the original flow after promotion. It can respond to slow or flaky flows, flow edits, application changes, and missing cache on pinned flows. Unresolved behavior or changes that need review can leave the optimization blocked or waiting for review.

Our team also uses the manual loop for flows that need focused repair: inspect the evidence, fix one playbook, run from cache, and repeat. Use the same loop yourself when you want direct control over a specific interaction or need to prepare a flow for repeated deterministic runs.

03Cache-only runs make repair loops shorter

cofactor workflow run <workflowId> --cache-only --org "<organization>" --env prod

This command waits for completion and exits non-zero when the run fails. Cache-managed browser steps replay their cached actions without asking an agent to invent a replacement. The first missing or unusable cache becomes an explicit failure that you can diagnose and repair.

Cache-only is a real workflow run. It performs the flow's writes and deletions in the selected application environment. Authentication may still use an agent; steps explicitly configured to always use an agent are exempt from the deterministic cache gate. Check the run's replay and assertion evidence rather than treating a green status as proof that every step was agentless.

The shorter loop is run → inspect the first failure → change that node's playbook → commit → run again. Validate locators against retained evidence before rerunning whenever possible. After a commit, continue with cache-only runs while proving the candidate: a normal run can route an unverified playbook through an agent and rewrite it.

04Reliability starts with a repeatable flow

A perfect locator cannot fix a test that assumes yesterday's record still exists or leaves a shared setting changed. Make a flow safe to rerun after both success and partial failure before converging its cache.

For testing, idempotent means another complete run needs no manual reset and checks the same behavior. It does not mean clicking Create twice has no effect. Create uniquely named test data, pass its identity through variables, and clean up data the flow owns. Declare read-only prerequisites and restore any setting the test changes. Use teardown that runs on failure when cleanup is essential.

See Author repeatable cached flows for the data rules and a prompt you can give your coding agent.

05Related

• Cache optimization and convergence — the CLI repair and promotion procedure.
• Author repeatable cached flows — idempotency and the spec-to-cache agent prompt.
• Assertions — checks that replay must preserve.
• Runs — results and evidence.