docs: Add warning about async callback for describe

[mcdurdin]

Requirements

• Filling out the template is required. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion.
• All new code requires tests to ensure against regressions.

Description of the Change

This is a documentation only change.

I couldn't find any reference to describe not supporting an async callback. It seems like a natural conclusion to draw, given mocha specializes in async tests, and given it and hook do.

I spent considerable time trying to figure out why an async test was failing in one of my modules before I discovered the reason deep in an issue discussion (#2975 (comment))!

Alternate Designs

Why should this be in core?

This is a documentation change.

Benefits

I hope that this helps others design their test suites (I saw a number of comments about spending 'lots of time' trying to figure this out).

Possible Drawbacks

Applicable issues

• Describe block with async function behaving weirdly #2975
• 🚀 Feature: Allow async function in describe (block) #2116
• Please allow describe can do async with done/promise #2085

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: mcdurdin / name: Marc Durdin (9e708d9, 65133eb)

[JoshuaKGoldberg]

LGTM! Just a couple small touchups for typos.

[JoshuaKGoldberg]

Note that #4921 should also help with this.

[voxpelli]

Can we simplify it a bit?

[voxpelli]

Suggested change

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.

You can use all asynchronous callbacks (`done`, `Promise`, and `async`/`await`) in callbacks for `it()`, `before()`, `after()`, `beforeEach()`, `afterEach()`) but not `describe()` -- it must be synchronous.

[mcdurdin]

OK for all changes except that I feel like understanding the 'why' really helped me here.

[voxpelli]

Yeah, I'm thinking its maybe getting a bit too much into the current implementation of things, I'll have a think about it.

If we include it then maybe as a new paragraph, like Technically this is caused by...? Thoughts @mochajs/maintenance-crew?

[JoshuaKGoldberg]

IMO we can just say that they're synchronous / run synchronously. I don't think we need to go deep here.

I think we have two options that we can do well:

• Give a cursory explanation ("this is just how it is")
• Give a deep explanation on why

The deep explanation option would be far too much information for a root-level docs site. As a general ideology, one should never have to rely on deep architectural explanations in root-level docs.

[voxpelli]

Yeah, and it can always be found by looking in the GitHub history of that documentation line as it will reference this PR 😌