🚀 Feature: Custom error message for failed await

[jahorton]

Is your feature request related to a problem or a nice-to-have?? Please describe.
In a module I'm working on, I'm unit testing a scenario that involves very significant amounts of Promise chaining. Naturally, should the tested component break, the output I usually get is:

Error: Timeout of 2000ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.

This doesn't really give me much insight into why a Promise-chain test failed; I only get to know that it failed. I don't even get to see how much of the unit test completed before failing.

To be clear, I'm developing the Promises that are being chained and tested, as well as the parts that are using these Promises.

Describe the solution you'd like

The request: I'd like something similar to the following:

// ...

this.timeoutError = new Error("The third `Promise` in the chain failed to resolve!");
let value = await thirdPromise;

to produce the following failure log message on timeout:

Error: The third `Promise` in the chain failed to resolve!
  at <the constructed Error's call stack>    

Or at least something similar that provides much higher-quality information for diagnosing the test failure than the generic error above.

Setting this.timeoutError = null or = undefined would clear the error object and set the default message back in place.

I've opted for this.timeoutError in this proposal because this.timeout already exists as a feature, so this should be easy enough to integrate with Mocha's existing design - the essential mechanics seem to be present already, with this.timeout's existing implementation serving as a useful guide.

Describe alternatives you've considered
Of course, it's possible this may belong more in an assertion library of some sort... though I suspect an assertion library would actually need some sort of Mocha hook to connect with for the error report.

I'd love an assertion library to provide:

let value = assert.await(thirdPromise, "The third `Promise` in the chain failed to resolve!");

and provide a beautiful corresponding call stack for the failed await, complete with an AssertionAsyncError type/heading (rather than plain Error). This would even show the exact line of the test case's point-of-failure in the call stack. That said, I realize that this aspect - the custom assertion function - is better asked of assertion libraries like chai.js than of Mocha.

Either way, only getting a generic Error: Timeout message... doesn't provide me with much information on where the timeout error occurred within the Promise chain / heavily async/await-based unit test. A feature like this would provide much better feedback for such use cases.

---

The greater context: I'm coding a custom gesture engine component for a project; this engine involves a processing stage which performs segmentation of the user's touchpath, with a goal of facilitating complex gesture types. Naturally, this segmentation happens live over time - gestures should feel responsive, after all - and thus involves quite a bit of asynchronous reasoning. I'm finding it important to test the ordering of Promise resolution so that I can provide guarantees on resolution order for its consumer(s).

[JoshuaKGoldberg]

This was filed in 2022 and hasn't had any interactions in the >1 year since. Per #5027 we're trying to avoid doing too many changes that don't have a lot of broad user appeal. This feature request makes sense but would need a lot of discussion to evaluate how exactly to make it work in Mocha. The user demand just doesn't seem to be there. Thanks for filing though!

For reference, you can implement it in user-land with code like something like:

// setup.js

let timeoutError;

module.exports.getTimeoutError = () => timeoutError;

module.exports.setTimeoutError = (newValue) => {
  timeoutError = newValue;
};

afterEach(function () {
  if (timeoutError && this.currentTest.state !== "passed") {
    throw timeoutError;
  }
});

// test.spec.js

const { setTimeoutError } = require("./setup.js");

it("works quickly", (done) => {
  setTimeoutError(new Error("Failed to finish"));
  setTimeout(done, 9001);
});

If you end up making a standalone library for this and that library gets popular, we can always re-evaluate adding it to Mocha core. That'd be a great sign that I'm wrong and user demand actually is there. 😄

Thanks for filing - it's an interesting idea. Cheers! 🤎