-
Notifications
You must be signed in to change notification settings - Fork 45
v2 release notes
v2 is a completely new version of mocha-parallel-tests
rewritten in TypeScript from scratch. Its main focus is to simplify parallel run 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 occured in version 2 from the code features perspective.
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 own process and doesn't share variables with the other files. If the file contains multiple test suites or nested test suites in it they will be executed normally like mocha
does it, i.e. there's no parallelization inside one file.
Internally mocha-parallel-tests
is using child_process.fork() to fork subprocesses for each file and IPC channel to communicate between the main process and subprocesses. By default the number of subprocesses is equal to the number of logical CPU cores on your machine but you can also specify it manually (example: --max-parallel 4
) or set it to zero (example: --max-parallel 0
) to launch all your test files simultaneously. However according to Node.js docs your 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 technical perspective all communication between the main process and subprocesses is being done through the IPC channel with a help from circular-json package. Andrea @WebReflection thank you for this library!
Thanks to mocha-parallel-tests
contributors @mmotkina, @k03mad, @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 withmocha
in terms of API and to not introduce its own options and APIs other than--max-parallel
. Actuallymocha-parallel-tests
is heavily usingmocha
programmatic API in each of the subprocesses and it would be hard to support its own option without monkeypatching themocha
code. Because of that five tests related to--retry
have been removed from the repo. -
--retries N
option ofmocha
is now supported and covered with test. This option allows you to re-run test cases (akait()
) and you should consider using it instead ofmocha-parallel-tests
custom--retry
option. -
--delay
option ofmocha
is now supported and covered with test.
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 programatically 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
Main changed 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 will see that the number of suites is 2 and it was also 2 for mocha-parallel-tests
v1. mocha-parallel-tests
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 will see not 2 but 4 suites in the output.
From default spec
reporter UI perspective you will see additional indentation for your tests because this is how it renders suites.
There's also a bunch of other changes happened in v2 release:
- minumum 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 not 3, 4 and 5. This is not just a one line change: in order to check thatmocha-parallel-tests
runs fine with all of these versions ofmocha
each test is now executed with eachmocha
version. -
mocha-parallel-tests
npm install should work fine on windows. This is checked by an AppVeyor integration. However there's still 7 tests failing on Windows so this could've been a great contribution if you want to help the project.
supported node version: 8
new: all tests are now executed against all supported mocha versions awesome appveyor: install is okay, tests are not