Concepts

Cofactor has a small vocabulary. Learn these few objects and the whole product clicks into place. Here's the full model, in the order you'll meet it. The first seven are all you need to get going; the rest you can pick up as your testing grows.

01Flows

A flow is a single test, written as a journey instead of code. Where a traditional end-to-end test is a script of selectors and assertions, a flow is the sequence of steps a real person would take (log in, open billing, change the plan, confirm the new price), and an AI agent plays that person in a real browser. If you've written a user story, you've already written the hard part of a flow. See Flows.

02Suites

A suite is a set of flows you run together. Your smoke suite is the short list of must-pass journeys you want checked on every change; a regression suite is the broader set you run before a release. Grouping flows into suites is how you go from "I have some tests" to "I have a safety net," the same way a CI job bundles many tests into one green-or-red signal. See Smoke suites.

03Applications and environments

An application is the product you're testing, usually one web app. Each application has one or more environments: the places it actually runs, like production, staging, a local dev server, or a throwaway sandbox. It's the familiar "same app, many deploys" model: one application, with different URLs and data behind each environment, so a single flow can run against staging today and production tomorrow without being rewritten. See Properties.

04Credentials and personas

To test anything behind a login, Cofactor needs to sign in. A credential is the saved login itself: the username, password, or token, like one entry in a password manager. A persona is the role a flow logs in as (Admin, Buyer, Support agent), independent of any one environment. You write the flow once to act as "the Buyer," and the persona resolves to the right real credential in whatever environment the run targets. Think roles, not passwords. See Credentials and login and Personas.

05Runs

A run is one execution of a flow or suite: the receipt. Like a single CI build, a run tells you pass or fail, but it also keeps a full replayable recording: every navigation, action, assertion, screenshot, and the agent's reasoning. When you want to know what actually happened, you open the run.

06Sandboxes

A sandbox is a disposable, isolated environment Cofactor spins up on demand, most often from a GitHub branch, the way a preview deploy works. Use one to test a change before it's live, to run against a clean slate, or to exercise risky flows without touching shared staging. You create sandboxes from reusable templates, and they tear down when you're done. See Sandboxes.

07Issues

An issue is a problem Cofactor found and filed for you: a broken function, a regression, a UX defect. It works like an auto-populated bug tracker: each issue carries a severity, a lifecycle (open → fixed → verified → closed), and a link back to the run that proves it. Findings are deduped and triaged so you get a clean list of real problems, not a wall of raw failures. See Issues.

08Flow health and status

Every flow has three independent signals: approval, promotion, and health. Approval is human sign-off (draft -> approved) that the flow checks the right behavior. Promotion controls suite inclusion: promoted flows actively guard your app, while paused flows stay out of suites without being deleted. Health is recent reliability (passing, failing, or flaky), so you can tell a stable green flow from one that oscillates. Existing flows that were already published keep running as promoted, but may still need one approval pass to record the new sign-off. See Flows.

09Managing Test Data via Seeds and Teardowns

Good tests control their starting conditions. A seed is a setup step that establishes what a flow needs before the real journey begins: create the account, the order, the record. A teardown is the cleanup afterward, so the next run starts from a known-clean state. It's the same idea as setUp/tearDown or test fixtures: isolate each run so results are repeatable, not dependent on whatever state happened to be lying around. See Flows.

10Macros and variables

Hardcoded data makes tests brittle. A macro generates fresh, unique data every run, so flows never collide on stale records: $EMAIL() mints a new test address, $UUID() a new id. A variable ($var.name) carries a value across steps: an input you passed in, a macro result, or something captured from the page earlier. Together they're your template placeholders and Faker rolled into one, which is what lets a single flow run as many accounts across many environments. See Macros & Variables.

11API catalog and sequences

Not everything worth testing happens in the UI. The API catalog is a map of your application's endpoints (both the calls captured during runs and definitions you import from an OpenAPI or Postman schema), so you can see what the app talked to and correlate a UI failure with the request behind it. API sequences chain those calls into repeatable, multi-step checks (login → create → verify), the way a Postman runner does, to seed state or assert behavior directly below the interface. See API Catalog and API Sequences.