Skip to content

Test plans

A plan is a titled collection of case filters that a run is started from — the model Testomat.io’s test plans use, taken as it is. Each collection is one filter of the cases list, written the way the list’s URL writes it: inside a collection the dimensions narrow together, between collections the cases add up, and a collection with nothing set is every case.

A plan is a query, not a list of ids. Nothing is copied when it is saved: what it collects is resolved when it is read or launched, so a case written under the filter tomorrow is in tomorrow’s run without anybody editing the plan — and a case deleted today leaves every plan today.

POST /v1/plans
{
"title": "Release regression",
"description": "Everything under checkout, plus every critical case wherever it lives.",
"kind": "mixed",
"collections": ["suiteId=6f1c2b3a-0000-4000-8000-0000000000a1", "priority=critical"]
}
field
titleUnique within the project — a second plan of the same title is a 409.
descriptionOptional, up to 16 384 bytes.
kindmanual, automated or mixed — who executes it and which cases it may collect (below).
asManualmanual only: take automated cases too, to be walked by a person.
collectionsOne to twenty query strings. Each is read through the filter contract, so an unknown value of an enumerated dimension is refused with the filter’s own sentence (400 · unknown priority “urgent” — priorities are low, normal, important, high, critical), and written back canonical: two spellings of one filter are one string.

GET /v1/plans lists the project’s plans, ordered by title, each with count — how many cases it collects right now. GET /v1/plans/{id} is the plan itself; PATCH changes any field (collections replaces the whole list); DELETE is for good — there is no bin for a plan, it is a saved query, and the runs it started stay where they are.

GET /v1/plans/{id}/cases

The union of the collections, in the order of the tree, each case once, live cases only — then the kind’s rule:

kindcollects
manualmanual cases; with asManual, automated ones too
automatedautomated cases
mixedmanual and automated cases

Evals belong to no plan: their run is plune eval. Every case comes with its externalKeys, which is what a reporter greps by — see the road for CI below.

POST /v1/plans/{id}/launch
{ "environment": "staging", "labels": ["release"] }

The body is optional; title, environment and labels say what the run is called and marked, and the plan says everything else. The answer is 201 { "run": … } — a run of the plan’s kind, started through the same road a reporter takes, with:

  • configuration.expected — every case the plan collects at this moment, each with its first external key, so a reporter that joins the run later matches by it;
  • meta.planId — where the run came from;
  • title — the plan’s, unless the body names another;
  • externalKey — the run’s key, rk_ and ten hex, the one a reporter joins it by.

Two more fields come from the dashboard’s dialog. schedule: true is Save: the run is created scheduled and waits for Launch — Save or Launch. runKey is the key POST /v1/runs/keys issued when the dialog opened, so the command the dialog showed reports into this run; without one, the launch issues its own. A key a live run already holds is refused: 409 · run_key_taken.

A plan that collects nothing is not launched: 409 · the plan matches no case — nothing to run. The runs of one plan are GET /v1/runs?planId={id}.

Plans in the sidebar is the list — the kind, the live count, and Edit · Launch run · Delete behind each row’s menu. The form builds a collection with the same filter bar the cases screen has (suite, tags, priority, type, state, search), one bar per collection, and shows Matched cases under them as you edit. The plan’s page names each collection in words as a link into the cases screen with that filter, lists the matched cases with their state, and the runs launched from it. Launch run opens Launch a run: what the plan collects — «12 cases (7 manual · 5 automated)» when it holds both — a title (the plan’s, by default), an environment and the assignment, then Cancel · Save · Launch. Launch opens the run — for a manual or mixed plan, with the To run section a person marks the cases in (Manual runs). Save keeps it scheduled and says so on the page, with Open the run. With automated cases, the dialog shows the command that starts them, so their reporter joins this very run — The command with the key. Above the dialog’s note and its buttons, a bar says how much of the project’s run quota is used — Runs in the last 24 hours: 4 of 1000 used, 996 left. — and, once it is spent, when a slot frees (Quotas). On the Runs screen, New run ▾ › From a plan… leads here, and Manual run… beside it starts a manual run without a plan.

Launch a run on the mixed plan Checkout release: Checkout release · 6 cases (4 manual · 2 automated) → run «Checkout release»; Run title, Checkout release; Environment, empty; Assignment — None, picked, and Prefer case assignee; Automated cases · 2 — Start them in your CI with this command — the reporter joins this run by its key — the command PLUNE_RUN=rk_4f7c2a9e1b PLUNE_SHARED_RUN=1 npx playwright test --grep "$(plune plan grep …)" with the plan's id, and copy; a bar and Runs in the last 24 hours: 4 of 1000 used, 996 left.; Save keeps the run scheduled and its key; the run starts when someone launches it or the command reports. Launch starts it now. Then Cancel, Save and Launch. Launch a run on the mixed plan Checkout release: Checkout release · 6 cases (4 manual · 2 automated) → run «Checkout release»; Run title, Checkout release; Environment, empty; Assignment — None, picked, and Prefer case assignee; Automated cases · 2 — Start them in your CI with this command — the reporter joins this run by its key — the command PLUNE_RUN=rk_4f7c2a9e1b PLUNE_SHARED_RUN=1 npx playwright test --grep "$(plune plan grep …)" with the plan's id, and copy; a bar and Runs in the last 24 hours: 4 of 1000 used, 996 left.; Save keeps the run scheduled and its key; the run starts when someone launches it or the command reports. Launch starts it now. Then Cancel, Save and Launch.
A mixed plan's launch: the split, and the command its automated cases report by.

A plan is also a way to run a subset in CI without maintaining a list of test names by hand. Since CLI 0.13.0, plune plan grep <id> prints the plan as one --grep pattern — the platform decides which tests run, the runner runs only those:

Terminal window
npx playwright test --grep "$(plune plan grep $PLAN)"
npx vitest run -t "$(plune plan grep $PLAN)"

The command reads GET /v1/plans/{id}/cases with PLUNE_TOKEN (or the saved login) and builds the pattern from each case’s path-title key — the title path with the file left out, each segment escaped, [ >#]+ between segments so the same pattern fits Playwright, jest, mocha and vitest, whichever way they spell the boundary. A case without a key goes in by title. Only the pattern reaches stdout; the count of cases goes to stderr, so $(…) stays clean. An empty plan prints (?!), a pattern that matches nothing, because an empty --grep would run everything. Exit codes are those of plune pull: not logged in or a rejected token → 2, a plan that does not exist → 1.

Run like this, the reporter opens a run of its own. To report into the run a plan launched, put that run’s key in PLUNE_RUN — the dialog’s command does: PLUNE_RUN=<key> PLUNE_SHARED_RUN=1 npx playwright test --grep "$(plune plan grep <plan-id>)". With manual cases in the plan, PLUNE_SHARED_RUN=1 leaves the run open for Finish run; a plan of automated cases alone gets the command without it, and its reporter closes the run.

Without the CLI, the same answer is GET /v1/plans/{id}/cases — the cases with their external keys, one join away from a filter.

With a CI connected to the project, Plune can start the run’s automated cases itself, with the same pattern and the run’s key: Run tests in your CI.