feat: improve error messages when using --forbid-only in CI

Author: RobinVdBroeck

lib/cli/run.js

@@ -26,6 +26,7 @@ const {ONE_AND_DONES, ONE_AND_DONE_ARGS} = require('./one-and-dones');
 const debug = require('debug')('mocha:cli:run');
 const defaults = require('../mocharc.json');
 const {types, aliases} = require('./run-option-metadata');
+const {isCI} = require('../utils');
 
 /**
  * Logical option groups
@@ -124,7 +125,7 @@ exports.builder = yargs =>
       'forbid-only': {
         description: 'Fail if exclusive test(s) encountered',
         group: GROUPS.RULES,
-        default: !!process.env.CI,
+        default: isCI()
       },
       'forbid-pending': {
         description: 'Fail if pending test(s) encountered',

lib/errors.js

@@ -9,6 +9,7 @@
 
 const {format} = require('node:util');
 const { constants } = require('./error-constants.js');
+const { isCI } = require('./utils');
 
 /**
  * Contains error codes, factory functions to create throwable error objects,
@@ -329,11 +330,17 @@ function createMultipleDoneError(runnable, originalErr) {
  * @returns {Error} Error with code {@link constants.FORBIDDEN_EXCLUSIVITY}
  */
 function createForbiddenExclusivityError(mocha) {
-  var err = new Error(
-    mocha.isWorker
-      ? '`.only` is not supported in parallel mode'
-      : '`.only` forbidden by --forbid-only'
-  );
+  var message;
+  if (mocha.isWorker) {
+    message = '`.only` is not supported in parallel mode';
+  } else {
+    message = '`.only` forbidden by --forbid-only';
+    if (isCI()) {
+      message += ' (default in CI, add `--no-forbid-only` to allow `.only`)';
+    }
+  }
+
+  var err = new Error(message);
   err.code = constants.FORBIDDEN_EXCLUSIVITY;
   return err;
 }

lib/utils.js

@@ -696,3 +696,17 @@ exports.breakCircularDeps = inputObj => {
 exports.isNumeric = input => {
   return !isNaN(parseFloat(input));
 };
+
+/**
+ * Checks if being ran in a CI environment.
+ *
+ * This uses the CI env variable, which is set by most popular CI providers. Some
+ * examples include:
+ * Github:     https://docs.github.com/en/actions/reference/workflows-and-actions/variables
+ * Gitlab:     https://docs.gitlab.com/ci/variables/predefined_variables/
+ * CircleCI:   https://circleci.com/docs/reference/variables/#built-in-environment-variables
+ * Bitbucket:  https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/
+ */
+exports.isCI = () => {
+  return !!process.env.CI;
+};