doc: call out potentially unexpected results when mocking and testing synchronous callback-based APIs #58170
Conversation
When mocking synchronous callback-based APIs, the `MockFunctionContext` tracking mock calls won't be register until after the mock function finishes execution. Tests exercising callback-based code will likely not be written in a way to ensure this is the case. As such, call this out in the documentation. Fixes: nodejs#58161
|
Review requested:
|
nodejs-github-bot
added
doc
| @@ -652,6 +652,86 @@ test('spies on an object method', (t) => { | |||
| }); | |||
| ``` | |||
|
|
|||
| ### Mocking callback-based APIs | |||
There was a problem hiding this comment.
I don't think we should document this as specific to callback based APIs. It probably makes sense to call them out as a case where you can encounter this issue, but it doesn't inherently have anything to do with callbacks. The problem also goes away when making callbacks asynchronous, as they generally are within Node.
The issue is really that the call is not recorded until the mocked function returns. You would run into the same issue if you tried to access the call from within a mock of a synchronous functon.
There was a problem hiding this comment.
That's fair. I struggled with how to frame this particular situation in the context of these docs; I think it deserves call-out status in the docs, but I am also biased to think that given I spent some time digging into this issue to figure out what was going on 😛
You would run into the same issue if you tried to access the call from within a mock of a synchronous function.
Is this a reasonable equivalency? From my own perspective, I wouldn't expect to be able to access MockFunctionContext references as the mock itself is still executing. But I did expect to be able to do so when mocking a sync callback. Perhaps this reveals more about my lack of understanding of node internals more than anything else 😆 but I also see this discussion as the magic that is consumers of a project hashing out some point with maintainers of a project - we each bring our own biases to bear but hopefully can meet in the middle somewhere.
I'll have a think about how to frame this gotcha as the result of the mock still executing rather than something unique to callback-based APIs. Open to suggestions / ideas!
This PR fixes #58161.
When mocking synchronous callback-based APIs, the
MockFunctionContexttracking mock calls won't be register until after the mock function finishes execution. Tests exercising callback-based code will likely not be written in a way to ensure this is the case. As such, call this out in the documentation.