Merge branch 'master' of https://github.com/mochajs/mocha

mochajs · Oct 3, 2018 · d2a7f04 · d2a7f04
2 parents 5ac90a1 + 04469bf
commit d2a7f04
Show file tree

Hide file tree

Showing 22 changed files with 4,825 additions and 4,036 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -40,9 +40,6 @@ jobs:
     - <<: *node
       node_js: '6'
 
-    - <<: *node
-      node_js: '4'
-
     - script: npm start test.bundle test.browser
       install: npm ci # we need the native modules here
       addons:
@@ -78,9 +75,6 @@ jobs:
     - <<: *smoke
       node_js: '6'
 
-    - <<: *smoke
-      node_js: '4'
-
     - stage: precache
       script: true
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,34 @@
+# 5.2.0 / 2018-05-18
+
+## :tada: Enhancements
+
+- [#3375]: Add support for comments in `mocha.opts` ([@plroebuck])
+
+## :bug: Fixes
+
+- [#3346]: Exit correctly from `before` hooks when using `--bail` ([@outsideris])
+
+## :book: Documentation
+
+- [#3328]: Mocha-flavored [API docs](https://mochajs.org/api/)! ([@Munter])
+
+## :nut_and_bolt: Other
+
+- [#3330]: Use `Buffer.from()` ([@harrysarson])
+- [#3295]: Remove redundant folder ([@DavNej](https://github.com/DajNev))
+- [#3356](https://github.com/mochajs/mocha/pull/3356): Refactoring ([@plroebuck])
+
+[#3375]: https://github.com/mochajs/mocha/pull/3375
+[#3346]: https://github.com/mochajs/mocha/pull/3346
+[#3328]: https://github.com/mochajs/mocha/pull/3328
+[#3330]: https://github.com/mochajs/mocha/pull/3330
+[#3295]: https://github.com/mochajs/mocha/pull/3295
+
+[@plroebuck]: https://github.com/plroebuck
+[@harrysarson]: https://github.com/harrysarson
+[@outsideris]: https://github.com/outsideris
+[@Munter]: https://github.com/Munter
+
 # 5.1.1 / 2018-04-18
 
 ## :bug: Fixes

diff --git a/Gemfile.lock b/Gemfile.lock
@@ -4,38 +4,50 @@ GEM
     addressable (2.5.2)
       public_suffix (>= 2.0.2, < 4.0)
     colorator (1.1.0)
-    ffi (1.9.18)
+    concurrent-ruby (1.0.5)
+    em-websocket (0.5.1)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    eventmachine (1.2.7)
+    ffi (1.9.25)
     forwardable-extended (2.6.0)
-    jekyll (3.6.2)
+    http_parser.rb (0.6.0)
+    i18n (0.9.5)
+      concurrent-ruby (~> 1.0)
+    jekyll (3.8.3)
       addressable (~> 2.4)
       colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 0.7)
       jekyll-sass-converter (~> 1.0)
-      jekyll-watch (~> 1.1)
+      jekyll-watch (~> 2.0)
       kramdown (~> 1.14)
       liquid (~> 4.0)
       mercenary (~> 0.3.3)
       pathutil (~> 0.9)
-      rouge (>= 1.7, < 3)
+      rouge (>= 1.7, < 4)
       safe_yaml (~> 1.0)
-    jekyll-sass-converter (1.5.0)
+    jekyll-sass-converter (1.5.2)
       sass (~> 3.4)
-    jekyll-watch (1.5.1)
+    jekyll-watch (2.0.0)
       listen (~> 3.0)
-    kramdown (1.14.0)
+    kramdown (1.17.0)
     liquid (4.0.0)
-    listen (3.0.8)
+    listen (3.1.5)
       rb-fsevent (~> 0.9, >= 0.9.4)
       rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
     mercenary (0.3.6)
-    pathutil (0.16.0)
+    pathutil (0.16.1)
       forwardable-extended (~> 2.6)
-    public_suffix (3.0.0)
-    rb-fsevent (0.10.2)
+    public_suffix (3.0.3)
+    rb-fsevent (0.10.3)
     rb-inotify (0.9.10)
       ffi (>= 0.5.0, < 2)
-    rouge (2.2.1)
+    rouge (3.2.1)
+    ruby_dep (1.5.0)
     safe_yaml (1.0.4)
-    sass (3.5.3)
+    sass (3.5.7)
       sass-listen (~> 4.0.0)
     sass-listen (4.0.0)
       rb-fsevent (~> 0.9, >= 0.9.4)
@@ -48,4 +60,4 @@ DEPENDENCIES
   jekyll (~> 3.6)
 
 BUNDLED WITH
-   1.16.0
+   1.16.1
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
@@ -18,7 +18,7 @@ Anyone involved with Mocha will fall into one of these buckets: **user**, **cont
 
 A "user" for the purpose of this document is any *individual developer* who consumes Mocha to write and/or execute tests.  A user interacts with contributors.  A user interacts with the software, web site, documentation, etc., which these contributors provide.
 
-As a user, you're expected to follow the [code of conduct](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md) when interacting in Mocha's "official" social spaces. This includes:
+As a user, you're expected to follow the [code of conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) when interacting in Mocha's "official" social spaces. This includes:
 
 - Any chatroom under the `mochajs` organization on Gitter
 - Any project under the `mochajs` organization on GitHub
@@ -45,7 +45,7 @@ A "contributor" is any individual who has *given back* in some way to the projec
 1. Recruiting more contributors! Don't spam.
 1. Researching the user base, getting feedback, etc. Don't spam.
 
-A contributor is *usually* a user as well, but this isn't a hard-and-fast rule. A contributor is also expected to adhere to the [code of conduct](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md) as a user would.
+A contributor is *usually* a user as well, but this isn't a hard-and-fast rule. A contributor is also expected to adhere to the [code of conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) as a user would.
 
 As you can see, it's wide open!  Think of it another way: if you are *adding value to Mocha*, then you are a contributor.
 

diff --git a/appveyor.yml b/appveyor.yml
@@ -6,7 +6,6 @@ environment:
     - nodejs_version: '9'
     - nodejs_version: '8'
     - nodejs_version: '6'
-    - nodejs_version: '4'
 install:
   - ps: Install-Product node $env:nodejs_version x64
   - set CI=true

diff --git a/bin/_mocha b/bin/_mocha
@@ -99,25 +99,10 @@ const showCursor = () => {
 };
 
 /**
- * Stop play()ing.
+ * Stop.
  */
 const stop = () => {
   process.stdout.write('\u001b[2K');
-  clearInterval(play.timer);
-};
-
-/**
- * Play the given array of strings.
- */
-const play = (arr, interval) => {
-  const len = arr.length;
-  interval = interval || 100;
-  let i = 0;
-
-  play.timer = setInterval(() => {
-    const str = arr[i++ % len];
-    process.stdout.write(`\u001b[0G${str}`);
-  }, interval);
 };
 
 /**

diff --git a/bin/mocha b/bin/mocha
@@ -38,6 +38,7 @@ process.argv.slice(2).forEach(arg => {
       break;
     case '--gc-global':
     case '--es_staging':
+    case '--experimental-modules':
     case '--no-deprecation':
     case '--no-warnings':
     case '--prof':

diff --git a/docs/README.md b/docs/README.md
@@ -9,14 +9,14 @@
 - Ruby
 - RubyGems
 - Bundler (`gem install bundler`)
-- Node.js v4.0.0 or greater
+- Node.js v6.x or greater
 
 ## Development
 
 1. Run `npm install` from working copy root to get Node.js deps.
 1. Run `bundle install` to install Jekyll and its dependencies.  This may or may not require elevated privileges, depending on your system.
-1. To serve the site and rebuild as changes are made, execute `npm run docs.watch`.
-1. To rebuild the site *once*, execute `npm start docs.build`.
+1. To serve the site and rebuild as changes are made, execute `npm start docs.watch`.
+1. To rebuild the site *once*, execute `npm start docs`.
 
 ### Notes
 

diff --git a/docs/index.md b/docs/index.md
@@ -52,6 +52,7 @@ Mocha is a feature-rich JavaScript test framework running on [Node.js](https://n
 
 - [Installation](#installation)
 - [Getting Started](#getting-started)
+- [Run Cycle Overview](#run-cycle-overview)
 - [Detects Multiple Calls to `done()`](#detects-multiple-calls-to-done)
 - [Assertions](#assertions)
 - [Asynchronous Code](#asynchronous-code)
@@ -92,9 +93,7 @@ or as a development dependency for your project:
 $ npm install --save-dev mocha
 ```
 
-> To install Mocha v3.0.0 or newer with `npm`, you will need `npm` v2.14.2 or newer.  Additionally, to run Mocha, you will need Node.js v4 or newer.
-
-Mocha can also be installed via [Bower](https://bower.io) (`bower install mocha`), and is available at [cdnjs](https://cdnjs.com/libraries/mocha).
+> Mocha currently requires Node.js v6.x or newer.
 
 ## Getting Started
 
@@ -144,6 +143,47 @@ Then run tests with:
 $ npm test
 ```
 
+## Run Cycle Overview
+
+A brief outline on the order Mocha's components are executed.
+Worth noting that all hooks, `describe` and `it` callbacks are run in the order they are defined (i.e. found in the file).
+
+``` js
+run 'mocha spec.js'
+|
+spawn child process
+|
+|--------------> inside child process
+  process and apply options
+  |
+  run spec file/s
+  |
+  |--------------> per spec file
+    suite callbacks (e.g., 'describe')
+    |
+    'before' root-level pre-hook
+    |
+    'before' pre-hook
+    |
+    |--------------> per test
+      'beforeEach' root-level pre-hook
+      |
+      'beforeEach' pre-hook
+      |
+      test callbacks (e.g., 'it')
+      |
+      'afterEach' post-hook
+      |
+      'afterEach' root-level post-hook
+    |<-------------- per test end
+    |
+    'after' post-hook
+    |
+    'after' root-level post-hooks
+  |<-------------- per spec file end
+|<-------------- inside child process end
+```
+
 ## Detects Multiple Calls to `done()`
 
 If 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.
@@ -742,7 +782,6 @@ Mocha supports the `err.expected` and `err.actual` properties of any thrown `Ass
 ```text
   Usage: mocha [debug] [options] [files]
 
-
   Options:
 
     -V, --version                           output the version number
@@ -751,7 +790,7 @@ Mocha supports the `err.expected` and `err.actual` properties of any thrown `Ass
     -C, --no-colors                         force disabling of colors
     -G, --growl                             enable growl notification support
     -O, --reporter-options <k=v,k2=v2,...>  reporter-specific options
-    -R, --reporter <name>                   specify the reporter to use
+    -R, --reporter <name>                   specify the reporter to use (default: spec)
     -S, --sort                              sort test files
     -b, --bail                              bail after first test failure
     -d, --debug                             enable node's debugger, synonym for node --debug
@@ -762,27 +801,27 @@ Mocha supports the `err.expected` and `err.actual` properties of any thrown `Ass
     -r, --require <name>                    require the given module
     -s, --slow <ms>                         "slow" test threshold in milliseconds [75]
     -t, --timeout <ms>                      set test-case timeout in milliseconds [2000]
-    -u, --ui <name>                         specify user-interface (bdd|tdd|qunit|exports)
+    -u, --ui <name>                         specify user-interface (bdd|tdd|qunit|exports) (default: bdd)
     -w, --watch                             watch files for changes
     --check-leaks                           check for global variable leaks
     --full-trace                            display the full stack trace
-    --compilers <ext>:<module>,...          use the given module(s) to compile files
+    --compilers <ext>:<module>,...          use the given module(s) to compile files (default: )
     --debug-brk                             enable node's debugger breaking on the first line
-    --globals <names>                       allow the given comma-delimited global [names]
+    --globals <names>                       allow the given comma-delimited global [names] (default: )
     --es_staging                            enable all staged features
-    --file <file>                           include a file to be ran during the suite [file]
     --harmony<_classes,_generators,...>     all node --harmony* flags are available
     --preserve-symlinks                     Instructs the module loader to preserve symbolic links when resolving and caching modules
     --icu-data-dir                          include ICU data
     --inline-diffs                          display actual/expected differences inline within each string
+    --no-diff                               do not show a diff on failure
     --inspect                               activate devtools in chrome
     --inspect-brk                           activate devtools in chrome and break on the first line
     --interfaces                            display available interfaces
     --no-deprecation                        silence deprecation warnings
     --exit                                  force shutdown of the event loop after test run: mocha will call process.exit
     --no-timeouts                           disables timeouts, given implicitly with --debug
     --no-warnings                           silence all node process warnings
-    --opts <path>                           specify opts path
+    --opts <path>                           specify opts path (default: test/mocha.opts)
     --perf-basic-prof                       enable perf linux profiler (basic support)
     --napi-modules                          enable experimental NAPI modules
     --prof                                  log statistical profiling information
@@ -795,14 +834,15 @@ Mocha supports the `err.expected` and `err.actual` properties of any thrown `Ass
     --trace-deprecation                     show stack traces on deprecations
     --trace-warnings                        show stack traces on node process warnings
     --use_strict                            enforce strict mode
-    --watch-extensions <ext>,...            additional extensions to monitor with --watch
+    --watch-extensions <ext>,...            specify extensions to monitor with --watch (default: js)
     --delay                                 wait for async suite definition
     --allow-uncaught                        enable uncaught errors to propagate
     --forbid-only                           causes test marked with only to fail the suite
     --forbid-pending                        causes pending tests and test marked with skip to fail the suite
+    --file <file>                           include a file to be ran during the suite (default: )
+    --exclude <file>                        a file or glob pattern to ignore (default: )
     -h, --help                              output usage information
 
-
   Commands:
 
     init <path>  initialize a client-side mocha setup at <path>
@@ -1193,22 +1233,20 @@ A typical setup might look something like the following, where we call `mocha.se
 <head>
   <meta charset="utf-8">
   <title>Mocha Tests</title>
-  <link href="https://cdn.rawgit.com/mochajs/mocha/2.2.5/mocha.css" rel="stylesheet" />
+  <link href="https://unpkg.com/mocha@5.2.0/mocha.css" rel="stylesheet" />
 </head>
 <body>
   <div id="mocha"></div>
 
-  <script src="https://cdn.rawgit.com/jquery/jquery/2.1.4/dist/jquery.min.js"></script>
-  <script src="https://cdn.rawgit.com/Automattic/expect.js/0.3.1/index.js"></script>
-  <script src="https://cdn.rawgit.com/mochajs/mocha/2.2.5/mocha.js"></script>
+  <script src="https://unpkg.com/chai/chai.js"></script>
+  <script src="https://unpkg.com/mocha@5.2.0/mocha.js"></script>
 
   <script>mocha.setup('bdd')</script>
   <script src="test.array.js"></script>
   <script src="test.object.js"></script>
   <script src="test.xhr.js"></script>
   <script>
     mocha.checkLeaks();
-    mocha.globals(['jQuery']);
     mocha.run();
   </script>
 </body>
@@ -1290,7 +1328,21 @@ $ mocha --reporter list --growl
 
 ## The `test/` Directory
 
-By default, `mocha` looks for the glob `./test/*.js`, so you may want to put your tests in `test/` folder. If you want to include sub directories, use `--recursive`, since `./test/*.js` only matches files in the first level of `test` and `./test/**/*.js` only matches files in the second level of `test`.
+By default, `mocha` looks for the glob `./test/*.js`, so you may want to put your tests in `test/` folder. If you want to include sub directories, pass the `--recursive` option.
+
+To configure where `mocha` looks for tests, you may pass your own glob:
+
+```sh
+$ mocha --recursive "./spec/*.js"
+```
+
+Some shells support recursive matching by using the `**` wildcard in a glob. Bash >= 4.3 supports this with the [`globstar` option](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html) which [must be enabled](https://github.com/mochajs/mocha/pull/3348#issuecomment-383937247) to get the same results as passing the `--recursive` option ([ZSH](http://zsh.sourceforge.net/Doc/Release/Expansion.html#Recursive-Globbing) and [Fish](https://fishshell.com/docs/current/#expand-wildcard) support this by default). With recursive matching enabled, the following is the same as passing `--recursive`:
+
+```sh
+$ mocha "./spec/**/*.js"
+```
+
+*Note*: Double quotes around the glob are recommended for portability.
 
 ## Editor Plugins
 

diff --git a/lib/reporters/base.js b/lib/reporters/base.js
@@ -42,7 +42,8 @@ var isatty = tty.isatty(1) && tty.isatty(2);
  */
 
 exports.useColors =
-  !process.browser && (supportsColor || process.env.MOCHA_COLORS !== undefined);
+  !process.browser &&
+  (supportsColor.stdout || process.env.MOCHA_COLORS !== undefined);
 
 /**
  * Inline diffs instead of +/-