@johanblumenberg/mocha

simple, flexible, fun test framework

Usage no npm install needed!

<script type="module">
  import johanblumenbergMocha from 'https://cdn.skypack.dev/@johanblumenberg/mocha';
</script>

README

@johanblumenberg/mocha

Fork of mocha, which will be kept until the following PRs are accepted, or similar functionality is added to mocha:

Purpose

The focus of this fork is hardening of mocha, to make it robust enough to run in a CI environment.

If tests are aquiring external resources, it is important that those resources are always released after the test is done. This fork is making sure that all after hooks are always run, regardless of how mocha is terminated, and regardless if tests are failing or not.

There are also a few commits that improve troubleshooting in such environments.

Added functionality in this fork

Listen to events

It can be useful for a test to be able to know when a test starts, fails, passes, and so on. The same events that are exposed to reporters are also exposed to tests to listen for.

Example:

describe('test a web page', function () {
    var webdriver;

    before(function() {
        webdriver = ... // Set up a webdriver pointing to my web paage

        this.events.on('test', function (test) {
            webdriver.log('Starting test ' + test.fullTitle());
        });

        this.events.on('test end', function (test) {
            webdriver.log('Passing test ' + test.fullTitle());
        });

        this.events.on('fail', (test, err) => {
            webdriver.log('Failing test ' + test.fullTitle());

            let logs = webdriver.getLogs();
            console.log(logs);
        });
    });
});

This simple example is testing a web page using webdriver. When a test starts and ends, a message is logged to the browser console, to make it easier to correlate the browser console log with the tests that are run. When a test fails, the browser console log is collected and logged to the test console.

--cleanup-after <ms> option

The default behaviour is to kill the mocha process immediately when receiving SIGINT or SIGTERM. Adding --cleanup-after will make mocha abort the current test, run all after hooks, and then terminate.

It is useful to have all after hooks run before exiting, for example if there are after hooks that are releasing up external resources, that would otherwise leak when pressing Ctrl-C.

The argument to --cleanup-after is a timeout in milliseconds, after which the mocha process will be forcefully terminated if the after hooks still have not completed.

--repeat <n> option

Used to repeat the test suite a number of times.

This is useful to catch hard to reproduce errors, together with the --bail option.

--leak-timeout <ms> option

If there are leaked resources after the last test completes, such as timers or child processes, the mocha process might not terminate. This option sets the timeout value, in millisecond from when the last test completes, for when to forcefully terminate the mocha process.

The default value is 60s.

--bucket <m>:<n> option

This option is for running tests in parallel, possibly on separate machines. This option will split the test suite in <n> buckets, and run the tests in bucket #<m>.

To spread out the tests over 3 mahines, and run a third of the tests on each machine, run the same command on each machine, but add the --bucket option:

# On machine 1
$ mocha spec/**/*.js --bucket 1:3

# On machine 2
$ mocha spec/**/*.js --bucket 2:3

# On machine 3
$ mocha spec/**/*.js --bucket 3:3

--grepv <pattern>

Used to exclude tests from running. Can be combined with --grep and --invert.

For example, this will run all tests containing abc, except those containing abcdef

$ mocha spec/**/*.js --grep abc --grepv abcdef

--exclude-from <file>

This is used to exclude tests from a file.

The format of the file is the same as generated by the json reporter.

This can be useful to be able to run only the tests that are new. If test results are recorded when running on master, this information can be used to identify which tests that are added.

The example below will use the test results from a master build to identify which tests are new, and run those tests 10 times.

$ mocha **/*.spec.js --exclude-from master-test-results.json --repeat 10