Merge pull request #1105 from cypress-io/issue-1077-mocha-overspecified-error

add error message for mocha overspecified error

Author: chrisbreiding

source/guides/references/error-messages.md

@@ -345,6 +345,10 @@ While this works in practice, it's often indicative of an anti-pattern. You almo
 
 `cy` commands themselves are already promise like, and you can likely avoid the use of the separate Promise.
 
+## {% fa fa-exclamation-triangle red %} Cypress detected that you returned a promise in a test, but also invoked a done callback.
+
+The version of mocha was upgraded with Cypress 4.0. Mocha 3+ no longer allows returning a promise and invoking a done callback. Read more about it in the {% url "4.0 migration guide" migration-guide#Make-changes-related-to-Mocha-upgrade %}.
+
 ## {% fa fa-exclamation-triangle red %} Passing `cy.route({stub: false})` or `cy.server({stub: false})` is now deprecated.
 
 You can safely remove: `{stub: false}`.

source/guides/references/migration-guide.md

@@ -147,6 +147,85 @@ module.exports = (on) => {
 }
 ```
 
+## Make changes related to mocha upgrade
+
+Mocha has been upgraded to Mocha 5.
+
+Starting with [mocha 3.0.0](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md#300--2016-07-31), invoking a `done` callback *and* returning a promise in a test results in an error.
+
+This error originates from mocha and is discussed at length [here](https://github.com/mochajs/mocha/pull/1320) and [here](https://github.com/mochajs/mocha/issues/2407).
+
+The reason is that using two different ways to signal that a test is finished is usually a mistake, and there is always a way to only use one. There is a [proposal to handle this situation without erroring](https://github.com/mochajs/mocha/issues/2509) that may be released in a future version of mocha.
+
+In the meantime, you can fix the error by choosing one way or the other to signal the end of your test's execution.
+
+Given the following test:
+
+```javascript
+it('uses invokes done and returns promise', function (done) {
+  return codeUnderTest.doSomethingThatReturnsPromise().then((result) => {
+    // assertions here
+    done()
+  })
+})
+```
+
+You don't need the `done` callback. Just return the promise instead:
+
+```javascript
+it('uses invokes done and returns promise', function () {
+  return codeUnderTest.doSomethingThatReturnsPromise().then((result) => {
+    // assertions here
+  })
+})
+```
+
+Sometimes it might make more sense to use the `done` callback and not return a promise:
+
+```javascript
+it('uses invokes done and returns promise', function (done) {
+  eventEmitter.on('change', () => {
+    // assertions
+    done()
+  })
+
+  return eventEmitter.doSomethingThatEmitsChange()
+})
+```
+
+In this case, you don't need to return the promise:
+
+```javascript
+it('uses invokes done and returns promise', function (done) {
+  eventEmitter.on('change', () => {
+    // assertions
+    done()
+  })
+
+  eventEmitter.doSomethingThatEmitsChange()
+})
+```
+
+Test functions using `async/await` automatically return a promise, so they need to be refactored to not use a `done` callback.
+
+```javascript
+// Will cause overspecified error
+it('uses async/await', async function (done) {
+  const eventEmitter = await getEventEmitter()
+  eventEmitter.on('change', () => done())
+  eventEmitter.doSomethingThatEmitsChange()
+})
+
+// Update to this
+it('uses async/await', async function () {
+  const eventEmitter = await getEventEmitter()
+  return new Promise((resolve) => {
+    eventEmitter.on('change', () => resolve())
+    eventEmitter.doSomethingThatEmitsChange()
+  })
+})
+```
+
 ## Make changes related to Chai upgrade
 
 Chai 3 has been upgraded to Chai 4, which includes a number of breaking changes and new features outlined in [Chai's migration guide](https://github.com/chaijs/chai/issues/781). Some changes you might notice include: