v2 release notes

v2 is a new version of mocha-parallel-tests rewritten in TypeScript from scratch. Its primary focus is to simplify parallelisation of mocha tests: while previously they were executed in one single process now each file is executed in a separate process. You can see the list of breaking changes in the changelog. This page covers most of the changes occurred in version 2 from the code features perspective.

Parallelisation

This is the main thing happened to mocha-parallel-tests. In v1 each test file was executed in the same process and scope. Also, there was an uncertainty about what's running in parallel: files, top-level test suites or even nested test suites. v2 makes it easy: each file is now executed in its process and doesn't share variables with the other files. If the file contains multiple test suites or nested test suites in it they are executed normally like mocha does it, i.e. there's no parallelisation inside one file.

Internally mocha-parallel-tests is using child_process.fork() to fork subprocesses for each file. By default, the number of simultaneously running subprocesses is equal to the number of logical CPU cores on your machine, but you can also specify it manually (--max-parallel 4) or set it to zero (--max-parallel 0) to launch all your test files at the same time. However, according to Node.js docs, your tests performance can suffer from this:

Each process has its own memory, with their own V8 instances. Because of the additional resource allocations required, spawning a large number of child Node.js processes is not recommended.

From a technical perspective, all communication between the main process and subprocesses is going through the IPC channel with help from circular-json package. Andrea @WebReflection thank you for this library!

Tests and CLI options

Thanks to mocha-parallel-tests contributors @mmotkina, @k03mad, @1999, @kolontsov and @furstenheim there had been lots of tests before v2 development started. These tests are in JavaScript, and most of them stay untouched in v2. However, there were some changes:

• --retry N option is not supported anymore because the main target was to be 100%-compliant with mocha regarding API and to not introduce its specific options and APIs other than --max-parallel. Actually mocha-parallel-tests is heavily using mocha programmatic API in each of the subprocesses and it would be hard to support its own option without monkeypatching the mocha code. Because of that five tests related to --retry have been removed from the repo.
• --retries N option of mocha is now supported and covered with a test. This option allows you to re-run test cases (aka it()) and you should consider using it instead of mocha-parallel-tests custom --retry option.
• --delay option of mocha is now supported and covered with a test.

Programmatic API

v2 is written in TypeScript with default export in the main file. Default exports in ES6 modules do not convert naturally into CommonJS default exports. That's why if you want to use mocha-parallel-tests v2 programmatically you should change your code a bit:

// v1
const MochaParallelTests = require('mocha-parallel-tests'); // CommonJS

// v2
const MochaParallelTests = require('mocha-parallel-tests').default; // CommonJS
import MochaParallelTests from 'mocha-parallel-tests'; // ES6 modules or TypeScript

Reporter

The main change happened to all reporters is that each file now gives an additional suite. Let's take mocha JSON reporter and 2 test files where each has one test suite with 2 test cases in it. If you pass these files to mocha you see that the number of suites is 2 and it was also 2 for mocha-parallel-tests v1. mocha-parallel-tests v2 runs all files in separate processes which technically means that each file's top-level suite is then merged into the main process top level suite. I.e. you see not 2 but 4 suites in the output.

From default spec reporter UI perspective you see additional indentation for your tests because this is how it renders suites. For example, this is the mocha reporter output:

And this is mocha-parallel-tests v2 reporter output:

Misc

There's also a bunch of other changes happened in v2 release:

• minimum supported node version is now 8. Mainly it's because this is the current LTS and mocha-parallel-tests is heavily using async/await
• supported peerDependencies versions of mocha are now 3, 4 and 5. This is not just a one line change: mocha-parallel-tests runs its tests with all of these versions of mocha to check that.
• mocha-parallel-tests npm install should work fine on windows. This is checked by an AppVeyor integration. However, there are still 7 tests failing on Windows, so this is a significant contribution if you want to help the project.