diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index 588e130dfd..c75ae60d65 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -8,6 +8,13 @@ sidebar_label: Changelog # Changelog +## 15.5.0 + +_Released 10/21/2025 (PENDING)_ + +**Features:** + +- When the `run` command requires successful negotiation with the Cypress Cloud API and the `--posix-exit-codes` flag is set, Cypress will now exit with code `112` when it cannot determine which spec to run next due to network conditions. These Cloud API negotiations are required when either `--record` or `--parallel` flags are set. Addresses [#32485](https://github.com/cypress-io/cypress/issues/32485). Addressed in [#32635](https://github.com/cypress-io/cypress/pull/32635). ## 15.4.0 _Released 10/7/2025_ diff --git a/docs/app/references/command-line.mdx b/docs/app/references/command-line.mdx index c59a92ed42..9825e914e1 100644 --- a/docs/app/references/command-line.mdx +++ b/docs/app/references/command-line.mdx @@ -442,14 +442,12 @@ cypress run --port 8080 #### `cypress run --posix-exit-codes` {#cypress-run-posix-exit-codes} -This changes the default behavior of Cypress regarding exit codes. This flag causes Cypress to exit with POSIX exit code of 1 when there are test failures or if Cypress could not run, rather than the number of tests that failed. +This changes the default behavior of Cypress regarding exit codes. This flag causes Cypress to exit with POSIX exit code of 1 when there are test failures or if Cypress could not run, rather than the number of tests that failed. It can return additional POSIX-compliant exit codes for other scenarios as well. See the [Exit Code section](/app/references/command-line#Exit-code) for a comprehensive reference of Cypress exit codes. ```shell cypress run --posix-exit-codes ``` -For more about Cypress' exit code behavior, see the [Exit Code section](/app/references/command-line#Exit-code). - #### `cypress run --project ` {#cypress-run-project-lt-project-path-gt} To see this in action we've set up an @@ -598,69 +596,20 @@ Cypress Cloud will display any tags sent with the appropriate run. #### Exit code -When Cypress finishes running tests, it exits. If there are no failed tests, the -exit code will be 0. - -```text -## All tests pass -$ cypress run -... - Tests Passing Failing - ✔ All specs passed! 00:16 17 17 0 - -## print exit code on Mac or Linux -$ echo $? -0 -``` - -By default, if there are any test failures, then the exit code will match the number of -tests that failed. - -```text -## Spec with two failing tests -$ cypress run -... - Tests Passing Failing - ✖ 1 of 1 failed (100%) 00:22 17 14 2 - -## print exit code on Mac or Linux -$ echo $? -2 -``` +Cypress supports two different exit code behaviors. The default behavior is similar to that of Mocha, but is not POSIX compliant: reserved exit codes can be returned for certain conditions. As well, the default behavior +can return a false negative when there are a number of tests that fail in multiples of 256: most terminals will apply modulo 256 to any exit code larger than 255. -You can change this behavior by passing the `--posix-exit-codes` flag. When this flag is passed, -the exit code will be 0 if all tests pass. If there are any test failures or if Cypress could not run, -the exit code will be 1. +POSIX compliant exit codes are available via the `--posix-exit-codes` flag. When this flag is passed, additional conditions can be returned that are not possible with the default behavior, including when Cypress fails due to +network errors when connections to Cypress Cloud are required, such as in `--record` or `--parallel` runs. -```text -## Spec with two failing tests -$ cypress run -... - Tests Passing Failing - ✖ 1 of 1 failed (100%) 00:22 17 14 2 +When using POSIX compliant exit codes, the number of failed tests can be determined from [structured reporter data](/app/tooling/reporters). -## print exit code on Mac or Linux -$ echo $? -1 -``` - -If Cypress could not run for some reason (for example if no spec files were -found) then the exit code will be 1. - -```text -## No spec files found -$ cypress run --spec not-found.js -... -Can't run because no spec files were found. - -We searched for any files matching this glob pattern: - -not-found.js - -## print exit code on Mac or Linux -$ echo $? -1 -``` +| Exit Condition | POSIX Exit Code (with `--posix-exit-codes`) | Default Exit Code (without `--posix-exit-codes`) | +| ------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------ | +| All tests pass | 0 | 0 | +| _n_ tests fail | 1 | _n_ | +| Cypress could not run due to a network error when connections to Cypress Cloud are required | 112 | 1 | +| Cypress could not run for any other reason, including no spec files found | 1 | 1 | ### `cypress open` @@ -1000,10 +949,11 @@ and with Windows CMD and PowerShell terminal windows. ## History -| Version | Changes | -| ------------------------------------------ | ---------------------------------------------------------- | -| [15.4.0](/app/references/changelog#15-4-0) | Added `--posix-exit-codes` flag to `cypress run` | -| [12.6.0](/app/references/changelog#12-6-0) | Added `--auto-cancel-after-failures` flag to `cypress run` | -| [5.4.0](/app/references/changelog) | Added `prune` subcommand to `cypress cache` | -| [5.4.0](/app/references/changelog) | Added `--size` flag to `cypress cache list` subcommand | -| [4.9.0](/app/references/changelog) | Added `--quiet` flag to `cypress run` | +| Version | Changes | +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- | +| [15.5.0](/app/references/changelog#15-5-0) | Modified exit code documentations from narrative to a reference table, adding the 112 exit code scenario | +| [15.4.0](/app/references/changelog#15-4-0) | Added `--posix-exit-codes` flag to `cypress run` | +| [12.6.0](/app/references/changelog#12-6-0) | Added `--auto-cancel-after-failures` flag to `cypress run` | +| [5.4.0](/app/references/changelog) | Added `prune` subcommand to `cypress cache` | +| [5.4.0](/app/references/changelog) | Added `--size` flag to `cypress cache list` subcommand | +| [4.9.0](/app/references/changelog) | Added `--quiet` flag to `cypress run` |