☕️ Classic, reliable, trusted test framework for Node.js and the browser
feat: add option to use posix exit code upon fatal signal (#4989)
Darren DeRidder91bbf855012e
diff --git a/bin/mocha.js b/bin/mocha.jsold mode 100644new mode 100755index 8970d1bd..d6359cd3--- a/bin/mocha.js+++ b/bin/mocha.js@@ -10,6 +10,7 @@* @private*/+const os = require('node:os');const {loadOptions} = require('../lib/cli/options');const {unparseNodeFlags,@@ -22,6 +23,7 @@ const {aliases} = require('../lib/cli/run-option-metadata');const mochaArgs = {};const nodeArgs = {};+const SIGNAL_OFFSET = 128;let hasInspect = false;const opts = loadOptions(process.argv.slice(2));@@ -109,9 +111,13 @@ if (mochaArgs['node-option'] || Object.keys(nodeArgs).length || hasInspect) {proc.on('exit', (code, signal) => {process.on('exit', () => {if (signal) {+ signal = typeof signal === 'string' ? os.constants.signals[signal] : signal;+ if (mochaArgs['posix-exit-codes'] === true) {+ process.exitCode = SIGNAL_OFFSET + signal;+ }process.kill(process.pid, signal);} else {- process.exit(code);+ process.exit(Math.min(code, mochaArgs['posix-exit-codes'] ? 1 : 255));}});});@@ -126,7 +132,7 @@ if (mochaArgs['node-option'] || Object.keys(nodeArgs).length || hasInspect) {// be needed.if (!args.parallel || args.jobs < 2) {// win32 does not support SIGTERM, so use next best thing.- if (require('node:os').platform() === 'win32') {+ if (os.platform() === 'win32') {proc.kill('SIGKILL');} else {// using SIGKILL won't cleanly close the output streams, which can resultdiff --git a/docs/index.md b/docs/index.mdindex d456ed61..4fc8aa8d 100644--- a/docs/index.md+++ b/docs/index.md@@ -963,6 +963,18 @@ Define a global variable name. For example, suppose your app deliberately exposeBy using this option in conjunction with `--check-leaks`, you can specify a whitelist of known global variables that you _expect_ to leak into global scope.+### `--posix-exit-codes`++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.diff --git a/lib/cli/run-helpers.js b/lib/cli/run-helpers.jsindex a7e631b7..99396974 100644--- a/lib/cli/run-helpers.js+++ b/lib/cli/run-helpers.js@@ -27,7 +27,7 @@ const {UnmatchedFile} = require('./collect-files');*/const exitMochaLater = clampedCode => {process.on('exit', () => {- process.exitCode = clampedCode;+ process.exitCode = Math.min(clampedCode, process.argv.includes('--posix-exit-codes') ? 1 : 255);});};@@ -39,6 +39,8 @@ const exitMochaLater = clampedCode => {* @private*/const exitMocha = clampedCode => {+ const usePosixExitCodes = process.argv.includes('--posix-exit-codes');+ clampedCode = Math.min(clampedCode, usePosixExitCodes ? 1 : 255);let draining = 0;// Eagerly set the process's exit code in case stream.write doesn'tdiff --git a/lib/cli/run-option-metadata.js b/lib/cli/run-option-metadata.jsindex df967097..de553ef9 100644--- a/lib/cli/run-option-metadata.js+++ b/lib/cli/run-option-metadata.js@@ -46,6 +46,7 @@ const TYPES = (exports.types = {'list-reporters','no-colors','parallel',+ 'posix-exit-codes','recursive','sort','watch'diff --git a/lib/cli/run.js b/lib/cli/run.jsindex 5f42c508..561592b9 100644--- a/lib/cli/run.js+++ b/lib/cli/run.js@@ -195,6 +195,10 @@ exports.builder = yargs =>description: 'Run tests in parallel',group: GROUPS.RULES},+ 'posix-exit-codes': {+ description: 'Use POSIX and UNIX shell exit codes as Mocha\'s return value',+ group: GROUPS.RULES+ },recursive: {description: 'Look for tests in subdirectories',group: GROUPS.FILESdiff --git a/test/integration/fixtures/failing.fixture.js b/test/integration/fixtures/failing.fixture.jsnew file mode 100644index 00000000..337d6289--- /dev/null+++ b/test/integration/fixtures/failing.fixture.js@@ -0,0 +1,23 @@+'use strict';++// One passing test and three failing tests++var assert = require('assert');++describe('suite', function () {+ it('test1', function () {+ assert(true);+ });++ it('test2', function () {+ assert(false);+ });++ it('test3', function () {+ assert(false);+ });++ it('test4', function () {+ assert(false);+ });+});diff --git a/test/integration/fixtures/signals-sigabrt.fixture.js b/test/integration/fixtures/signals-sigabrt.fixture.jsnew file mode 100644index 00000000..03711109--- /dev/null+++ b/test/integration/fixtures/signals-sigabrt.fixture.js@@ -0,0 +1,7 @@+'use strict';++describe('signal suite', function () {+ it('test SIGABRT', function () {+ process.kill(process.pid, 'SIGABRT');+ });+});diff --git a/test/integration/fixtures/signals-sigterm-numeric.fixture.js b/test/integration/fixtures/signals-sigterm-numeric.fixture.jsnew file mode 100644index 00000000..a396e126--- /dev/null+++ b/test/integration/fixtures/signals-sigterm-numeric.fixture.js@@ -0,0 +1,8 @@+'use strict';+const os = require('node:os');++describe('signal suite', function () {+ it('test SIGTERM', function () {+ process.kill(process.pid, os.constants.signals['SIGTERM']);+ });+});diff --git a/test/integration/fixtures/signals-sigterm.fixture.js b/test/integration/fixtures/signals-sigterm.fixture.jsnew file mode 100644index 00000000..2f1d01c7--- /dev/null+++ b/test/integration/fixtures/signals-sigterm.fixture.js@@ -0,0 +1,7 @@+'use strict';++describe('signal suite', function () {+ it('test SIGTERM', function () {+ process.kill(process.pid, 'SIGTERM');+ });+});diff --git a/test/integration/helpers.js b/test/integration/helpers.jsindex 16a2ed89..a6ab867a 100644--- a/test/integration/helpers.js+++ b/test/integration/helpers.js@@ -8,6 +8,7 @@ const {format} = require('node:util');const path = require('node:path');const Base = require('../../lib/reporters/base');const debug = require('debug')('mocha:test:integration:helpers');+const SIGNAL_OFFSET = 128;/*** Path to `mocha` executable@@ -358,6 +359,18 @@ function createSubprocess(args, done, opts = {}) {});});+ /**+ * Emulate node's exit code for fatal signal. Allows tests to see the same+ * exit code as the mocha cli.+ */+ mocha.on('exit', (code, signal) => {+ if (signal) {+ mocha.exitCode =+ SIGNAL_OFFSET ++ (typeof signal == 'string' ? os.constants.signals[signal] : signal);+ }+ });+return mocha;}diff --git a/test/integration/options/posixExitCodes.spec.js b/test/integration/options/posixExitCodes.spec.jsnew file mode 100644index 00000000..51099339--- /dev/null+++ b/test/integration/options/posixExitCodes.spec.js@@ -0,0 +1,172 @@+'use strict';++var helpers = require('../helpers');+var runMocha = helpers.runMocha;+var os = require('node:os');++const EXIT_SUCCESS = 0;+const EXIT_FAILURE = 1;+const SIGNAL_OFFSET = 128;++describe('--posix-exit-codes', function () {+ if (os.platform() !== 'win32') {+ describe('when enabled', function () {+ describe('when mocha is run as a child process', () => {+ // 'no-warnings' node option makes mocha run as a child process+ const args = ['--no-warnings', '--posix-exit-codes'];++ it('should exit with correct POSIX shell code on SIGABRT', function (done) {+ var fixture = 'signals-sigabrt.fixture.js';+ runMocha(fixture, args, function postmortem(err, res) {+ if (err) {+ return done(err);+ }+ expect(+ res.code,+ 'to be',+ SIGNAL_OFFSET + os.constants.signals.SIGABRT+ );+ done();+ });+ });++ it('should exit with correct POSIX shell code on SIGTERM', function (done) {+ // SIGTERM is not supported on Windows+ if (os.platform() !== 'win32') {+ var fixture = 'signals-sigterm.fixture.js';+ runMocha(fixture, args, function postmortem(err, res) {+ if (err) {+ return done(err);+ }+ expect(+ res.code,+ 'to be',+ SIGNAL_OFFSET + os.constants.signals.SIGTERM+ );+ done();+ });+ } else {+ done();+ }+ });++ it('should exit with the correct POSIX shell code on numeric fatal signal', function (done) {+ // not supported on Windows+ if (os.platform() !== 'win32') {+ var fixture = 'signals-sigterm-numeric.fixture.js';+ runMocha(fixture, args, function postmortem(err, res) {+ if (err) {+ return done(err);+ }+ expect(+ res.code,+ 'to be',+ SIGNAL_OFFSET + os.constants.signals.SIGTERM+ );+ done();+ });+ } else {+ done();+ }+ });++ it('should exit with code 1 if there are test failures', function (done) {+ var fixture = 'failing.fixture.js';+ runMocha(fixture, args, function postmortem(err, res) {+ if (err) {+ return done(err);+ }+ expect(res.code, 'to be', EXIT_FAILURE);+ done();+ });+ });+ });++ describe('when mocha is run in-process', () => {+ // Without node-specific cli options, mocha runs in-process+ const args = ['--posix-exit-codes'];++ it('should exit with the correct POSIX shell code on SIGABRT', function (done) {+ var fixture = 'signals-sigabrt.fixture.js';+ runMocha(fixture, args, function postmortem(err, res) {+ if (err) {+ return done(err);+ }+ expect(+ res.code,+ 'to be',+ SIGNAL_OFFSET + os.constants.signals.SIGABRT+ );+ done();+ });+ });++ it('should exit with the correct POSIX shell code on SIGTERM', function (done) {+ // SIGTERM is not supported on Windows+ if (os.platform() !== 'win32') {+ var fixture = 'signals-sigterm.fixture.js';+ runMocha(fixture, args, function postmortem(err, res) {+ if (err) {+ return done(err);+ }+ expect(+ res.code,+ 'to be',+ SIGNAL_OFFSET + os.constants.signals.SIGTERM+ );+ done();+ });+ } else {+ done();+ }+ });++ it('should exit with code 1 if there are test failures', function (done) {+ var fixture = 'failing.fixture.js';+ runMocha(fixture, args, function postmortem(err, res) {+ if (err) {+ return done(err);+ }+ expect(res.code, 'to be', EXIT_FAILURE);+ done();+ });+ });+ });+ });++ describe('when not enabled', function () {+ describe('when mocha is run as a child process', () => {+ // any node-specific option makes mocha run as a child process+ var args = ['--no-warnings'];++ it('should exit with the number of failed tests', function (done) {+ var fixture = 'failing.fixture.js';+ var numFailures = 3;+ runMocha(fixture, args, function postmortem(err, res) {+ if (err) {+ return done(err);+ }+ expect(res.code, 'to be', numFailures);+ done();+ });+ });+ });++ describe('when mocha is run in-process', () => {+ var args = [];++ it('should exit with the number of failed tests', function (done) {+ var fixture = 'failing.fixture.js';+ var numFailures = 3;+ runMocha(fixture, args, function postmortem(err, res) {+ if (err) {+ return done(err);+ }+ expect(res.code, 'to be', numFailures);+ done();+ });+ });+ });+ });+ }+});