Alternative implementation of Mocha (requires no external dependencies
for security purposes).
Usage
Bmocha's CLI mimics Mocha's CLI for most features:
$ bmocha --help Usage: bmocha [options] [files] bmocha debug [options] [files] bmocha init <path> [options] [files] Commands: debug start bmocha with the node.js debugger enabled init <path> initialize a client-side bmocha setup at <path> Options: --allow-uncaught enable uncaught errors to propagate (default: false) -A, --async-only require all tests to use a callback or promise (default: false) -B, --backend <value> set the NODE_BACKEND environment variable -b, --bail bail after first test failure (default: false) --check-leaks check for global variable leaks (default: false) --chrome <path> chrome binary to use for headless mode -c, --colors force enabling of colors -C, --no-colors force disabling of colors --conditions <string> use custom conditional exports conditions --config <path> path to config file (default: nearest rc file) --csp-source <src> add content-security-policy source (default: 'self') --delay delay initial execution of root suite (default: false)
Example
$ bmocha --reporter spec test.js
Docs
Because bmocha is more or less a full clone of mocha, the MochaJS docs should
be sufficient for any typical use-case. See mochajs.org.
Features
Easily Auditable Code (the "why?")
There have been a number of NPM package attacks in the past. The most recent
being an attack on the popular event-stream library. There are many projects
with financial components to them, cryptocurrency projects in particular.
Mocha pulls in a number of dependencies (23 with dedupes, and an even greater
amount of dev dependencies):
As maintainers of several cryptocurrency projects, we find this attack surface
to be far too large for comfort. Although we of course trust the mocha
developers, only one of its dependencies need be compromised in order to
potentially steal bitcoin or API keys.
As a result, bmocha pulls in zero dependencies: what you see is what you get.
The code is a couple thousand lines, residing in lib/ and bin/.
Headless Chrome & Browser Support
If browserify is installed as a global or peer dependency, running tests in
headless chrome is as easy as:
$ bmocha -H test.js
Chromium or chrome must be installed in one of the usual locations depending on
your OS. If both are installed, bmocha prefers chromium over chrome.
The tests will run in a browserify environment with some extra features:
console.{log,error,info,warn,dir} and process.{stdout,stderr} will work
as expected.
process.{exit,abort} will work as expected.
The fs module will work in "read-only" mode. All of the read calls,
including access, exists, stat, readdir, and readFile will all work
properly (sync and async). As a security measure, they will only be able to
access your current working directory and nothing else.
If your chrome binary is somewhere non-standard, you are able to pass the
--chrome flag.
$ mocha test.js Suite ✓ should fail (unhandled rejection) ✓ should fail (resolve & resolve) ✓ should fail (resolve & reject) ✓ should fail (resolve & throw) 4 passing (7ms)
Bmocha will report and catch unhandled rejections, multiple resolutions, along
with other strange situations:
$ bmocha test.js Suite 1) should fail (unhandled rejection) 2) should fail (resolve & resolve) 3) should fail (resolve & reject) 4) should fail (resolve & throw) 0 passing (4ms) 4 failing 1) Suite should fail (unhandled rejection): Unhandled Error: foobar reject(new Error('foobar')); ^ at Promise (/home/bmocha/test.js:4:14) at new Promise (<anonymous>) at Context.it (/home/bmocha/test.js:3:5) 2) Suite should fail (resolve & resolve): Uncaught Error: Multiple resolves detected for number. 2 3) Suite should fail (resolve & reject): Uncaught Error: Multiple rejects detected for error. Error: foobar at Promise (/home/bmocha/test.js:18:14) at new Promise (<anonymous>)
Mocha tends to die in very strange ways on uncaught errors. Take for instance:
$ mocha test.js Suite ✓ should fail (setImmediate) 1) should fail (setImmediate) 1 passing (5ms) 1 failing 1) Suite should fail (setImmediate): Uncaught Error: foobar 1 at Immediate.setImmediate (test.js:4:13) ✓ should not fail (setTimeout)
The garbled output shown above is very confusing and not very user friendly.
In bmocha, the results are as such:
$ bmocha test.js Suite 1) should fail (setImmediate) ✓ should not fail (setTimeout) 1 passing (5ms) 1 failing 1) Suite should fail (setImmediate): Uncaught Error: foobar 1 throw new Error('foobar 1'); ^ at Immediate.setImmediate (/home/bmocha/test.js:4:13) at processImmediate (timers.js:632:19) An error occurred outside of the test suite: Uncaught Error: foobar 2 throw new Error('foobar 2'); ^ at Timeout.setTimeout [as _onTimeout] (/home/bmocha/test.js:10:13) at listOnTimeout (timers.js:324:15) at processTimers (timers.js:268:5)
A note on uncaught errors, unhandled rejections, and multiple resolutions:
Mocha does not even handle the latter, but it tends to die strangely on the
former two. In fact, it dies almost instantly. Bmocha will attempt to "attach"
uncaught errors to the currently running test and reject it. If there is no
currently running test, bmocha will buffer the error until the end, at which
point it will list all of the uncaught errors. If bmocha is no longer running
at all, the error will be output and the process will be exited.
This can lead to differing output on each run if your process has uncaught
errors. Running it again, bmocha was able to attach the error to the currently
running test:
$ bmocha test.js Suite 1) should fail (setImmediate) 2) should not fail (setTimeout) 0 passing (4ms) 2 failing 1) Suite should fail (setImmediate): Uncaught Error: foobar 1 throw new Error('foobar 1'); ^ at Immediate.setImmediate (/home/bmocha/test.js:4:13) at processImmediate (timers.js:632:19) 2) Suite should not fail (setTimeout): Uncaught Error: foobar 2 throw new Error('foobar 2'); ^ at Timeout.setTimeout [as _onTimeout] (/home/bmocha/test.js:10:13) at listOnTimeout (timers.js:324:15) at processTimers (timers.js:268:5)
Mocha also only warns when explicitly passed a non-existent test. This is a
shortcoming in CI situations which may only look at the exit code.
$ mocha test.js non-existent.js || echo 1Warning: Could not find any test files matching pattern: non-existent.js Suite ✓ should pass 1 passing (3ms)
Bmocha will fail outright:
$ bmocha test.js non-existent.js || echo 1File not found: non-existent.js.1
Running in the browser is similar. To output to the DOM, a DOMStream object
is available:
const {Mocha, DOMStream} = require('bmocha');const stream = new DOMStream(document.body);const mocha = new Mocha(stream);await mocha.run(...);
Likewise, a ConsoleStream object is available to output to the console:
const {Mocha, ConsoleStream} = require('bmocha');const stream = new ConsoleStream(console);const mocha = new Mocha(stream);await mocha.run(...);
Contribution and License Agreement
If you contribute code to this project, you are implicitly allowing your code
to be distributed under the MIT license. You are also implicitly verifying that
all code is your original work. </legalese>
License
Copyright (c) 2018-2019, Christopher Jeffrey (MIT License).
See LICENSE for more info.
pinheadmz
pinheadmz@gmail.com
--diff show diff on failure (default: true)
--dry-run report tests without executing them
-e, --env <name=val> set environment variable (can be specified multiple
times)
--exclude <file> a file to ignore
--exit force shutdown of the event loop after test run
(default: false)
--extension <ext> file extension(s) to load and/or watch
(default: js, cjs, mjs)
--fail-zero fail test run if no tests encountered
-f, --fgrep <string> only run tests containing <string>
--file <file> include a file to be ran during the suite
--firefox use firefox instead of chrome for headless mode
--forbid-only fail if exclusive test(s) encountered
(default: false)
--forbid-pending fail if pending test(s) encountered
(default: false)
--full-trace display full stack traces (default: false)
-g, --grep <pattern> only run tests matching <pattern>