Missing exit option in the API documentation, and the NodeJS API

[regaldisclaimer]

Prerequisites

• Checked that your issue hasn't already been filed by cross-referencing issues with the faq label
• Checked next-gen ES issues and syntax problems by using the same environment and/or transpiler configuration without Mocha to ensure it isn't just a feature that actually isn't supported in the environment in question or a bug in your code.
• 'Smoke tested' the code to be tested by running it outside the real test suite to get a better sense of whether the problem is in the code under test, your usage of Mocha, or Mocha itself
• Ensured that there is no discrepancy between the locally and globally installed versions of Mocha. You can find them with: node node_modules/.bin/mocha --version(Local) and mocha --version(Global). We recommend that you not install Mocha globally.

Description

I commented here initially, but this seems to be an issue to be addressed, not just my inability to locate information.

The --exit option introduced in v4 is not incuded in the API documentation, and also seems to be missing from the JS runner.

Is this an intentional omission, or should it be added in? If it can be added in, that seems necessary considering how often the usage of this flag is recommended.

Steps to Reproduce

Try to locate the --exit option in the API documentation, or try to pass in the option in the JS runner.

Expected behavior: Expect to see the option in the API documentation, and have the ability to specify this option in the JS runner

Actual behavior: The flag is only specified on the landing page/"documentation", but is lacking on the API documentation, and is unavailable when using through the NodeJS API/Runner

Reproduces how often: N/A

Versions

Currently using v6.2.0, but the entry is found to be missing on current versions as well

• The output of mocha --version and node node_modules/.bin/mocha --version:
• The output of node --version:
• Your operating system
  • name and version:
  • architecture (32 or 64-bit):
• Your shell (e.g., bash, zsh, PowerShell, cmd):
• Your browser and version (if running browser tests):
• Any third-party Mocha-related modules (and their versions):
• Any code transpiler (e.g., TypeScript, CoffeeScript, Babel) being used (and its version):

Additional Information

[juergba]

@regaldisclaimer --exit is a CLI (command line interface) option only and documented here.
It has no functionality when using Mocha programmatically, so adding options.exit to the Mocha constructor would not have any effect.

When using Mocha programmatically you can terminate your Node process synchronously. Try:

mocha.run(function(failures) {
  process.exit(failures ? 1 : 0)
});

[regaldisclaimer]

@juergba Thanks for your response. Yes I am aware, and have noted in my initial post as such. However, the lack of an equivalent option causes certain scripts to stop working starting version 4.

For a script that is only running mocha, your posted code certainly gets the job done. However, for any scripts that need to execute tasks following a test, it does not offer the equivalent effect of having only mocha stop, rather than exiting entirely from the entire script.

This notably becomes an issue (as many discussions over this feature were made when the changes were introduced in v4) when one is running servers during tests. The exit flags were often suggested as a way to preserve the behavior prior to v4, which stops the servers after the tests complete.

Is there a way for mocha to stop, along with servers started during tests (truly equivalent of pre v4 behavior, or post v4 with the --exit flag) while using Mocha programmatically?

[juergba]

@regaldisclaimer The exit option has not been added to avoid a tear down after all tests have been completed.

• use before/beforeEach hooks to set up your test environment (as e.g. starting a server)
• use after/afterEach hooks to tear down your test environment (as e.g. stopping a server).

Intentionally using the exit option in order to avoid a correct clean-up after your tests is a dirty misuse. You should think about improving your tests.

Re Mocha <v4: I don't know, that's a long time ago. I'm not going to dig this one out. But I doubt there was a way to "exit" when using Mocha programatically.

[boneskull]

There is no way to do this using Mocha programmatically; you have to force-exit yourself once the run has completed. This is how the CLI does it.