From 65133eb43744402c979bbf985ed5893eaf07fee4 Mon Sep 17 00:00:00 2001 From: Marc Durdin Date: Wed, 13 Dec 2023 09:57:53 +1100 Subject: [PATCH 1/2] docs: Add warning about async callback for describe I couldn't find any reference to `describe` not supporting an async function. It seems like a natural idea given `it` and `before` do. I spent considerable time trying to figure out why an async test was failing before I discovered the reason deep in an issue discussion (https://github.com/mochajs/mocha/issues/2975#issuecomment-1004176440), so hope that this helps others design their test suites! --- docs/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/index.md b/docs/index.md index cf6896a0bf..49f41a29f3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -296,6 +296,10 @@ describe('#find()', function () { }); ``` +### Limitations of asynchronous callbacks + +You can use all three asynchronous patterns (`done`, `Promise`, and `async`/`await`) in callbacks for `it()` and for all hooks (`before()`, `after()`, `beforeEach()`, `afterEach()`), but `describe()` will not work correctly with an asynchronous callback -- it must be synchronous. This is because, in the "parsing" cycle all `describe` callbacks are excecuted and the test hierarchy (`runner`) is created, before any tests are run. + ## Synchronous Code When testing synchronous code, omit the callback and Mocha will automatically continue on to the next test. From 9e708d988c410c81d3dfbb69cce08795ae5c6f1f Mon Sep 17 00:00:00 2001 From: Marc Durdin Date: Wed, 6 Mar 2024 01:27:22 +1100 Subject: [PATCH 2/2] Update docs/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Josh Goldberg ✨ --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 49f41a29f3..d841fdf77a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -298,7 +298,7 @@ describe('#find()', function () { ### Limitations of asynchronous callbacks -You can use all three asynchronous patterns (`done`, `Promise`, and `async`/`await`) in callbacks for `it()` and for all hooks (`before()`, `after()`, `beforeEach()`, `afterEach()`), but `describe()` will not work correctly with an asynchronous callback -- it must be synchronous. This is because, in the "parsing" cycle all `describe` callbacks are excecuted and the test hierarchy (`runner`) is created, before any tests are run. +You can use all three asynchronous patterns (`done`, `Promise`, and `async`/`await`) in callbacks for `it()` and for all hooks (`before()`, `after()`, `beforeEach()`, `afterEach()`), but `describe()` will not work correctly with an asynchronous callback -- it must be synchronous. This is because in the "parsing" cycle all `describe` callbacks are executed and the test hierarchy (`runner`) is created before any tests are run. ## Synchronous Code