Skip to content

Commit daf80e2

Browse files
cacieprinsjennifer-shehane
cacieprins
and
jennifer-shehane
authored
docs: Adds documentation for the 112 exit code when posix-compliant exit codes are enabled. (#6294)
* docs: exit code 112 for cloud api network errors * docs: detailed exit code scenarios * changelog * fix ref for modulus behavior on test fail count * edit pass * Update changelog.mdx * Update changelog.mdx * rm feature release note, keep version heading for linkage * Update docs/app/references/command-line.mdx * Update docs/app/references/command-line.mdx * lint fix --------- Co-authored-by: Jennifer Shehane <[email protected]> Co-authored-by: Jennifer Shehane <[email protected]>
1 parent d0ba53f commit daf80e2

File tree

2 files changed

+24
-70
lines changed

2 files changed

+24
-70
lines changed

‎docs/app/references/changelog.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ sidebar_label: Changelog
88

99
# Changelog
1010

11+
## 15.5.0
12+
13+
_Released 10/21/2025 (PENDING)_
14+
1115
## 15.4.0
1216

1317
_Released 10/7/2025_

‎docs/app/references/command-line.mdx‎

Lines changed: 20 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -442,14 +442,12 @@ cypress run --port 8080
442442
443443
#### `cypress run --posix-exit-codes` {#cypress-run-posix-exit-codes}
444444
445-
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.
445+
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.
446446
447447
```shell
448448
cypress run --posix-exit-codes
449449
```
450450
451-
For more about Cypress' exit code behavior, see the [Exit Code section](/app/references/command-line#Exit-code).
452-
453451
#### `cypress run --project <project-path>` {#cypress-run-project-lt-project-path-gt}
454452
455453
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.
598596
599597
#### Exit code
600598
601-
When Cypress finishes running tests, it exits. If there are no failed tests, the
602-
exit code will be 0.
603-
604-
```text
605-
## All tests pass
606-
$ cypress run
607-
...
608-
Tests Passing Failing
609-
✔ All specs passed! 00:16 17 17 0
610-
611-
## print exit code on Mac or Linux
612-
$ echo $?
613-
0
614-
```
615-
616-
By default, if there are any test failures, then the exit code will match the number of
617-
tests that failed.
618-
619-
```text
620-
## Spec with two failing tests
621-
$ cypress run
622-
...
623-
Tests Passing Failing
624-
✖ 1 of 1 failed (100%) 00:22 17 14 2
625-
626-
## print exit code on Mac or Linux
627-
$ echo $?
628-
2
629-
```
599+
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
600+
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.
630601
631-
You can change this behavior by passing the `--posix-exit-codes` flag. When this flag is passed,
632-
the exit code will be 0 if all tests pass. If there are any test failures or if Cypress could not run,
633-
the exit code will be 1.
602+
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
603+
network errors when connections to Cypress Cloud are required, such as in `--record` or `--parallel` runs.
634604
635-
```text
636-
## Spec with two failing tests
637-
$ cypress run
638-
...
639-
Tests Passing Failing
640-
✖ 1 of 1 failed (100%) 00:22 17 14 2
605+
When using POSIX compliant exit codes, the number of failed tests can be determined from the [Module API](/app/references/module-api) or [structured reporter data](/app/tooling/reporters).
641606
642-
## print exit code on Mac or Linux
643-
$ echo $?
644-
1
645-
```
646-
647-
If Cypress could not run for some reason (for example if no spec files were
648-
found) then the exit code will be 1.
649-
650-
```text
651-
## No spec files found
652-
$ cypress run --spec not-found.js
653-
...
654-
Can't run because no spec files were found.
655-
656-
We searched for any files matching this glob pattern:
657-
658-
not-found.js
659-
660-
## print exit code on Mac or Linux
661-
$ echo $?
662-
1
663-
```
607+
| Exit Condition | POSIX Exit Code (with `--posix-exit-codes`) | Default Exit Code (without `--posix-exit-codes`) |
608+
| ------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------ |
609+
| All tests pass | 0 | 0 |
610+
| _n_ tests fail | 1 | _n_ |
611+
| Cypress could not run due to a network error when connections to Cypress Cloud are required | 112 | 1 |
612+
| Cypress could not run for any other reason, including no spec files found | 1 | 1 |
664613
665614
### `cypress open`
666615
@@ -1000,10 +949,11 @@ and with Windows CMD and PowerShell terminal windows.
1000949
1001950
## History
1002951
1003-
| Version | Changes |
1004-
| ------------------------------------------ | ---------------------------------------------------------- |
1005-
| [15.4.0](/app/references/changelog#15-4-0) | Added `--posix-exit-codes` flag to `cypress run` |
1006-
| [12.6.0](/app/references/changelog#12-6-0) | Added `--auto-cancel-after-failures` flag to `cypress run` |
1007-
| [5.4.0](/app/references/changelog) | Added `prune` subcommand to `cypress cache` |
1008-
| [5.4.0](/app/references/changelog) | Added `--size` flag to `cypress cache list` subcommand |
1009-
| [4.9.0](/app/references/changelog) | Added `--quiet` flag to `cypress run` |
952+
| Version | Changes |
953+
| ------------------------------------------ | --------------------------------------------------------------------- |
954+
| [15.5.0](/app/references/changelog#15-5-0) | Added the 112 exit code scenario when using `--posix-exit-codes` flag |
955+
| [15.4.0](/app/references/changelog#15-4-0) | Added `--posix-exit-codes` flag to `cypress run` |
956+
| [12.6.0](/app/references/changelog#12-6-0) | Added `--auto-cancel-after-failures` flag to `cypress run` |
957+
| [5.4.0](/app/references/changelog) | Added `prune` subcommand to `cypress cache` |
958+
| [5.4.0](/app/references/changelog) | Added `--size` flag to `cypress cache list` subcommand |
959+
| [4.9.0](/app/references/changelog) | Added `--quiet` flag to `cypress run` |

0 commit comments

Comments
 (0)