Author repeatable cached flows
Design idempotent flows and give your coding agent a prompt that takes a spec to cached replay while reporting bugs.
Design a flow that can run again after success or failure, then prove its cached interactions. Repeatability keeps application state problems from masquerading as cache failures.
Availability: Cache-only runs and basic cache authoring require access for your organization. Force replacement, trace authoring, and verified import currently require Cofactor assistance.
01Make the flow idempotent
Use these rules when turning a requirement into a flow:
| Concern | Authoring rule |
|---|---|
| Starting state | Name the application, environment, credential, and read-only prerequisites. Navigate explicitly to a known starting page. |
| Owned data | Create the records the test edits or deletes. Copy shared data first if the journey requires it. |
| Collisions | Use fresh macro values such as QA Test — $RANDOM_STRING(6) or $EMAIL(). Capture one generated value and reuse its variable when later steps must target that same record. |
| Partial failure | A rerun must tolerate leftovers from a stopped run. Unique identities prevent it from editing the wrong record. |
| Cleanup | Delete only data the test created. Restore settings it changed. Inline cleanup may be skipped after a fatal failure; use a seed and paired teardown when cleanup must run on pass and fail. |
| Isolation | Use a dedicated tenant or sandbox for organization-wide or global changes. A separate flow definition does not isolate application data. |
| Locators | Use unique semantic targets supported by the observed DOM. Avoid recorded coordinates, positional guesses, and IDs tied to one run. |
| Checks | State the behavior promised by the spec, preserve each configured assertion, and execute it exactly once. Check the actual user-visible outcome with current-run evidence. Do not turn observed DOM attributes, SVG details, or chosen scroll distances into requirements. |
For example, an edit test should create a uniquely named item, verify it exists, edit that exact item, verify the changed value, delete it, and verify it is gone. A failed run may leave its item behind; the next run uses a new identity and remains independent.
Cache the interaction you intend to test. Do not replace a UI action with a direct API call merely because the API is easier to replay. APIs can prepare test data when that is the agreed setup, but the journey under test must still exercise the intended interface.
02Explore before authoring
Use a Cofactor browser session to explore the target environment with the same credential the flow will use. Check the signed-in identity and role in the application. Read cofactor session --help, then use cofactor session start with the selected credential and application URL. Observe the real UI with snapshots, screenshots, and DOM evidence before choosing targets or writing Playwright code.
Discover candidate records and controls yourself, then confirm with the user which existing data is reliable enough to depend on. An item being visible today does not establish that it will remain available for future runs. If shared data is unsuitable, agree on test-owned setup instead. Ask about genuinely ambiguous requirements; discover URLs, labels, credentials, and available controls through the CLI and browser.
Describe each meaningful phase with its named target, action, and observable outcome. For a column-pinning journey, identify a stable grid and a named pinnable column, establish the starting state, pin it, verify its pinned state and that it stays fixed during actual horizontal scrolling while an unpinned column moves, then unpin it and verify that it moves with the scrollable region. Check whether the UI pins individual columns or a group. Restore the agreed starting state. A tooltip or a successful click alone does not prove scrolling behavior.
Keep these phases readable in the flow. Attach checks to the state they verify, before the next transition or cleanup. Evaluate the live page or measurements captured in that same phase; do not return constant success values or infer movement from the mere presence of a scrollbar.
03Assert product behavior
Write conditions a user can recognize from the specification. For column pinning, "The named column stays fixed while the level columns scroll" and "After unpinning, the named column scrolls with the grid" express the feature's behavior. An ARIA value, SVG path, or arbitrary minimum number of pixels does not define that behavior.
The Playwright code may use DOM evidence, measurements, and a small comparison tolerance to observe the outcome. Those are verification mechanics. A scroll distance or viewport size chosen to exercise the journey belongs in the setup or action; make it an acceptance threshold only when the specification requires one. Verify the intended user during browser exploration, but add a signed-in-user assertion only when authentication or identity is part of the journey under test.
04Copy this prompt into your coding agent
Paste this prompt as-is. The agent will ask for your spec, explore the application, and confirm reliable test data before designing the flow.
Use the Cofactor CLI to build a repeatable, working cached flow. Ask me for the test specification or journey I want to cover. Read `cofactor workflow guide`, `cofactor workflow guide playbook`, `cofactor workflow guide assertions`, `cofactor workflow --help`, `cofactor workflow cache`, `cofactor session --help`, `cofactor docs search caching`, `cofactor docs get reference/cache-authoring`, and `cofactor docs get reference/cache-optimization`. Find other relevant references through CLI docs search and get. Check supported command syntax and inputs before using them. Research the application, environments, credentials, existing flows, and relevant requirements through the CLI. Select the intended organization explicitly when multiple organizations are available. Start a Cofactor browser session with the flow's intended credential and environment. Verify the signed-in user and role, then explore the real behavior using snapshots, screenshots, and DOM evidence before designing the flow. Discover candidate test data yourself. Confirm with me which existing records, grids, or named targets are reliable for repeated tests; explain what you found so I can make that choice. If I am unsure, investigate the candidates and their controls before asking a focused question. Do not assume today's visible data is a durable fixture. Ask other questions only for truly ambiguous behavior or choices you cannot discover yourself. Design readable phases with specific named targets, actions, and expected outcomes. Write assertions about codified user-visible behavior, not ARIA values, SVG internals, or numeric thresholds invented from exploration. Keep chosen scroll distances and viewport sizes in setup/actions; verify that scrolling occurred and the expected columns stayed fixed or moved. Do not add a signed-in-user assertion unless identity is part of the spec. Map every specified behavior and rule to a check; do not silently substitute a sample for a requirement covering an entire group. Require comparison targets to exist, so a missing element cannot pass a negative state check. Verify the starting state and each meaningful transition before moving on or cleaning up. Test actual behavior: for example, pinning checks must show the named column stays fixed during real scrolling while an unpinned column moves, then show the named column moves after unpinning. Determine whether the UI operates on one column or a group. A control's label or a successful click alone is insufficient. Create the flow directly with `cofactor workflow create`; use `cofactor workflow patch` and workflow node commands to update it. Make it idempotent after success or partial failure: establish a known starting state, use fresh identities for test-owned data, preserve those identities through variables, and restore changed state. Follow CLI seed and teardown guidance when needed. Exercise the requested UI behavior with semantic locators verified against the observed DOM. Write executable cache interactions as self-contained Playwright code using the documented `browser_run_code` / `run_code` payload. Preserve dynamic inputs and bind every configured assertion by its ID. Checks must evaluate current-run evidence at the relevant phase, never copied source results, constant success values, or assumptions that an action worked. Validate the payload with cache commit dry-run. Verify through the CLI and inspect actual run evidence. Inspect the installed cached Playwright code, output capture wiring, and assertion expressions as well; generated cache can contain copied results even when the flow instructions are correct. Iterate: run with `--cache-only`, inspect the first failure, fix that step, commit its cache, and rerun. Do not weaken checks to obtain a pass. If application behavior contradicts the spec, report expected versus actual behavior with evidence; ask me only if the intended behavior is unclear. Require two consecutive fresh cache-only passes after the last change. Check every replay and assertion result, not just overall run status. Finish with the flow link, named data dependencies, what was verified, and any blockers. Leave final human approval to me.
05Related
- Cache optimization and convergence — commands, playbook format, repair, and promotion.
- Setup, seed & teardown — data preparation and failure-safe cleanup.
- Macros & Variables — fresh data and value propagation.
- Driving Cofactor from your coding agent — connect your agent.