Async describe
A describe callback that awaits something before declaring its tests has to take the suite's scope as its parameter:
describe("parser", async ({ it }) => {
const cases = JSON.parse(await readFile("cases.json", "utf8"));
for (const entry of cases) {
it(entry.name, () => { … });
}
});Destructure what you need from the scope, and the body reads as it would otherwise.
Why it needs the scope
A describe callback returns at its first await, and the runner moves on. A plain it called after that no longer knows which suite it's in, so it would land at a shallower path, and integrations would give it the wrong identity.
The scope's members are bound to that suite, so an await can't change where they register. It has describe, it, test, beforeEach, and afterEach, plus beforeAll and afterAll when your runner has them. A nested describe gets a scope of its own. expect isn't on it, since it doesn't depend on the suite.
Without the scope, harness throws
An async callback that doesn't declare a parameter throws AsyncDescribeError, naming the suite. Without the error, its tests would be registered at the wrong path, with nothing to say so.
A hook called after an await throws AmbientHookError for the same reason. Take hooks from the scope too:
describe("parser", async ({ it, beforeEach }) => { … });What the runner does with it
Once the callback takes its scope, harness hands its promise to your runner, and runners differ:
| runner | async describe |
|---|---|
| bun, vitest, rstest | awaited |
node:test | awaited |
| jest | rejected by jest |
| mocha | the tests inside are silently dropped |
On jest and mocha, keep the describe callback synchronous, and load what it needs before it, at the top of the file.
