Skip to content

Suites

A suite is a named group of workflows in a project. Running a suite fans out one run per member workflow, in parallel, and the suite only passes when every member passes. Suites are what a CI gate, a nightly smoke test, or a “run everything before I ship” button actually run — a single workflow is one test; a suite is the release gate built from many.

Every project has one suite marked is_default: true, named All workflows. Every top-level workflow you build (including a workflow promoted from a suggestion) is added to it automatically — you can remove one later if it doesn’t belong. This is also the suite the GitHub action and the onboarding CI gate run when you don’t name a suite explicitly: POST /v1/github/runs with no suite runs the calling repo’s default suite.

A suite run only dispatches its live members. A workflow is live once a version with at least one step has been published and it is not paused. Everything else in the suite sits the run out:

  • Draft, not published — no version with steps has been published yet, so there is nothing to replay.
  • Paused — the workflow is disabled, so you have already asked us not to run it.

Skipped members are not failures. They are counted in the run’s skipped total and listed by name, with the reason, in the run report and on the dashboard’s suite-run page. If none of a suite’s members are live, the run is refused up front with 409 no_live_members rather than starting an empty run.

The suite page and the suite cards show this as “N live of M workflows”, and the members table badges each workflow Live, Draft or Paused.

There are three places to change which workflows a suite runs, and they all write the same membership:

  • The suite page — “Add workflows” at the top right of the members table, ↑/↓ to set the run order, and Remove on each row.
  • The workflow page — the Suites button in the workflow header opens a checkbox list of the project’s suites; tick or untick and Save.
  • Workflow → Settings → Suites — the same checkbox list, in the workflow’s settings tab.

A draft can be added to a suite before it is published — it simply shows as skipped until you publish it, and then it starts running with the rest.

A suite declares its own parameters under Settings → Params: name, description, required, secret, and an optional default (a secret param can’t have a default — store its value instead, see below). A run overrides any subset of them; anything the suite doesn’t declare is a 400, and a missing required param with no default fails the whole suite run before any session is bought — never mid-run.

Two params are built in and don’t need to be declared:

  • base_url — if set and the run has no other target-URL override, it becomes the workflow’s navigation target for that run (the same seam the GitHub action’s PR-preview URL rides).
  • app_build_id — an app build to gate mobile workflows on for that run.

Inside a step field or a vibe prompt, reach any param with {{ params.name }}, e.g. {{ params.base_url }}/login.

Secret params never appear in the suite’s stored params, in the run report, or in any log line — the value is masked to '***' everywhere except inside the workflow run that actually consumes it. Set a secret’s value with the internal PUT /v1/suites/:id/secrets/:name route (dashboard-only; not part of the public API).

Needs an API key with the workflow:run scope (Settings → API keys).

{
"params": { "base_url": "https://shop.test" } // optional; Record<string,string>
}

Returns 202:

{ "suite_run_id": "…", "status": "queued", "url": "/v1/suites/<id>/runs/<suite_run_id>" }

status is "running" when the suite’s concurrency policy let it start immediately, or "queued" when a run was already in progress and the policy is queue.

Errors are { "error": { "code", "message", "names"? } }:

status code when
400 validation_error params isn’t an object of strings
404 suite_not_found no such suite in your org
409 suite_run_in_progress policy is reject and a run is already queued/running
409 no_live_members every member is a draft or paused, so there is nothing to run
422 suite_empty the suite has no members
422 missing_params / unknown_params see names[]; no run is created
422 secret_override_not_queueable you passed a secret override on a run that would queue instead of dispatching immediately
const resp = await fetch('https://api.kifas.io/v1/suites/SUITE_ID/runs', {
method: 'POST',
headers: {
  Authorization: `Bearer ${process.env.KIFAS_API_KEY}`,
  'Content-Type': 'application/json',
},
body: JSON.stringify({ params: { base_url: 'https://shop.test' } }),
})
const { suite_run_id, status } = await resp.json()
console.log(suite_run_id, status)

Sign in at app.kifas.io to run snippets against a real cloud session.

{
"id": "…",
"status": "queued|running|passed|failed|aborted",
"run_number": 4,
"started_at": "…",
"ended_at": "…",
"report": { "…": "per-member outcomes plus a `skipped[]` list, see the dashboard report page" },
"counts": { "total": 2, "passed": 2, "failed": 0, "aborted": 0, "skipped": 0 },
"credits_used": 9,
"devices": {
"running": 2,
"starting": 1,
"waiting_for_device": 1,
"waiting_for_org_limit": 2,
"org_limit": 5,
"starting_devices": false,
"typical_wait_s": null
},
"message": "2 running · 1 starting · 3 waiting. Your plan runs 5 at once."
}

credits_used is the sum of every member run’s credit spend for this suite run — suites don’t have a separate USD cost, they’re billed the same way any run is.

While the suite run is queued or running, devices counts its Android devices: how many are running your tests, how many are starting, and how many runs are waiting, either for a device to free up or because your plan’s number of Android devices at once is already in use. message says the same in one line, as the dashboard shows it. Both are null once the suite run has finished, or when none of its workflows run on Android.

404 not_found when the run isn’t in your org or isn’t under that suite.

const resp = await fetch('https://api.kifas.io/v1/suites/SUITE_ID/runs/RUN_ID', {
headers: { Authorization: `Bearer ${process.env.KIFAS_API_KEY}` },
})
const run = await resp.json()
console.log(run.status, run.counts)

Sign in at app.kifas.io to run snippets against a real cloud session.

The dashboard’s Run it from CI panel on a suite’s settings page generates this for you, with your suite’s real params filled in:

- uses: kifasio/e2e-action@v1
with:
api-key: ${{ secrets.KIFAS_API_KEY }}
suite: my-suite-slug
params: |
base_url=<base_url>

suite is the suite’s slug (or id). params is a multiline key=value list — one override per line — matching whatever the suite declares (plus base_url / app_build_id). Omit suite entirely to run the repo’s default suite, which is what the action generated during onboarding does.

A suite can run on a cron schedule instead of (or in addition to) being triggered manually or from CI. Set a 5-field cron expression and an IANA timezone under Settings → Schedule; the dashboard ships three presets to start from:

Preset Cron
Every hour 0 * * * *
Nightly at 02:00 0 2 * * *
Weekdays at 09:00 0 9 * * 1-5

A scheduler tick claims each suite’s next matching minute exactly once (so a slow tick or a retry never double-fires the same minute) and dispatches the suite the same way a manual run does, subject to the suite’s concurrency policy.

Suites notify org members only — an email channel is always a member id, never a raw address, so a suite can’t be used to spam an outside inbox. Under Settings → Notifications, subscribe a member’s email channel to any of:

Event Fires
suite.started a suite run starts
suite.passed every member of a run passed
suite.failed any member of a run failed
suite.report_ready every finished run, pass or fail
workflow.failed a single member workflow fails, as it happens (before the suite itself finishes)

When a project’s default suite is created, its Owner is automatically subscribed to suite.report_ready so nobody’s default suite fails silently with no one watching.

GET /v1/suites/:id/badge.svg?token=<badge_token> returns 200 image/svg+xml you can embed in a README:

![suite status](https://api.kifas.io/v1/suites/SUITE_ID/badge.svg?token=YOUR_BADGE_TOKEN)
Last run status Badge reads
passed passing
failed / aborted failing
running running
no runs yet no runs

Find the badge URL (with its token already filled in) on the suite’s settings page. A wrong or missing token always returns a JSON 404 not_found, never an SVG — a stale badge URL fails loudly instead of silently rendering as blank.