From 550fe8f53543024f2e2c47a511529ecefb9c768b Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Fri, 23 Oct 2026 21:41:24 +0900 Subject: [PATCH] docs: document --max-failures and cli.maxFailures [RED-1227] Co-Authored-By: Claude Opus 5.5 --- cli/checkly-test.mdx | 29 +++++++++++++++++++++++++++++ cli/checkly-trigger.mdx | 29 +++++++++++++++++++++++++++++ constructs/project.mdx | 1 + 3 files changed, 59 insertions(+) diff --git a/cli/checkly-test.mdx b/cli/checkly-test.mdx index 08b4c85f..f83bb243 100644 --- a/cli/checkly-test.mdx +++ b/cli/checkly-test.mdx @@ -29,6 +29,7 @@ npx checkly test [arguments] [options] | `--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. | +| `--max-failures` | - | Stop waiting for the remaining checks once this many checks have failed, and exit with a failing status code. | | `--private-location` | - | The private location to run checks at. | | `--[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. | @@ -156,6 +157,34 @@ npx checkly test -l="eu-west-1" + + +Stop waiting for the remaining checks once this many checks have failed (a whole number of 1 or more), and exit with a failing status code. Use it in CI to see a broken change fail early instead of waiting for the whole run. Overrides `cli.maxFailures` in your Checkly config. + +Only a check's final result counts toward the limit: a check that passes after a retry does not count, and neither does a degraded check. If the failure that reaches the limit is the last check to finish, the run completes normally. + +When the limit is reached, the CLI writes its reports, marks the remaining checks as not finished, and asks Checkly to cancel the test session. Only some check types, such as Playwright Check Suites, can be cancelled once they are running, so other checks may still run to completion in Checkly. The `json` reporter gives those checks `"result": "Not finished"` and adds a top-level `"stoppedEarly": { "reason": "maxFailures", "maxFailures": }` field. + +Cannot be combined with `--detach` or `--update-snapshots`. + +**Usage:** + +```bash Terminal +npx checkly test --max-failures=1 +``` + +**Examples:** + +```bash Terminal +# Stop at the first failed check +npx checkly test --max-failures=1 + +# Retry failing checks, and stop once three checks still fail after their retries +npx checkly test --retries=2 --max-failures=3 +``` + + + The private location to run checks at. diff --git a/cli/checkly-trigger.mdx b/cli/checkly-trigger.mdx index addf9c71..21bd1139 100644 --- a/cli/checkly-trigger.mdx +++ b/cli/checkly-trigger.mdx @@ -28,6 +28,7 @@ npx checkly trigger [options] | `--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. | +| `--max-failures` | - | Stop waiting for the remaining checks once this many checks have failed, and exit with a failing status code. | | `--private-location` | - | The private location to run checks at. | | `--[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. | @@ -144,6 +145,34 @@ npx checkly trigger -l="us-east-1" Choose from available Checkly public locations like us-east-1, eu-west-1, ap-southeast-1, etc. + + +Stop waiting for the remaining checks once this many checks have failed (a whole number of 1 or more), and exit with a failing status code. Use it in CI to see a broken change fail early instead of waiting for the whole run. Overrides `cli.maxFailures` in your Checkly config. + +Only a check's final result counts toward the limit: a check that passes after a retry does not count, and neither does a degraded check. If the failure that reaches the limit is the last check to finish, the run completes normally. + +When the limit is reached, the CLI writes its reports, marks the remaining checks as not finished, and asks Checkly to cancel the test session. Only some check types, such as Playwright Check Suites, can be cancelled once they are running, so other checks may still run to completion in Checkly. The `json` reporter gives those checks `"result": "Not finished"` and adds a top-level `"stoppedEarly": { "reason": "maxFailures", "maxFailures": }` field. + +Cannot be combined with `--detach`. + +**Usage:** + +```bash Terminal +npx checkly trigger --max-failures=1 +``` + +**Examples:** + +```bash Terminal +# Stop at the first failed check +npx checkly trigger --max-failures=1 + +# Retry failing checks, and stop once three checks still fail after their retries +npx checkly trigger --retries=2 --max-failures=3 +``` + + + The private location to run checks at. diff --git a/constructs/project.mdx b/constructs/project.mdx index 13a038dd..c57ca462 100644 --- a/constructs/project.mdx +++ b/constructs/project.mdx @@ -151,6 +151,7 @@ export default defineConfig({ | `runLocation` | `string` | ❌ | - | Default location for `checkly test` and `checkly trigger` | | `privateRunLocation` | `string` | ❌ | - | Default private location for CLI commands | | `retries` | `number` | ❌ | `0` | Default retry count for failing checks (max 3) | +| `maxFailures` | `number` | ❌ | - | Stop `checkly test` and `checkly trigger` once this many checks have failed. The `--max-failures` flag overrides it. See [`checkly test`](/cli/checkly-test) | **Use cases**: Local testing defaults, CI/CD configuration, development workflow.