doc: add note (and caveat) for mock.module about customization hooks

[JakobJingleheimer]

So for instance, if mocking a tsx module and a loader was registered via the async API (module.register(), --loader, etc), the test-runner doesn't use it and throws trying to validate format (even though it will actually work):

node/lib/internal/test_runner/mock/mock.js

Lines 650 to 653 in f8d5bad

	const { format, url } = sharedState.moduleLoader.resolveSync(caller, request);
	debug('module mock, url = "%s", format = "%s", caller = "%s"', url, format, caller);
	if (format) { // Format is not yet known for ambiguous files when detection is enabled.
	validateOneOf(format, 'format', kSupportedFormats);

This is mainly problem within the ModuleLoader itself, which checks whether sync hooks exist; when they do, it uses that chain and ignores the potential existence of registered async hooks:

node/lib/internal/modules/esm/loader.js

Lines 727 to 734 in f8d5bad

	resolveSync(parentURL, request) {
	const specifier = `${request.specifier}`;
	const importAttributes = request.attributes ?? kEmptyObject;
	if (syncResolveHooks.length) {
	// Has module.registerHooks() hooks, chain the asynchronous hooks in the default step.
	return resolveWithSyncHooks(specifier, parentURL, importAttributes, this.#defaultConditions,
	this.#resolveAndMaybeBlockOnLoaderThread.bind(this));

The problem for the test runner was created/exposed by switching the test-runner's loader to sync registration, which ensures there's always a sync chain (causing the async chain to be ignored internally).

Geoffrey, Joyee, Matteo, and I discussed this scenario ~a year ago in Dublin. The fix is not simple.

It would need to do something like this

slack convo

[nodejs-github-bot]

Review requested:

• @nodejs/test_runner

[github-actions]

Fast-track has been requested by @JakobJingleheimer. Please 👍 to approve.