docs: document PWCS cancellation feature [RED-511] by miliberlin · Pull Request #308 · checkly/docs

miliberlin · 2026-05-13T14:20:20Z

Documents the Playwright Check Suite cancellation feature shipping under Allow cancellation of PWCS runs & test sessions (RED-511).

Summary

Cancellation lets you stop in-progress Playwright Check Suite runs from the UI, public API, or CLI. This PR adds the concept page, the API reference for the cancel endpoints, the v2 check-session pages, and CLI cancellation docs — plus follow-on updates for two related CLI/API changes found along the way.

New pages

concepts/cancellation.mdx — what can be cancelled (check session vs. test session), how to cancel from UI/API/CLI, what happens after a run is cancelled (no alerts, excluded from metrics, no automated incidents), and the v1/v2 API versioning split.
api-reference/check-sessions/cancel-a-check-session.mdx and api-reference/test-sessions/cancel-a-test-session.mdx — the two cancel endpoints (see below).
api-reference/check-sessions/{trigger,retrieve,await-completion}-v2.mdx — three v2 check-session pages; endpoint content renders from the OpenAPI spec.

Cancel endpoint split

POST /v1/cancel was replaced by two path-scoped endpoints — POST /v1/check-sessions/{checkSessionId}/cancel and POST /v1/test-sessions/{testSessionId}/cancel. The session ID moves to the path; the body carries only an optional sequenceId array. openapi.json is synced from the live endpoint, and the v2 check-session descriptions that cross-referenced /v1/cancel were updated.

`--record` now defaults to true

checkly-cli#1306 makes checkly test and checkly trigger record a test session by default (opt out with --no-record), matching pw-test. The test/trigger reference pages now document --[no-]record and note the default applies since CLI v8.0.0. Examples keep --record explicit so they work on pre-v8.0.0 CLIs.

CLI cancellation behaviour

