☕️ Classic, reliable, trusted test framework for Node.js and the browser
docs: sync CLI docs with v12 options and defaults (#6140)
Mostafa Nazari579fd1563822
diff --git a/docs/src/content/docs/declaring/exclusive-tests.mdx b/docs/src/content/docs/declaring/exclusive-tests.mdxindex 1499ccdc..01f1e2b6 100644--- a/docs/src/content/docs/declaring/exclusive-tests.mdx+++ b/docs/src/content/docs/declaring/exclusive-tests.mdx@@ -108,5 +108,6 @@ Hooks, if present, will still be executed.:::tipBe mindful not to commit usages of `.only()` to version control, unless you really mean it!-To do so one can run mocha with the option `--forbid-only` in the continuous integration test command (or in a git precommit hook).+Since v12, Mocha guards against this by default in continuous integration: [`--forbid-only`](/running/cli#--forbid-only) defaults to `true` when the `CI` environment variable is set.+On older versions or outside of CI (for example in a git precommit hook), pass `--forbid-only` explicitly.:::diff --git a/docs/src/content/docs/running/cli.mdx b/docs/src/content/docs/running/cli.mdxindex cfcc9caf..0a0a1108 100644--- a/docs/src/content/docs/running/cli.mdx+++ b/docs/src/content/docs/running/cli.mdx@@ -30,6 +30,8 @@ Rules & Behavior[boolean]--pass-on-failing-test-suite Not fail test run if tests were failed[boolean] [default: false]+ --fail-hook-affected-tests Report tests as failed when affected by hook+ failures (before/beforeEach) [boolean]--fail-zero Fail test run if no test(s) encountered[boolean]--forbid-only Fail if exclusive test(s) encountered@@ -40,6 +42,8 @@ Rules & Behavioruse 1 to run in serial[number] [default: (number of CPU cores - 1)]-p, --parallel Run tests in parallel [boolean]+ --posix-exit-codes Use POSIX and UNIX shell exit codes as+ Mocha's return value [boolean]--retries Retry failed tests this many times [number]-s, --slow Specify "slow" test threshold (inmilliseconds) [string] [default: 75]@@ -183,6 +187,14 @@ To ensure your tests aren't leaving messes around, here are some ideas to get stIf set to `true`, Mocha returns exit code `0` even if there are failed tests during the run.+### `--fail-hook-affected-tests`++:::note[New in v12.0.0]+:::++When a `before` or `beforeEach` hook fails, Mocha skips the tests affected by that hook; only the hook itself is reported as a failure.+Use `--fail-hook-affected-tests` to also report each affected test as failed.+### `--fail-zero`:::note[New in v9.1.0]@@ -196,6 +208,13 @@ Enforce a rule that tests may not be exclusive (use of e.g., `describe.only()` o`--forbid-only` causes Mocha to fail when an exclusive ("only'd") test or suite is encountered, and it will abort further test execution.+:::note[Updated in v12.0.0]+Before v12, `--forbid-only` defaulted to `false`.+Since v12, it defaults to `true` when the `CI` environment variable is set, and `false` otherwise.+Most CI providers, like GitHub Actions and GitLab, set `CI` automatically.+Use `--no-forbid-only` to allow exclusive tests in CI.+:::+### `--forbid-pending`Enforce a rule that tests may not be skipped (use of e.g., `describe.skip()`, `it.skip()`, or `this.skip()` anywhere is disallowed).@@ -248,6 +267,21 @@ Each test file will be put into a queue and executed as workers become availableRead more about [running tests in parallel](/features/parallel-mode).:::+### `--posix-exit-codes`++:::note[New in v11.3.0]+:::++Exits with standard POSIX exit codes instead of the number of failed tests.++Those exit codes are:++- `0`: if all tests passed+- `1`: if any test failed+- `128 + <signal>` if given a signal, such as:+ - 134: `SIGABRT` (`128 + 6`)+ - 143: `SIGTERM` (`128 + 15`)+### `--retries <n>`Retries failed tests `n` times.