diff --git a/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx b/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx new file mode 100644 index 00000000..d24029a8 --- /dev/null +++ b/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/check-sessions/{checkSessionId}/completion +--- diff --git a/api-reference/check-sessions/await-the-completion-of-a-check-session.mdx b/api-reference/check-sessions/await-the-completion-of-a-check-session.mdx index 6e93205c..3c14b799 100644 --- a/api-reference/check-sessions/await-the-completion-of-a-check-session.mdx +++ b/api-reference/check-sessions/await-the-completion-of-a-check-session.mdx @@ -1,3 +1,4 @@ --- openapi: get /v1/check-sessions/{checkSessionId}/completion ---- \ No newline at end of file +deprecated: true +--- diff --git a/api-reference/check-sessions/cancel-a-check-session.mdx b/api-reference/check-sessions/cancel-a-check-session.mdx new file mode 100644 index 00000000..a7d48dad --- /dev/null +++ b/api-reference/check-sessions/cancel-a-check-session.mdx @@ -0,0 +1,9 @@ +--- +openapi: post /v1/check-sessions/{checkSessionId}/cancel +title: Cancel a check session +sidebarTitle: Cancel a check session +--- + +Check sessions are started by the UI "Schedule now" button and `checkly deploy`. + +See [Cancellation](/concepts/cancellation) for how cancelled runs affect alerts, metrics, and the `CANCELLED` session status. diff --git a/api-reference/check-sessions/retrieve-a-check-session-v2.mdx b/api-reference/check-sessions/retrieve-a-check-session-v2.mdx new file mode 100644 index 00000000..10ee5c0d --- /dev/null +++ b/api-reference/check-sessions/retrieve-a-check-session-v2.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/check-sessions/{checkSessionId} +--- diff --git a/api-reference/check-sessions/retrieve-a-check-session.mdx b/api-reference/check-sessions/retrieve-a-check-session.mdx index 9b732e76..7df50494 100644 --- a/api-reference/check-sessions/retrieve-a-check-session.mdx +++ b/api-reference/check-sessions/retrieve-a-check-session.mdx @@ -1,3 +1,4 @@ --- openapi: get /v1/check-sessions/{checkSessionId} ---- \ No newline at end of file +deprecated: true +--- diff --git a/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx b/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx new file mode 100644 index 00000000..72deac5a --- /dev/null +++ b/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v2/check-sessions/trigger +--- diff --git a/api-reference/check-sessions/trigger-a-new-check-session.mdx b/api-reference/check-sessions/trigger-a-new-check-session.mdx index c5dcbf9b..8c304e6a 100644 --- a/api-reference/check-sessions/trigger-a-new-check-session.mdx +++ b/api-reference/check-sessions/trigger-a-new-check-session.mdx @@ -1,3 +1,4 @@ --- openapi: post /v1/check-sessions/trigger ---- \ No newline at end of file +deprecated: true +--- diff --git a/api-reference/test-sessions/cancel-a-test-session.mdx b/api-reference/test-sessions/cancel-a-test-session.mdx new file mode 100644 index 00000000..cf6bd366 --- /dev/null +++ b/api-reference/test-sessions/cancel-a-test-session.mdx @@ -0,0 +1,9 @@ +--- +openapi: post /v1/test-sessions/{testSessionId}/cancel +title: Cancel a test session +sidebarTitle: Cancel a test session +--- + +Test sessions are recorded with `checkly test`, `checkly trigger`, and `checkly pw-test`. Cancellation applies only to the session's Playwright Check Suite runs — any URL, API, Browser, Multistep, Heartbeat, TCP, DNS, or ICMP runs continue until they finish normally. + +See [Cancellation](/concepts/cancellation) for how cancelled runs affect alerts, metrics, and the `CANCELLED` session status. diff --git a/cli/checkly-pw-test.mdx b/cli/checkly-pw-test.mdx index 53c97251..9804991b 100644 --- a/cli/checkly-pw-test.mdx +++ b/cli/checkly-pw-test.mdx @@ -36,6 +36,7 @@ Define `checkly pw-test` specific options before the `--` separator: |--------|----------|-------------| | `--config` | - | The Checkly CLI configuration file. If not passed, uses the `checkly.config.ts\|js` file in the current directory. | | `--create-check` | - | Create a Checkly check from the Playwright test. | +| `--detach, -d` | - | Keep checks running in the cloud when you stop the CLI with Ctrl+C, instead of cancelling the run. | | `--env, -e` | - | Env vars to be passed to the test run. Default: [] | | `--env-file` | - | dotenv file path to be passed. For example `--env-file="./.env"` | | `--include, -i` | - | File patterns to include when bundling the test project (e.g., `"utils/**/*"`). Can be repeated. | @@ -125,6 +126,18 @@ const config = defineConfig({ + + +By default, pressing Ctrl+C during a `pw-test` run cancels the recorded test session. With `--detach`, Ctrl+C exits the CLI immediately instead, leaving the checks running in the cloud. + +**Usage:** + +```bash Terminal +npx checkly pw-test --detach +``` + + + Pass environment variables to the test run. Can be specified multiple times to set multiple variables. @@ -432,6 +445,16 @@ npx checkly pw-test -- test.spec.ts - Test sessions are recorded by default with full logs, traces, and videos - View all artifacts in Checkly's UI +## Cancelling a run + +Available in CLI v8.0.0+. + +Cancellation is available only for recorded test sessions. + +Press Ctrl+C during a `checkly pw-test` run to cancel the test session. The CLI keeps running to report the cancelled results; press Ctrl+C again to exit immediately without waiting. Pass the `--detach` flag to keep the checks running in the cloud instead — Ctrl+C then exits the CLI immediately without cancelling. + +See [Cancellation](/concepts/cancellation) for the full flow. + ## Related Commands - [`checkly test`](/cli/checkly-test) - Test your setup before deployment diff --git a/cli/checkly-test.mdx b/cli/checkly-test.mdx index 6c14729a..cf7bf61e 100644 --- a/cli/checkly-test.mdx +++ b/cli/checkly-test.mdx @@ -21,18 +21,19 @@ npx checkly test [arguments] [options] | Option | Required | Description | |--------|----------|-------------| | `--config, -c` | - | The Checkly CLI configuration file. If not passed, uses the `checkly.config.ts\|js` file in the current directory. | +| `--detach, -d` | - | Keep checks running in the cloud when you stop the CLI with Ctrl+C, instead of cancelling the run. | | `--env, -e` | - | Env vars to be passed to the test run. Can be used multiple times. | | `--env-file` | - | dotenv file path to be passed. For example `--env-file="./.env"` | | `--grep, -g` | - | Only run checks where the check name matches a regular expression. Default: `.*` | | `--list` | - | List all checks but don't run them. | | `--location, -l` | - | The location to run the checks at. | | `--private-location` | - | The private location to run checks at. | -| `--record` | - | Record test session results in Checkly with full logs, traces and videos. | +| `--[no-]record` | - | Record test session results in Checkly with full logs, traces and videos. Records by default since CLI v8.0.0. | | `--refresh-cache` | - | Force a fresh install of dependencies and update the cached version. | | `--reporter, -r` | - | One or more custom reporters for the test output. Supports comma-separated values and repeated flags. | | `--retries` | - | How many times to retry a failing test run. | | `--tags, -t` | - | Filter the checks to be run using a comma separated list of tags. | -| `--test-session-name, -n` | - | A name to use when storing results in Checkly with `--record`. | +| `--test-session-name, -n` | - | A name to use when recording results in Checkly. | | `--timeout` | - | A timeout (in seconds) to wait for checks to complete. | | `--update-snapshots, -u` | - | Update any snapshots using the actual result of this test run. | | `--verbose, -v` | - | Always show the full logs of the checks. | @@ -53,6 +54,18 @@ npx checkly test -c="./checkly.staging.config.ts" + + +By default, pressing Ctrl+C during a recorded run cancels the test session. With `--detach`, Ctrl+C exits the CLI immediately instead, leaving the checks running in the cloud. + +**Usage:** + +```bash Terminal +npx checkly test --detach +``` + + + [Environment variables](/cli/environment-variables) to be passed to the test run. Can be used multiple times. @@ -228,14 +241,17 @@ npx checkly test -r github -r json - + + +Record test results in Checkly as [a test session](/detect/testing/overview) with full logs, traces and videos. Recording is enabled by default; use `--no-record` to disable it. -Record test results in Checkly as [a test session](/detect/testing/overview) with full logs, traces and videos. +Recording defaults to enabled since CLI v8.0.0. In earlier versions, recording was opt-in via `--record`. **Usage:** ```bash Terminal npx checkly test --record +npx checkly test --no-record npx checkly test --record --test-session-name="CI Build #123" ``` @@ -280,7 +296,7 @@ npx checkly test --retries 3 -A name to use when storing results in Checkly with `--record`. +A name to use when recording results in Checkly. **Usage:** @@ -380,6 +396,18 @@ Specify [environment variables](/cli/environment-variables) to dry run checks wi npx checkly test --env ENVIRONMENT_URL="https://preview.acme.com" --env PASSWORD=doremiabc123 ``` +## Cancelling a run + +Available in CLI v8.0.0+. + +`checkly test` records a test session by default, so pressing Ctrl+C cancels it. Cancellation applies only to Playwright Check Suite runs inside the session; other check types finish normally. Runs started with `--no-record` cannot be cancelled. + +The CLI keeps running after the first Ctrl+C to report the cancelled results. Press Ctrl+C again to exit immediately without waiting. + +Pass the `--detach` flag to keep the checks running in the cloud instead — Ctrl+C then exits the CLI immediately without cancelling. + +See [Cancellation](/concepts/cancellation) for the full flow. + ## Related Commands - [`checkly pw-test`](/cli/checkly-pw-test) - Run Playwright tests in the Checkly cloud diff --git a/cli/checkly-trigger.mdx b/cli/checkly-trigger.mdx index 9b0e4fd0..0611cbd4 100644 --- a/cli/checkly-trigger.mdx +++ b/cli/checkly-trigger.mdx @@ -21,17 +21,18 @@ npx checkly trigger [options] | Option | Required | Description | |--------|----------|-------------| | `--config, -c` | - | The Checkly CLI configuration file. If not passed, uses the `checkly.config.ts\|js` file in the current directory. | +| `--detach, -d` | - | Keep checks running in the cloud when you stop the CLI with Ctrl+C, instead of cancelling the run. | | `--env, -e` | - | Env vars to be passed to the check run. Default: empty. Multiple values can be passed. | | `--env-file` | - | dotenv file path to be passed. For example `--env-file="./.env"` | | `--fail-on-no-matching` | - | Exit with a failing status code when there are no matching tests. | | `--location, -l` | - | The location to run the checks at. | | `--private-location` | - | The private location to run checks at. | -| `--record` | - | Record test session results in Checkly with full logs, traces and videos. | +| `--[no-]record` | - | Record test session results in Checkly with full logs, traces and videos. Records by default since CLI v8.0.0. | | `--refresh-cache` | - | Force a fresh install of dependencies and update the cached version. | | `--reporter, -r` | - | One or more custom reporters for the test output. Supports comma-separated values and repeated flags. | | `--retries` | - | How many times to retry a check run. | | `--tags, -t` | - | Filter the checks to be run using a comma separated list of tags. | -| `--test-session-name, -n` | - | A name to use when storing results in Checkly with `--record`. | +| `--test-session-name, -n` | - | A name to use when recording results in Checkly. | | `--timeout` | - | A timeout (in seconds) to wait for checks to complete. | | `--verbose, -v` | - | Always show the full logs of the checks. | @@ -50,6 +51,18 @@ npx checkly trigger -c="./checkly.staging.config.ts" + + +By default, pressing Ctrl+C during a recorded run cancels the test session. With `--detach`, Ctrl+C exits the CLI immediately instead, leaving the checks running in the cloud. + +**Usage:** + +```bash Terminal +npx checkly trigger --detach +``` + + + [Environment variables](/cli/environment-variables) to be passed to the check run. Multiple values can be passed and passed variables overwrite any existing variables stored in your Checkly account. @@ -168,7 +181,7 @@ Tags are comma-separated within a single flag for AND logic, multiple flags for -A name to use when storing results in Checkly with `--record`. +A name to use when recording results in Checkly. **Usage:** @@ -259,27 +272,30 @@ npx checkly trigger --no-fail-on-no-matching --tags optional-tag Enabled by default. Use `--no-fail-on-no-matching` to allow zero matches without failure. - + + +Record check results in Checkly as a test session with full logs, traces and videos. Recording is enabled by default; use `--no-record` to disable it. -Record check results in Checkly as a test session with full logs, traces and videos. +Recording defaults to enabled since CLI v8.0.0. In earlier versions, recording was opt-in via `--record`. **Usage:** ```bash Terminal npx checkly trigger --record +npx checkly trigger --no-record ``` **Examples:** ```bash Terminal -# Basic recording -npx checkly trigger --record - -# Record with custom name +# Record with a custom session name npx checkly trigger --record --test-session-name "Deploy validation" # Record specific checks npx checkly trigger --record --tags critical + +# Run without recording +npx checkly trigger --no-record ``` Records provide full visibility including logs, traces, and videos for debugging failed checks. @@ -372,6 +388,18 @@ npx checkly trigger --tags staging --record --test-session-name "Pre-prod valida If your production deployment includes monitoring changes and updates, [use `npx checkly test`](/cli/checkly-test) to validate your preview environment with the updated monitoring configuration. +## Cancelling a run + +Available in CLI v8.0.0+. + +`checkly trigger` records a test session by default, so pressing Ctrl+C cancels it. Cancellation applies only to Playwright Check Suite runs inside the session; other check types finish normally. Runs started with `--no-record` cannot be cancelled. + +The CLI keeps running after the first Ctrl+C to report the cancelled results. Press Ctrl+C again to exit immediately without waiting. + +Pass the `--detach` flag to keep the checks running in the cloud instead — Ctrl+C then exits the CLI immediately without cancelling. + +See [Cancellation](/concepts/cancellation) for the full flow. + ## Related Commands - [`checkly deploy`](/cli/checkly-deploy) - Deploy your Checkly configuration diff --git a/communicate/alerts/configuration.mdx b/communicate/alerts/configuration.mdx index d80d81c8..09cba830 100644 --- a/communicate/alerts/configuration.mdx +++ b/communicate/alerts/configuration.mdx @@ -44,6 +44,10 @@ Understanding how settings cascade through the hierarchy: + +Runs you [cancel](/concepts/cancellation) never trigger alerts. No failure, degraded, or recovery notification is sent for a cancelled run, regardless of the settings above. + + ## Alert Configuration ### Account-Level @@ -70,7 +74,7 @@ Configure alerts for teams and service categories: ![Group-level alert settings](/images/docs/images/alerting/alert-settings-group.png) -#### Group Override +### Group Override Configure how group settings interact with individual checks: **If checked, Group settings override individual check settings** diff --git a/concepts/cancellation.mdx b/concepts/cancellation.mdx new file mode 100644 index 00000000..a6f46759 --- /dev/null +++ b/concepts/cancellation.mdx @@ -0,0 +1,101 @@ +--- +title: 'Cancellation' +description: 'Stop in-flight Playwright Check Suite runs from the UI, API, or CLI. Other check types cannot be cancelled.' +sidebarTitle: 'Cancellation' +--- + +Cancellation lets you stop an in-progress [Playwright Check Suite](/detect/synthetic-monitoring/playwright-checks/overview) run. Cancelled results are flagged with `isCancelled: true`, do not trigger alerts, and are excluded from availability and performance metrics. A session that contains at least one cancelled run ends in a terminal `CANCELLED` status. + +## What you can cancel + +You can cancel two kinds of sessions, and the behaviour differs: + +**Check sessions** — created by the UI "Schedule now" button and `checkly deploy`. A check session is one execution of a single Playwright Check Suite, fanned out across the locations you configured. Cancelling the session stops every in-progress run; cancelling a single run leaves the rest of the session going. + +**Test sessions** — created by `checkly test`, `checkly trigger`, and `checkly pw-test`, which all record by default. A test session can contain multiple checks of different types. Cancelling the test session stops only the Playwright Check Suite runs inside it; any URL, API, Browser, Multistep, Heartbeat, TCP, DNS, or ICMP runs in the same session continue until they finish normally. You can also cancel a single Playwright run within the session. + + +**Only Playwright Check Suite runs are cancellable.** Other check types cannot be cancelled, even when they appear inside a test session alongside Playwright runs. Scheduled runs are also excluded; cancellation is for user-initiated runs only. + + +## How to cancel + + + +On a check session or test session page, click **Cancel session** in the header to stop the whole session. To stop just a single run, use the cancel button on its row. + + + +Send a `POST` request to the cancel endpoint for the session type: [`/v1/check-sessions/{checkSessionId}/cancel`](/api-reference/check-sessions/cancel-a-check-session) or [`/v1/test-sessions/{testSessionId}/cancel`](/api-reference/test-sessions/cancel-a-test-session). The session ID goes in the path. Pass an optional `sequenceId` array in the body to cancel only specific runs within the session; send `{}` to cancel everything still running. + +```bash Cancel a whole check session +curl -X POST https://api.checklyhq.com/v1/check-sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \ + -H "Authorization: Bearer $CHECKLY_API_KEY" \ + -H "X-Checkly-Account: $CHECKLY_ACCOUNT_ID" \ + -H "Content-Type: application/json" \ + -d '{}' +``` + +```bash Cancel specific runs in a test session +curl -X POST https://api.checklyhq.com/v1/test-sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \ + -H "Authorization: Bearer $CHECKLY_API_KEY" \ + -H "X-Checkly-Account: $CHECKLY_ACCOUNT_ID" \ + -H "Content-Type: application/json" \ + -d '{"sequenceId": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]}' +``` + + + +CLI cancellation is available in CLI v8.0.0+. + +Press Ctrl+C during a recorded test session run — `checkly test`, `checkly trigger`, and `checkly pw-test` all record by default — to cancel the session. The CLI keeps running to report the cancelled results; press Ctrl+C again to exit immediately. + +See the [CLI reference](/cli/overview) for command-specific behavior. + + + +## What happens after a run is cancelled + + + +The runner receives the cancellation signal, aborts the in-flight Playwright run, and reports the result back to Checkly. + + + +Each cancelled run's result has `isCancelled: true`. Once the session has stopped (any remaining non-Playwright checks finish normally), the session's status becomes `CANCELLED` because at least one of its runs was cancelled. + + + +Cancelled runs never produce failure or recovery alerts, regardless of your alert settings. See [Alert configuration](/communicate/alerts/configuration). + + + +Availability, response time percentiles, and success ratios exclude cancelled runs. Your check status does not change. Public and private dashboards omit cancelled runs from their summary counts. + + + +Because no alert is sent and the check status does not change, [automated incidents](/communicate/incidents/overview) are not opened from a cancelled run. + + + +## API versioning + +Cancellation introduces two API additions: a new `CANCELLED` value on the check-session status enum, and a new `isCancelled` boolean on individual check results. The `isCancelled` flag is additive and ships on every check-result and check-session response without a version bump. The status enum change is breaking for clients that switch on status values exhaustively, so the new `CANCELLED` value is only returned by the v2 check-session endpoints; v1 maps cancelled sessions to `TIMED_OUT` in `status` so existing clients continue to work unchanged. + + +[`POST /v1/check-sessions/trigger`](/api-reference/check-sessions/trigger-a-new-check-session), [`GET /v1/check-sessions/{checkSessionId}`](/api-reference/check-sessions/retrieve-a-check-session), and [`GET /v1/check-sessions/{checkSessionId}/completion`](/api-reference/check-sessions/await-the-completion-of-a-check-session) report cancelled sessions as `TIMED_OUT` in `status` rather than `CANCELLED`. Per-result objects still include `isCancelled`, so individual cancelled runs remain identifiable. + + + +[`POST /v2/check-sessions/trigger`](/api-reference/check-sessions/trigger-a-new-check-session-v2), [`GET /v2/check-sessions/{checkSessionId}`](/api-reference/check-sessions/retrieve-a-check-session-v2), and [`GET /v2/check-sessions/{checkSessionId}/completion`](/api-reference/check-sessions/await-the-completion-of-a-check-session-v2) return `CANCELLED` in `status` for cancelled sessions. Response shape is otherwise the same as v1. + + + +[`GET /v1/check-results/{checkId}/{checkResultId}`](/api-reference/check-results/retrieve-a-check-result) and the list endpoints include `isCancelled` on every result. + + + +[`POST /v1/check-sessions/{checkSessionId}/cancel`](/api-reference/check-sessions/cancel-a-check-session) and [`POST /v1/test-sessions/{testSessionId}/cancel`](/api-reference/test-sessions/cancel-a-test-session) are the action endpoints. Each takes the session ID in the path and an optional `sequenceId` array in the body. + + +If you build automation against check sessions and need to distinguish cancelled sessions from genuine timeouts at the session level, switch to the v2 endpoints. Otherwise, the `isCancelled` flag on per-result objects is available in both versions. diff --git a/concepts/results.mdx b/concepts/results.mdx index 8e07ea57..e868bacc 100644 --- a/concepts/results.mdx +++ b/concepts/results.mdx @@ -10,6 +10,10 @@ Each time a Check executes—whether it's testing an API endpoint, clicking thro **Results** are more than just pass or fail indicators. They're comprehensive records that include performance metrics, error details, screenshots, network traces, and any other telemetry that helps you understand not just whether something worked, but how well it worked and why it might have failed. + +Playwright Check Suite runs can also be [cancelled](/concepts/cancellation) while they are in progress. Cancelled results are excluded from availability and performance metrics. + + ## Understanding Result Data You can select any check on the main Checkly dashboard to get an overview of the results they have produced so far. diff --git a/docs.json b/docs.json index ba400626..112103ef 100644 --- a/docs.json +++ b/docs.json @@ -68,6 +68,7 @@ "concepts/locations", "concepts/scheduling", "concepts/results", + "concepts/cancellation", "concepts/metrics" ] }, @@ -733,8 +734,12 @@ "group": "Check Sessions", "pages": [ "api-reference/check-sessions/trigger-a-new-check-session", + "api-reference/check-sessions/trigger-a-new-check-session-v2", "api-reference/check-sessions/retrieve-a-check-session", - "api-reference/check-sessions/await-the-completion-of-a-check-session" + "api-reference/check-sessions/retrieve-a-check-session-v2", + "api-reference/check-sessions/await-the-completion-of-a-check-session", + "api-reference/check-sessions/await-the-completion-of-a-check-session-v2", + "api-reference/check-sessions/cancel-a-check-session" ] }, { @@ -927,6 +932,12 @@ "api-reference/status-pages/delete-a-subscription-belonging-to-a-specific-status-page" ] }, + { + "group": "Test Sessions", + "pages": [ + "api-reference/test-sessions/cancel-a-test-session" + ] + }, { "group": "Test Session Error Groups", "pages": [ diff --git a/style.css b/style.css index 04a16201..ef124f56 100644 --- a/style.css +++ b/style.css @@ -30,3 +30,9 @@ tr { font-weight: 700; font-size: 1.15rem; } + +.dark kbd { + background-color: rgba(255, 255, 255, 0.08); + border-color: rgba(255, 255, 255, 0.2); + color: #e6e6e6; +}