cli/checkly-{test,trigger,pw-test}.mdx get a "Cancelling a run" section. Behaviour was verified against the checkly-cli source (PR #1292): the first Ctrl+C cancels the recorded session directly — there is no confirmation prompt (one was prototyped during development but never merged); the CLI keeps running to report results; a second Ctrl+C exits immediately; --detach exits at once and leaves the checks running in the cloud. CLI cancellation ships in v8.0.0.

Sidebar

cancel-a-check-session added to the Check Sessions group; new Test Sessions group for cancel-a-test-session.
Three v2 entries added under Check Sessions; concepts/cancellation added under Concepts.

v1 deprecation markers

The three v1 check-session MDX pages carry deprecated: true in frontmatter, matching the convention used by check-groups, check-results, checks, and triggers when a v2 replacement exists.

Cross-links and other fixes

concepts/results.mdx and communicate/alerts/configuration.mdx — notes linking to / about cancellation (cancelled runs never trigger alerts, excluded from metrics).
style.css — dark-mode rule so <kbd> keys (e.g. Ctrl+C) are legible.

Resolved — RED-512

RED-512 fixed the empty/partial request/response schemas on the new API reference pages. Merged in checkly/monorepo#1797; api-reference/openapi.json is synced from the live endpoint, so the cancel and v2 check-session endpoints render full request, response, and description content.

Test plan

npm run dev and visit /concepts/cancellation — copy reads cleanly, all links resolve.
Visit the two cancel endpoint pages and the three v2 check-session pages — specs render from OpenAPI with full request/response examples.
Visit /concepts/results, /communicate/alerts/configuration, and the three cli/* pages — new sections appear in the right place.
Sidebar shows: Concepts > Cancellation; API Reference > Check Sessions > cancel-a-check-session + the three v2 pages; new Test Sessions group with cancel-a-test-session.
v1 check-session reference pages show the "deprecated" badge.
Toggle dark mode — <kbd> keys in the CLI cancellation sections are legible.

🤖 Generated with Claude Code

- New concepts/cancellation.mdx covering cancellation surfaces, post-cancel flow, and API versioning - New api-reference/cancel/cancel-a-session.mdx for POST /v1/cancel - New v2 check-session reference pages (trigger, retrieve, await completion) - Sidebar entries in docs.json for the above - Cross-links from concepts/results.mdx, communicate/alerts/configuration.mdx - Ctrl+C cancellation sections in cli/checkly-{pw-test,test,trigger,deploy}.mdx Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

miliberlin · 2026-05-13T14:20:39Z

+## Cancelling a run
+
+{/* TODO: confirm CLI version that ships pw-test Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>


Fill in the CLI version that ships pw-test Ctrl+C handling (RED-375), or remove this Note if Ferran prefers a generic call-out. The Linear ticket is still in In Review.

miliberlin · 2026-05-13T14:20:41Z

+{/* TODO: confirm CLI version that ships pw-test Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>
+
+Press <kbd>Ctrl</kbd>+<kbd>C</kbd> during a `checkly pw-test` run to cancel the test session. The CLI sends a cancel request and waits for the runner to stop. Pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> a second time exits the CLI without waiting.


Verify the Ctrl+C UX matches what shipped: "no detach prompt; second Ctrl+C exits without waiting." I took this from the project spec (RED-375), not from reading the CLI source.

miliberlin · 2026-05-13T14:20:42Z

+## Cancelling a run
+
+{/* TODO: confirm CLI version that ships test Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>


Fill in the CLI version that ships checkly test Ctrl+C handling (was RED-373, marked Duplicate — verify it actually shipped), or remove this Note.

miliberlin · 2026-05-13T14:20:44Z

+{/* TODO: confirm CLI version that ships test Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>
+
+When you started the run with `--record`, pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> prompts you to either **cancel** the recorded test session in Checkly or **detach** and let it finish in the background. Detach is the default. Cancellation only applies to Playwright Check Suite runs inside the session.


Verify "cancel or detach, detach is default" matches what shipped. RED-373 was marked Duplicate so I'm not 100% sure this is the final UX.

miliberlin · 2026-05-13T14:20:45Z

+## Cancelling a run
+
+{/* TODO: confirm CLI version that ships trigger Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>


Fill in the CLI version that ships checkly trigger Ctrl+C handling (RED-373 dup), or remove this Note.

miliberlin · 2026-05-13T14:20:47Z

+{/* TODO: confirm CLI version that ships trigger Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>
+
+When you started the run with `--record`, pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> prompts you to either **cancel** the recorded test session in Checkly or **detach** and let it finish in the background. Detach is the default. Cancellation only applies to Playwright Check Suite runs inside the session.


Same UX question as in checkly-test.mdx — confirm "detach is the default" is accurate.

miliberlin · 2026-05-13T14:20:48Z

+## Cancelling a deploy
+
+{/* TODO: confirm CLI version that ships deploy Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>


Fill in the CLI version that ships checkly deploy Ctrl+C handling (RED-374 dup), or remove this Note.

miliberlin · 2026-05-13T14:20:52Z

+{/* TODO: confirm CLI version that ships deploy Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>
+
+`checkly deploy` may run [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview) as part of post-deploy verification. Pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> during that phase prompts you to either **cancel** the recorded check session or **detach** and let it finish in the background. Detach is the default.


Confirm: (1) checkly deploy actually runs PWCS as part of post-deploy verification today — is that universally true or only when configured? (2) "detach is the default" matches what shipped.

Match the convention used by check-groups and check-results: v1 MDX pages get deprecated: true when a v2 equivalent exists. Updates the matching ResponseField label in concepts/cancellation.mdx from backwards-compatible to deprecated for consistency. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The v2 OpenAPI entries have no description fields, so the auto-rendered pages were blank. Carry the v1 description text forward in the MDX body and add a What's new in v2 note covering the CANCELLED status value and isCancelled result flag. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The /v1/cancel OpenAPI entry has no description, so the auto-rendered page only showed the request schema. Add MDX body content explaining the discriminated body (checkSessionId vs testSessionId), the optional sequenceId narrowing, and the Playwright-only constraint, with a link out to the cancellation concept page. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

timohuovinen · 2026-05-15T06:31:01Z

+The successful response of this endpoint is equivalent to the [retrieve a check session](/api-reference/check-sessions/retrieve-a-check-session-v2) endpoint's response for a completed check session.
+
+<Note>
+**What's new in v2:** `status` may return the new `CANCELLED` value for sessions that were [cancelled](/concepts/cancellation), and every per-result object includes an `isCancelled` boolean. v1 clients continue to work unchanged and never see these additions.


for v1, cancelled is mapped to TIMED_OUT

Good point, added that!

The only v2-only addition is the CANCELLED status enum value; v1 maps cancelled sessions to TIMED_OUT. The isCancelled boolean on per-result objects is additive and present in both versions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Verified the Ctrl+C cancellation behavior against the checkly-cli RED-375 branch: - Remove the "Cancelling a deploy" section — checkly deploy has no cancellation handling. - Note that cancellation requires a recorded test session (checkly test/trigger --record; pw-test records by default). - Document the --detach flag on pw-test, test, and trigger, and fix the default: Ctrl+C opens a cancel prompt by default, and --detach is the opt-in flag to skip it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Recovers the work from commit e4c25ee, which was dropped during a rebase onto the updated remote branch. The RED-512 backend changes are in the production OpenAPI spec, so the v2 check-session and /v1/cancel endpoints carry full request, response, and description content. Strip the manually-written prose from the three v2 check-session pages so the synced spec drives their content, matching the v1 pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The public API replaced POST /v1/cancel with two path-scoped endpoints: POST /v1/check-sessions/{checkSessionId}/cancel and POST /v1/test-sessions/{testSessionId}/cancel. - openapi.json: swap the cancel path and schemas to match the live spec; update v2 check-session descriptions that cross-referenced /v1/cancel - Split the reference page into cancel-a-check-session and cancel-a-test-session, filed under the Check Sessions and Test Sessions nav groups; drop the standalone Cancel group - cancellation.mdx: update API tab, curl examples, and versioning notes - style.css: add a dark-mode rule so <kbd> keys are visible Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

checkly-cli #1306 makes `checkly test` and `checkly trigger` record a test session by default (opt out with --no-record), matching pw-test. - test/trigger reference pages: --record -> --[no-]record, note that recording defaults to enabled since CLI v8.0.0 - Fill in CLI v8.0.0 for the cancellation availability notes across test, trigger, and pw-test (replacing the vX.X placeholders) - cancellation.mdx and cancel-a-test-session.mdx: test sessions are created by checkly test/trigger/pw-test, which all record by default Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Show the --record flag explicitly in example snippets so they work on pre-v8.0.0 CLIs where recording is opt-in. The --detach examples omit it, since --detach only exists in v8.0.0+ where --record is default. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…-511] The shipped checkly-cli (PR #1292) cancels directly on Ctrl+C; the cancel-confirmation prompt was prototyped but never merged. Update the docs to match: first Ctrl+C cancels the session, the CLI keeps running to report results, a second Ctrl+C exits immediately, and --detach exits at once leaving checks running in the cloud. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

miliberlin commented May 13, 2026

View reviewed changes

miliberlin requested review from MariadeAnton, ferrandiaz and timohuovinen May 13, 2026 14:27

miliberlin and others added 3 commits May 13, 2026 16:31

miliberlin changed the title ~~docs: document PWCS cancellation feature [RED-511]~~ [DO NOT MERGE!] docs: document PWCS cancellation feature [RED-511] May 13, 2026

miliberlin requested a review from hwartig May 13, 2026 14:59

timohuovinen reviewed May 15, 2026

View reviewed changes

timohuovinen approved these changes May 15, 2026

View reviewed changes

mintlify Bot deployed to staging May 15, 2026 13:08 View deployment

Merge branch 'main' into michelle/red-511-docs-update-docs

75d52a6

mintlify Bot deployed to staging May 18, 2026 11:46 View deployment

mintlify Bot deployed to staging May 20, 2026 15:43 View deployment

mintlify Bot deployed to staging May 20, 2026 15:53 View deployment

mintlify Bot deployed to staging May 22, 2026 08:49 View deployment

mintlify Bot deployed to staging May 22, 2026 09:05 View deployment

docs: simplify test-session cancellation wording [RED-511]

2c6949e

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

mintlify Bot deployed to staging May 22, 2026 09:12 View deployment

mintlify Bot deployed to staging May 22, 2026 09:17 View deployment

mintlify Bot deployed to staging May 22, 2026 12:40 View deployment

feat: reset openai spec

5f2839a

miliberlin force-pushed the michelle/red-511-docs-update-docs branch from 3d909ce to 5f2839a Compare May 22, 2026 12:41

Merge branch 'main' into michelle/red-511-docs-update-docs

239cd15

mintlify Bot deployed to staging May 22, 2026 12:42 View deployment

mintlify Bot deployed to staging May 22, 2026 12:44 View deployment

Merge branch 'main' into michelle/red-511-docs-update-docs

9f7ed0b

mintlify Bot deployed to staging May 22, 2026 12:53 View deployment

miliberlin changed the title ~~[DO NOT MERGE!] docs: document PWCS cancellation feature [RED-511]~~ docs: document PWCS cancellation feature [RED-511] May 22, 2026

miliberlin merged commit a15a83f into main May 22, 2026
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: document PWCS cancellation feature [RED-511]#308

docs: document PWCS cancellation feature [RED-511]#308
miliberlin merged 16 commits into
mainfrom
michelle/red-511-docs-update-docs

miliberlin commented May 13, 2026 •

edited

Loading

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

timohuovinen May 15, 2026

Uh oh!

miliberlin May 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

miliberlin commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New pages

Cancel endpoint split

--record now defaults to true

CLI cancellation behaviour

Sidebar

v1 deprecation markers

Cross-links and other fixes

Resolved — RED-512

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

miliberlin commented May 13, 2026 •

edited

Loading

`--record` now defaults to true