Building your first suite

A suite is a group of flows you run together and judge as a unit. The best first suite is a smoke suite: a small set of must-pass flows that cover your most important user journeys.

The goal is not "test everything." The goal is: "If this is broken, we need to know immediately."

01How suites work in Cofactor

A suite runs a set of flows together and judges them as a unit. Cofactor gives you two ways to define one, and you can mix them:

• Tag a set of flows and run everything carrying that tag. There is nothing to maintain: add a flow to the suite by adding the tag, remove it by removing the tag. This is the fastest way to a smoke run.
• Build a named suite when you want a saved, curated gate, or when some tests must run before others. You pick the members and arrange them into ordered layers (see Named suites and sequencing).

Only promoted flows run, either way. Every flow has an approval state and a promotion state. Draft flows are work in progress, approved flows have been reviewed by a human, and promoted flows are included in suites and CI. Suites run the live promoted definition. Pause a promoted flow when you need to keep it out of the gate without deleting it. (How much the suite trusts a promoted flow is a separate, automatic signal, covered in Flow health below.)

The rest of this guide builds a tag-based smoke suite, since it is the quickest start; the Named suites and sequencing section covers when and how to graduate to a saved, ordered suite.

02Before you start

• You have a Property for the app or site you want to test.
• If login is required, you have set up Credentials and verified authentication works.

If you have not done these yet, start with Quickstart and Credentials and login.

03Pick the journeys (start with 3 to 7)

Pick flows that answer one question: "If this is broken, we need to know immediately."

Common examples:

• Sign in and sign out (or session refresh)
• Create the core resource (project, document, ticket, order)
• A critical payment or billing step, if you have one
• Invite a teammate or accept an invite (or a role change)
• A top navigation path that breaks easily, like global search or the workspace switcher

Keep it small. Aim for 5 to 15 minutes end to end. If you cannot explain in one sentence why a flow belongs in the smoke suite, it probably does not.

04Build each journey as a reliable, promoted flow

Each suite member is a single flow that models one coherent journey. Authoring a good flow is its own craft, covered in depth in Designing a good test. The short version:

1. Start from a stable entry point, usually your property base URL.
2. Use the Flow Designer to build one flow per journey.
3. Write steps as human intent ("Create a ticket assigned to Support"), not click-by-click mechanics.
4. Provision your own data with a seed or inline steps, using macros like $EMAIL() and $RANDOM_STRING(6) so reruns never collide.
5. End on a clear, observable signal ("Order confirmed", a new row in the table) and assert it inline.

Tag it as you build. Apply your suite tag to each flow. The tag is what enrolls the flow in the suite, so adding it later (or removing it) is how you change the roster.

Approve and promote it when it is reliable. Run the flow until it passes cleanly, approve it to record human sign-off, then promote it to include it in the gate. Fix flakiness before you promote: a smoke suite that flakes erodes trust faster than no suite at all. Existing flows that were published before this split keep running as promoted, but they may still show as Draft until approved once.

05Named suites and sequencing

A tag runs its flows in no particular order, which is perfect for an independent smoke suite. When order matters, or you want a stable, named gate you curate by hand, build a named suite.

A named suite is assembled on a canvas, where you place tests into layers:

• Tests in the same layer run in parallel. Group independent checks together so they finish fast.
• Layers run top to bottom, in order. A later layer can depend on what an earlier one set up, so you can run a setup flow, then the flows that need it.
• Add tests by search, or by tag. Adding a tag bulk-adds every flow that carries it, so your tag work still pays off here.
• Staged tests do not run. A test you have added but not yet placed in a layer sits in the staging rail and is excluded from runs until you place it.
• Arrange in one click. Collapse everything into a single parallel layer, or spread tests into sequential layers, and undo if you change your mind.
• Seeds and teardowns are automatic. Seed and teardown scripts attached to your flows show as read-only bands and run around the suite; you do not place them in layers.

Run a named suite from the app's Start Test Run dialog: choose the Suite scope, pick your suite, and it runs through the layered orchestrator in the order you arranged.

06Run the suite

Run every smoke-tagged flow together. Scope the run to a property or environment when you have more than one.

A green suite run: every flow passed (24 of 24), summarized as a 100% pass rate. Each row links to that flow's full result.

07Read the results and triage

A suite run is only useful if you act on it. Open the failures, and let Cofactor cluster related ones so you debug a cause once instead of chasing every red flow.

A passing flow confirms the journey still works end to end; a failing one opens to the exact step, screenshot, and assertion that broke.

Triage groups related failures into clusters, each with a likely cause and a suggested next step, so you debug once instead of chasing every red flow separately.

When something goes red, do not assume the worst. Work through Triaging a failure to decide whether it is a real regression, a flaky flow, agent confusion, or an environment problem, and route it to the right fix.

08Flow health

A suite is only as trustworthy as the flows in it, so Cofactor tracks a health signal for every promoted flow. You do not set it; it is recomputed automatically from each flow's recent run history, and it is separate from the approval and promotion lifecycle.

• Unverified — no terminal runs yet.
• Passing — recent runs are green, but not yet a long enough streak to be trusted.
• Reliable — five clean passes in a row. This is the bar a smoke-suite flow should clear.
• Flaky — the recent window mixes passes and failures (or a step only passed on a retry). Fix the flow; a flaky member makes the whole suite hard to trust.
• Degraded — enough consecutive failures that Cofactor stops running it in suites, showing it as "degraded — not run." This protects the suite from a flow that is broken or chronically failing.

A degraded flow stays skipped until you edit it or re-enable it, which gives it a clean slate: it has to earn a fresh passing streak before it counts again. So the health signal both tells you which flows to trust and quietly keeps a broken one from dragging the suite down.

09Run it like a release gate

Once the suite is reliable, put it on a schedule:

• Every release: run the smoke suite right before you ship, and again right after if you can.
• Nightly: schedule it to catch regressions early.
• After major changes: auth, navigation, payments, onboarding.

If the smoke suite fails, treat it as a release blocker until you understand the cause. See Running your tests to wire it into CI and run it automatically.

10A simple starter template

If you need a starting point, here is a common five-flow smoke suite:

1. Sign in (or session refresh)
2. Navigate to the primary dashboard or list
3. Create the primary object
4. Edit the primary object
5. Sign out (or switch org or workspace)

Build each one, tag it smoke, approve it, promote it, and you have a release gate.

11Next steps

• Go deeper on authoring with Designing a good test.
• Read Flows, Runs, and Issues for the full model behind authoring, execution, and triage.
• When a run goes red, follow Triaging a failure.