Skip to content

docs: adds --posix-exit-codes cli flag for run mode #6284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Oct 6, 2025
Merged

docs: adds --posix-exit-codes cli flag for run mode #6284

Changes from 3 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
1798f78
adds --posix-exit-codes cli flag for run mode
cacieprins Sep 30, 2025
a11cdae
add history entry
cacieprins Sep 30, 2025
1cd41d3
clarify option/description table for --posix-exit-codes
cacieprins Sep 30, 2025
524b211
expand docs on posix exit codes
cacieprins Sep 30, 2025
be5d892
prettify bash block
cacieprins Sep 30, 2025
1fea008
fix changelog link
cacieprins Sep 30, 2025
bb8c67b
formatting
cacieprins Sep 30, 2025
e271a0a
Add posixExitCodes to module API page
jennifer-shehane Oct 6, 2025
9371c71
changelog
jennifer-shehane Oct 6, 2025
dffaa3f
lint fix
jennifer-shehane Oct 6, 2025
f259c7c
Merge branch 'release/15.4.0' into feat/posix-exit-codes
jennifer-shehane Oct 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion docs/app/references/command-line.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,6 +217,7 @@ cypress run [options]
| `--no-runner-ui` | [Hides the Cypress Runner UI](#cypress-run-no-runner-ui) |
| `--parallel` | [Run recorded specs in parallel across multiple machines](#cypress-run-parallel) |
| `--port`,`-p` | [Override default port](#cypress-run-port-lt-port-gt) |
| `--posix-exit-codes` | [Exit with a POSIX-compliant exit code](#cypress-run-posix-exit-codes) rather than the number of failed tests. |
| `--project`, `-P` | [Path to a specific project](#cypress-run-project-lt-project-path-gt) |
| `--quiet`, `-q` | [Reduce output to `stdout`](#cypress-run-quiet) |
| `--record` | [Whether to record the test run](#cypress-run-record-key-lt-record-key-gt) |
Expand Down Expand Up @@ -439,6 +440,14 @@ documentation to learn more.
cypress run --port 8080
```

#### `cypress run --posix-exit-codes` {#cypress-run-posix-exit-codes}

Exit with POSIX exit code of 1 when there are test failures or if Cypress could not run.

```shell
cypress run --posix-exit-codes
```

Comment on lines 443 to 450
Copy link
Contributor

@MikeMcC399 MikeMcC399 Sep 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe cross-link here to the section #Exit-code?

I completely missed this section when I glanced at the change 🤭

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea! Updated here 524b211

#### `cypress run --project <project-path>` {#cypress-run-project-lt-project-path-gt}

To see this in action we've set up an
Expand Down Expand Up @@ -602,7 +611,7 @@ $ echo $?
0
```

If there are any test failures, then the exit code will match the number of
By default, if there are any test failures, then the exit code will match the number of
tests that failed.

```text
Expand All @@ -617,6 +626,22 @@ $ echo $?
2
```

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.

```text
## Spec with two failing tests
$ cypress run --posix-exit-codes
...
```

```text
## print exit code on Mac or Linux
Comment on lines 638 to 642
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
...
```
```text
## print exit code on Mac or Linux
...
## print exit code on Mac or Linux

Merge into one code block like the other examples above.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

$ 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.

Expand Down Expand Up @@ -975,6 +1000,7 @@ and with Windows CMD and PowerShell terminal windows.

| 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 |
Expand Down