☕️ Classic, reliable, trusted test framework for Node.js and the browser
temporarily disable broken OC badges
Christopher Hiller109820b96220
diff --git a/README.md b/README.mdindex 68634e1f..15834af6 100644--- a/README.md+++ b/README.md@@ -4,7 +4,7 @@<p align="center">☕️ Simple, flexible, fun JavaScript test framework for Node.js & The Browser ☕️</p>-<p align="center"><a href="http://travis-ci.org/mochajs/mocha"><img src="https://api.travis-ci.org/mochajs/mocha.svg?branch=master" alt="Build Status"></a> <a href="https://coveralls.io/github/mochajs/mocha"><img src="https://coveralls.io/repos/github/mochajs/mocha/badge.svg" alt="Coverage Status"></a> <a href="https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha?ref=badge_shield"><img src="https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha.svg?type=shield" alt="FOSSA Status"></a> <a href="https://gitter.im/mochajs/mocha?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Gitter"></a> <a href="https://github.com/mochajs/mocha#backers"><img src="https://opencollective.com/mochajs/backers/badge.svg" alt="OpenCollective"></a> <a href="https://github.com/mochajs/mocha#sponsors"><img src="https://opencollective.com/mochajs/sponsors/badge.svg" alt="OpenCollective"></a>+<p align="center"><a href="http://travis-ci.org/mochajs/mocha"><img src="https://api.travis-ci.org/mochajs/mocha.svg?branch=master" alt="Build Status"></a> <a href="https://coveralls.io/github/mochajs/mocha"><img src="https://coveralls.io/repos/github/mochajs/mocha/badge.svg" alt="Coverage Status"></a> <a href="https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha?ref=badge_shield"><img src="https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha.svg?type=shield" alt="FOSSA Status"></a> <a href="https://gitter.im/mochajs/mocha?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Gitter"></a> <!-- <a href="https://github.com/mochajs/mocha#backers"><img src="https://opencollective.com/mochajs/backers/badge.svg" alt="OpenCollective"></a> <a href="https://github.com/mochajs/mocha#sponsors"><img src="https://opencollective.com/mochajs/sponsors/badge.svg" alt="OpenCollective"></a> --></p><p align="center"><br><img alt="Mocha Browser Support h/t SauceLabs" src="https://saucelabs.com/browser-matrix/mochajs.svg" width="354"></p>diff --git a/docs/index.md b/docs/index.mdindex b8396ea3..96b2ed9a 100644--- a/docs/index.md+++ b/docs/index.md@@ -8,8 +8,8 @@ Mocha is a feature-rich JavaScript test framework running on [Node.js][] and in<nav class="badges"><a href="https://gitter.im/mochajs/mocha"><img src="/images/join-chat.svg" height="18" alt="Gitter"></a>- <a href="#sponsors"><img src="https://opencollective.com/mochajs/sponsors/badge.svg" height="18" alt="OpenCollective sponsors"></a>- <a href="#backers"><img src="https://opencollective.com/mochajs/backers/badge.svg" height="18" alt="OpenCollective backers"></a>+ <!-- <a href="#sponsors"><img src="https://opencollective.com/mochajs/sponsors/badge.svg" height="18" alt="OpenCollective sponsors"></a>+ <a href="#backers"><img src="https://opencollective.com/mochajs/backers/badge.svg" height="18" alt="OpenCollective backers"></a> --></nav>{% include supporters.md %}@@ -78,9 +78,9 @@ In your editor:```jsvar assert = require('assert');-describe('Array', function () {- describe('#indexOf()', function () {- it('should return -1 when the value is not present', function () {+describe('Array', function() {+ describe('#indexOf()', function() {+ it('should return -1 when the value is not present', function() {assert.equal([1, 2, 3].indexOf(4), -1);});});@@ -160,7 +160,7 @@ spawn child processIf you use callback-based async tests, Mocha will throw an error if `done()` is called multiple times. This is handy for catching accidental double callbacks.```javascript-it('double done', function (done) {+it('double done', function(done) {// Calling `done()` twice is an errorsetImmediate(done);setImmediate(done);@@ -203,11 +203,11 @@ Mocha allows you to use any assertion library you wish. In the above example, weBy adding an argument (usually named `done`) to `it()` to a test callback, Mocha will know that it should wait for this function to be called to complete the test. This callback accepts both an `Error` instance (or subclass thereof) _or_ a falsy value; anything else is invalid usage and throws an error (usually causing a failed test).```js-describe('User', function () {- describe('#save()', function () {- it('should save without error', function (done) {+describe('User', function() {+ describe('#save()', function() {+ it('should save without error', function(done) {var user = new User('Luna');- user.save(function (err) {+ user.save(function(err) {if (err) done(err);else done();});@@ -219,9 +219,9 @@ describe('User', function () {Alternatively, use the `done()` callback directly (which will handle an error argument, if it exists):```js-describe('User', function () {- describe('#save()', function () {- it('should save without error', function (done) {+describe('User', function() {+ describe('#save()', function() {+ it('should save without error', function(done) {var user = new User('Luna');user.save(done);});@@ -234,14 +234,14 @@ describe('User', function () {Alternately, instead of using the `done()` callback, you may return a [Promise][mdn-promise]. This is useful if the APIs you are testing return promises instead of taking callbacks:```js-beforeEach(function () {- return db.clear().then(function () {+beforeEach(function() {+ return db.clear().then(function() {return db.save([tobi, loki, jane]);});});-describe('#find()', function () {- it('respond with matching records', function () {+describe('#find()', function() {+ it('respond with matching records', function() {return db.find({type: 'User'}).should.eventually.have.length(3);});});@@ -255,8 +255,8 @@ In Mocha v3.0.0 and newer, returning a `Promise` _and_ calling `done()` will resconst assert = require('assert');// antipattern-it('should complete this test', function (done) {- return new Promise(function (resolve) {+it('should complete this test', function(done) {+ return new Promise(function(resolve) {assert.ok(true);resolve();}).then(done);@@ -270,13 +270,13 @@ The above test will fail with `Error: Resolution method is overspecified. SpecifIf your JS environment supports [async / await][mdn-async], you can also write asynchronous tests like this:```js-beforeEach(async function () {+beforeEach(async function() {await db.clear();await db.save([tobi, loki, jane]);});-describe('#find()', function () {- it('responds with matching records', async function () {+describe('#find()', function() {+ it('responds with matching records', async function() {const users = await db.find({type: 'User'});users.should.have.length(3);});@@ -288,9 +288,9 @@ describe('#find()', function () {When testing synchronous code, omit the callback and Mocha will automatically continue on to the next test.```js-describe('Array', function () {- describe('#indexOf()', function () {- it('should return -1 when the value is not present', function () {+describe('Array', function() {+ describe('#indexOf()', function() {+ it('should return -1 when the value is not present', function() {[1, 2, 3].indexOf(5).should.equal(-1);[1, 2, 3].indexOf(0).should.equal(-1);});@@ -319,20 +319,20 @@ _If you do not need to use_ Mocha's context, lambdas should work. Be aware thatWith its default "BDD"-style interface, Mocha provides the hooks `before()`, `after()`, `beforeEach()`, and `afterEach()`. These should be used to set up preconditions and clean up after your tests.```js-describe('hooks', function () {- before(function () {+describe('hooks', function() {+ before(function() {// runs once before the first test in this block});- after(function () {+ after(function() {// runs once after the last test in this block});- beforeEach(function () {+ beforeEach(function() {// runs before each test in this block});- afterEach(function () {+ afterEach(function() {// runs after each test in this block});@@ -347,7 +347,7 @@ describe('hooks', function () {Any hook can be invoked with an optional description, making it easier to pinpoint errors in your tests. If a hook is given a named function, that name will be used if no description is supplied.```js-beforeEach(function () {+beforeEach(function() {// beforeEach hook});@@ -355,7 +355,7 @@ beforeEach(function namedFun() {// beforeEach:namedFun});-beforeEach('some description', function () {+beforeEach('some description', function() {// beforeEach:some description});```@@ -365,22 +365,22 @@ beforeEach('some description', function () {All hooks (`before()`, `after()`, `beforeEach()`, `afterEach()`) may be sync or async as well, behaving much like a regular test-case. For example, you may wish to populate database with dummy content before each test:```js-describe('Connection', function () {+describe('Connection', function() {var db = new Connection(),tobi = new User('tobi'),loki = new User('loki'),jane = new User('jane');- beforeEach(function (done) {- db.clear(function (err) {+ beforeEach(function(done) {+ db.clear(function(err) {if (err) return done(err);db.save([tobi, loki, jane], done);});});- describe('#find()', function () {- it('respond with matching records', function (done) {- db.find({type: 'User'}, function (err, res) {+ describe('#find()', function() {+ it('respond with matching records', function(done) {+ db.find({type: 'User'}, function(err, res) {if (err) return done(err);res.should.have.length(3);done();@@ -403,10 +403,10 @@ As of v8.0.0, [Root Hook Plugins](#root-hook-plugins) are the preferred mechanisIf you need to perform asynchronous operations before any of your suites are run, you may delay the root suite. Run `mocha` with the `--delay` flag. This will attach a special callback function, `run()`, to the global context:```js-setTimeout(function () {+setTimeout(function() {// do some setup- describe('my suite', function () {+ describe('my suite', function() {// ...});@@ -419,8 +419,8 @@ setTimeout(function () {"Pending"--as in "someone should write these test cases eventually"--test-cases are those _without_ a callback:```js-describe('Array', function () {- describe('#indexOf()', function () {+describe('Array', function() {+ describe('#indexOf()', function() {// pending test belowit('should return -1 when the value is not present');});@@ -439,8 +439,8 @@ The exclusivity feature allows you to run _only_ the specified suite or test-casby appending `.only()` to the function. Here's an example of executing only a particular suite:```js-describe('Array', function () {- describe.only('#indexOf()', function () {+describe('Array', function() {+ describe.only('#indexOf()', function() {// ...});});@@ -451,13 +451,13 @@ _Note_: All nested suites will still be executed.Here's an example of executing an individual test case:```js-describe('Array', function () {- describe('#indexOf()', function () {- it.only('should return -1 unless present', function () {+describe('Array', function() {+ describe('#indexOf()', function() {+ it.only('should return -1 unless present', function() {// ...});- it('should return the index when present', function () {+ it('should return the index when present', function() {// ...});});@@ -467,17 +467,17 @@ describe('Array', function () {Previous to v3.0.0, `.only()` used string matching to decide which tests to execute; this is no longer the case. In v3.0.0 or newer, `.only()` can be used multiple times to define a subset of tests to run:```js-describe('Array', function () {- describe('#indexOf()', function () {- it.only('should return -1 unless present', function () {+describe('Array', function() {+ describe('#indexOf()', function() {+ it.only('should return -1 unless present', function() {// this test will be run});- it.only('should return the index when present', function () {+ it.only('should return the index when present', function() {// this test will also be run});- it('should return -1 if called with a non-Array context', function () {+ it('should return -1 if called with a non-Array context', function() {// this test will not be run});});@@ -487,25 +487,25 @@ describe('Array', function () {You may also choose multiple suites:```js-describe('Array', function () {- describe.only('#indexOf()', function () {- it('should return -1 unless present', function () {+describe('Array', function() {+ describe.only('#indexOf()', function() {+ it('should return -1 unless present', function() {// this test will be run});- it('should return the index when present', function () {+ it('should return the index when present', function() {// this test will also be run});});- describe.only('#concat()', function () {- it('should return a new Array', function () {+ describe.only('#concat()', function() {+ it('should return a new Array', function() {// this test will also be run});});- describe('#slice()', function () {- it('should return a new Array', function () {+ describe('#slice()', function() {+ it('should return a new Array', function() {// this test will not be run});});@@ -515,13 +515,13 @@ describe('Array', function () {But _tests will have precedence_:```js-describe('Array', function () {- describe.only('#indexOf()', function () {- it.only('should return -1 unless present', function () {+describe('Array', function() {+ describe.only('#indexOf()', function() {+ it.only('should return -1 unless present', function() {// this test will be run});- it('should return the index when present', function () {+ it('should return the index when present', function() {// this test will not be run});});@@ -537,13 +537,13 @@ _Note_: Hooks, if present, will still be executed.This feature is the inverse of `.only()`. By appending `.skip()`, you may tell Mocha to ignore test case(s). Anything skipped will be marked as [pending](#pending-tests), and reported as such. Here's an example of skipping an individual test:```js-describe('Array', function () {- describe('#indexOf()', function () {- it.skip('should return -1 unless present', function () {+describe('Array', function() {+ describe('#indexOf()', function() {+ it.skip('should return -1 unless present', function() {// this test will not be run});- it('should return the index when present', function () {+ it('should return the index when present', function() {// this test will be run});});@@ -553,9 +553,9 @@ describe('Array', function () {You can also put `.skip()` on an entire suite. This is equivalent to appending `.skip()` onto all tests in the suite. Hooks in the suite are also skipped.```js-describe('Array', function () {- describe.skip('#indexOf()', function () {- it('should return -1 unless present', function () {+describe('Array', function() {+ describe.skip('#indexOf()', function() {+ it('should return -1 unless present', function() {// this test will not be run});});@@ -613,21 +613,21 @@ before(function() {This will skip all `it`, `beforeEach/afterEach`, and `describe` blocks within the suite. `before/after` hooks are skipped unless they are defined at the same level as the hook containing `this.skip()`.```js-describe('outer', function () {- before(function () {+describe('outer', function() {+ before(function() {this.skip();});- after(function () {+ after(function() {// will be executed});- describe('inner', function () {- before(function () {+ describe('inner', function() {+ before(function() {// will be skipped});- after(function () {+ after(function() {// will be skipped});});@@ -647,15 +647,15 @@ This feature does re-run a failed test and its corresponding `beforeEach/afterEa**NOTE**: Example below was written using Selenium webdriver (which [overwrites global Mocha hooks][selenium-webdriver-testing] for `Promise` chain).```js-describe('retries', function () {+describe('retries', function() {// Retry all tests in this suite up to 4 timesthis.retries(4);- beforeEach(function () {+ beforeEach(function() {browser.get('http://www.yahoo.com');});- it('should succeed on the 3rd try', function () {+ it('should succeed on the 3rd try', function() {// Specify this test to only retry up to 2 timesthis.retries(2);expect($('.foo').isDisplayed()).to.eventually.be.true;@@ -673,20 +673,20 @@ Take the following example:var assert = require('chai').assert;function add() {- return Array.prototype.slice.call(arguments).reduce(function (prev, curr) {+ return Array.prototype.slice.call(arguments).reduce(function(prev, curr) {return prev + curr;}, 0);}-describe('add()', function () {+describe('add()', function() {var tests = [{args: [1, 2], expected: 3},{args: [1, 2, 3], expected: 6},- {args: [1, 2, 3, 4], expected: 10},+ {args: [1, 2, 3, 4], expected: 10}];- tests.forEach(function (test) {- it('correctly adds ' + test.args.length + ' args', function () {+ tests.forEach(function(test) {+ it('correctly adds ' + test.args.length + ' args', function() {var res = add.apply(null, test.args);assert.equal(res, test.expected);});@@ -722,10 +722,10 @@ There are three levels of test duration (depicted in the following image):To tweak what's considered "slow", you can use the `slow()` method:```js-describe('something slow', function () {+describe('something slow', function() {this.slow(300000); // five minutes- it('should take long enough for me to go make a sandwich', function () {+ it('should take long enough for me to go make a sandwich', function() {// ...});});@@ -738,14 +738,14 @@ describe('something slow', function () {Suite-level timeouts may be applied to entire test "suites", or disabled via `this.timeout(0)`. This will be inherited by all nested suites and test-cases that do not override the value.```js-describe('a suite of tests', function () {+describe('a suite of tests', function() {this.timeout(500);- it('should take less than 500ms', function (done) {+ it('should take less than 500ms', function(done) {setTimeout(done, 300);});- it('should take less than 500ms as well', function (done) {+ it('should take less than 500ms as well', function(done) {setTimeout(done, 250);});});@@ -756,7 +756,7 @@ describe('a suite of tests', function () {Test-specific timeouts may also be applied, or the use of `this.timeout(0)` to disable timeouts all together:```js-it('should take less than 500ms', function (done) {+it('should take less than 500ms', function(done) {this.timeout(500);setTimeout(done, 300);});@@ -767,8 +767,8 @@ it('should take less than 500ms', function (done) {Hook-level timeouts may also be applied:```js-describe('a suite of tests', function () {- beforeEach(function (done) {+describe('a suite of tests', function() {+ beforeEach(function(done) {this.timeout(3000); // A very long environment setup.setTimeout(done, 2500);});@@ -1066,17 +1066,17 @@ Cause Mocha to only run tests matching the given `regexp`, which is internally cSuppose, for example, you have "api" related tests, as well as "app" related tests, as shown in the following snippet; One could use `--grep api` or `--grep app` to run one or the other. The same goes for any other part of a suite or test-case title, `--grep users` would be valid as well, or even `--grep GET`.```js-describe('api', function () {- describe('GET /api/users', function () {- it('respond with an array of users', function () {+describe('api', function() {+ describe('GET /api/users', function() {+ it('respond with an array of users', function() {// ...});});});-describe('app', function () {- describe('GET /users', function () {- it('respond with an array of users', function () {+describe('app', function() {+ describe('GET /users', function() {+ it('respond with an array of users', function() {// ...});});@@ -1229,12 +1229,12 @@ A _root hook_ is a hook in a test file which is _not defined_ within a suite. An// test/setup.js// root hook to run before every test (even in other files)-beforeEach(function () {+beforeEach(function() {doMySetup();});// root hook to run after every test (even in other files)-afterEach(function () {+afterEach(function() {doMyTeardown();});```@@ -1308,7 +1308,7 @@ exports.mochaHooks = {beforeEach(done) {// do something before every testdone();- },+ }};```@@ -1325,7 +1325,7 @@ export const mochaHooks = {beforeEach(done) {// do something before every testdone();- },+ }};```@@ -1361,7 +1361,7 @@ export const mochaHooks = {if (require('os').userInfo().username === 'bob') {return this.skip();}- },+ }};```@@ -1374,14 +1374,14 @@ Multiple root hooks can be defined in a single plugin, for organizational purposexport const mochaHooks = {beforeEach: [- function (done) {+ function(done) {// do something before every test,// then run the next hook in this array},- async function () {+ async function() {// async or Promise-returning functions allowed- },- ],+ }+ ]};```@@ -1397,20 +1397,20 @@ export const mochaHooks = () => {// root hooks objectreturn {beforeEach: [- function () {+ function() {// CI-specific beforeEach},- function () {+ function() {// some other CI-specific beforeEach- },- ],+ }+ ]};}// root hooks objectreturn {beforeEach() {// regular beforeEach- },+ }};};```@@ -1428,7 +1428,7 @@ export const mochaHooks = async () => {return {beforeEach() {// something- },+ }};}};@@ -1453,16 +1453,16 @@ For example, given the following file, `test/test.spec.js`, containing root hook```js// test/test.spec.js-beforeEach(function () {+beforeEach(function() {// global setup for all tests});-after(function () {+after(function() {// one-time final cleanup});-describe('my test suite', function () {- it('should have run my global setup', function () {+describe('my test suite', function() {+ it('should have run my global setup', function() {// make assertion});});@@ -1490,8 +1490,8 @@ Your original `test/test.spec.js` should now contain:```js// test/test.spec.js-describe('my test suite', function () {- it('should have run my global setup', function () {+describe('my test suite', function() {+ it('should have run my global setup', function() {// make assertion});});@@ -1520,24 +1520,24 @@ The **BDD** interface provides `describe()`, `context()`, `it()`, `specify()`, `> All of the previous examples were written using the **BDD** interface.```js-describe('Array', function () {- before(function () {+describe('Array', function() {+ before(function() {// ...});- describe('#indexOf()', function () {- context('when not present', function () {- it('should not throw an error', function () {- (function () {+ describe('#indexOf()', function() {+ context('when not present', function() {+ it('should not throw an error', function() {+ (function() {[1, 2, 3].indexOf(4);}.should.not.throw());});- it('should return -1', function () {+ it('should return -1', function() {[1, 2, 3].indexOf(4).should.equal(-1);});});- context('when present', function () {- it('should return the index where the element first appears in the array', function () {+ context('when present', function() {+ it('should return the index where the element first appears in the array', function() {[1, 2, 3].indexOf(3).should.equal(2);});});@@ -1550,13 +1550,13 @@ describe('Array', function () {The **TDD** interface provides `suite()`, `test()`, `suiteSetup()`, `suiteTeardown()`, `setup()`, and `teardown()`:```js-suite('Array', function () {- setup(function () {+suite('Array', function() {+ setup(function() {// ...});- suite('#indexOf()', function () {- test('should return -1 when not present', function () {+ suite('#indexOf()', function() {+ test('should return -1 when not present', function() {assert.equal(-1, [1, 2, 3].indexOf(4));});});@@ -1569,17 +1569,17 @@ The **Exports** interface is much like Mocha's predecessor [expresso][]. The key```jsmodule.exports = {- before: function () {+ before: function() {// ...},Array: {'#indexOf()': {- 'should return -1 when not present': function () {+ 'should return -1 when not present': function() {[1, 2, 3].indexOf(4).should.equal(-1);- },- },- },+ }+ }+ }};```@@ -1594,12 +1594,12 @@ function ok(expr, msg) {suite('Array');-test('#length', function () {+test('#length', function() {var arr = [1, 2, 3];ok(arr.length == 3);});-test('#indexOf()', function () {+test('#indexOf()', function() {var arr = [1, 2, 3];ok(arr.indexOf(1) == 0);ok(arr.indexOf(2) == 1);@@ -1608,7 +1608,7 @@ test('#indexOf()', function () {suite('String');-test('#length', function () {+test('#length', function() {ok('foo'.length == 3);});```@@ -1625,13 +1625,13 @@ var pre = require('mocha').before;var assertions = require('mocha').it;var assert = require('chai').assert;-testCase('Array', function () {- pre(function () {+testCase('Array', function() {+ pre(function() {// ...});- testCase('#indexOf()', function () {- assertions('should return -1 when not present', function () {+ testCase('#indexOf()', function() {+ assertions('should return -1 when not present', function() {assert.equal([1, 2, 3].indexOf(4), -1);});});@@ -1735,9 +1735,9 @@ The Doc reporter outputs a hierarchical HTML body representation of your tests.For example, suppose you have the following JavaScript:```js-describe('Array', function () {- describe('#indexOf()', function () {- it('should return -1 when the value is not present', function () {+describe('Array', function() {+ describe('#indexOf()', function() {+ it('should return -1 when the value is not present', function() {[1, 2, 3].indexOf(5).should.equal(-1);[1, 2, 3].indexOf(0).should.equal(-1);});@@ -1893,7 +1893,7 @@ mocha.setup('tdd');// This is equivalent to the above.mocha.setup({- ui: 'tdd',+ ui: 'tdd'});// Examples of options:@@ -1908,7 +1908,7 @@ mocha.setup({retries: 3,slow: '100',timeout: '2000',- ui: 'bdd',+ ui: 'bdd'});```