meocord 4.1.2 → 4.2.0

package/dist/esm/testing/meocord-testing-module.js

@@ -7,7 +7,7 @@ import { CooldownStore, MemoryCooldownStore } from '../common/cooldown-store.js'
 import { ExecutionContext } from '../common/execution-context.js';
 import { Translator, missingTranslatorError } from '../common/translator.js';
 import { injectedTokens, singletonContextError } from '../core/guard-runner.js';
-import { appPresenterOf, runHandler, appStages, bindGlobalStages, prepareHandlerStages, bindAppPresenter } from '../core/handler-pipeline.js';
+import { appPresenterOf, runHandler, appStages, bindGlobalStages, prepareHandlerStages, prepareAppPresenter, prepareThemes, bindAppPresenter } from '../core/handler-pipeline.js';
 import { setPresenter } from '../common/response/presenter.js';
 import { componentRouteFor, commandMismatch, handlerInput } from '../core/handler-input.js';
 import { buildComponentRoutes } from '../core/component-routes.js';
@@ -21,11 +21,11 @@ import { messageParamsFor, buildMessageRoutes } from '../core/message-routes.js'
 import { assertDistinctCommands, warnUnregisteredCommands, warnInheritedRoutes, warnOverlappingPatterns, warnHandlersOffControllers } from '../core/command-conflicts.js';
 import { messageCommandHooks } from '../core/message-params.js';
 import { appObservers, assertObservers, bindObservers } from '../core/observer-runner.js';
-import { makeInjectable } from '../util/injectable.util.js';
 import { HandlerRegistry } from '../core/handler-registry.js';
 import { adviseInPlaceOfInjecting, meocordClasses } from '../core/meocord-classes.js';
 import { startupClasses, assertStartupClasses, lateGuardCheck } from '../core/startup-roots.js';
 import { markStartupChecked, assertStartupChecked } from '../core/startup-checked.js';
+import { makeInjectable } from '../util/injectable.util.js';
 import { ShardContext, shardCallHandler } from '../core/shard-context.js';
 import { isAppClassToken } from '../core/lifecycle-order.js';
 import { lifecycleEntry, runShutdownSequence, runReadyHooks, callsSettled } from '../core/lifecycle-hooks.js';
@@ -33,6 +33,8 @@ import { createMockClient } from './mock-interaction.js';
 import { Dispatcher } from '../core/dispatcher.js';
 import { createFallback } from '../core/fallback.js';
 import { Logger } from '../common/logger.js';
+import { isExplainedError, markExplained } from '../common/explained-error.js';
+import { declaredErrorsOf, collectStartupErrors, startupError, stopOnStartupErrors, isRefusal, logStartupErrors } from '../util/refusal.util.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, shutdownTimeoutProblem } from '../util/shutdown-timeout.util.js';
 import { resolveProviders, tokenName, bindsOwnToken, providerMap, bindProvider, resolutionOrder, isClassProvider, assertProvided, tokenDependencies } from '../core/providers.js';
 import { getEventHandlers } from '../decorator/event.decorator.js';
@@ -69,7 +71,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
  * @category Module
  * @see {@link MeoCordTestingModule}
  * @see {@link getResponse}
- * @see {@link https://meocord.dev/docs/4.1/invoke-and-dispatch | Invoke and dispatch}
+ * @see {@link https://meocord.dev/docs/4.2/invoke-and-dispatch | Invoke and dispatch}
  */ class TestingModule {
     /**
    * Resolves the module's `useFactory` providers, awaiting those that return a promise, in dependency
@@ -343,6 +345,8 @@ import { isUserOutcome } from '../common/user-outcome.js';
             controllerClasses: this.controllers,
             messageOptions: this.messageOptions,
             logger,
+            // A test's fake clock can pass 5 s inside a handler, so the slow-handler warning waits to be asked for
+            warnSlowMessageHandlers: false,
             // Strict: an answer MeoCord fails to build rejects the dispatch, where a bot logs it and carries on
             fallback: createFallback(logger, ()=>this.messageOptions, {
                 strict: true,
@@ -509,7 +513,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
  * @group Testing
  * @category Module
  * @see {@link MeoCordTestingModule}
- * @see {@link https://meocord.dev/docs/4.1/testing | The testing module}
+ * @see {@link https://meocord.dev/docs/4.2/testing | The testing module}
  */ class TestingModuleBuilder {
     /**
    * Replaces a provider with a test double.
@@ -657,199 +661,236 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * its command's builder does not register, a customId pattern given as a command name, a builder that registers
    * another name, and component patterns that can match the same customId are named, as the bot names them.
    *
+   * Each check reports every startup error it finds, and the first is thrown, unchanged; when there are several, each
+   * is logged first, with the file it comes from. After {@link reportAllStartupErrors}, the errors decorators kept on
+   * the classes the module runs are among them.
+   *
    * @returns The compiled module.
+   * @throws Error for the first startup error the checks find.
    */ compile() {
         // The bound the bot's config gives it, with the same words
         const shutdownTimeout = this.options.shutdownTimeout === undefined ? undefined : shutdownTimeoutProblem(this.options.shutdownTimeout);
         if (shutdownTimeout) throw new TypeError(`shutdownTimeout ${shutdownTimeout}.`);
-        const container = new Container();
-        const stages = this.globalStages();
-        if (stages) bindGlobalStages(container, stages);
-        // Bound first, as in the app, so a class that injects it gets this instance
-        const appClasses = [];
-        const translator = ()=>container.isBound(Translator) ? container.get(Translator) : undefined;
-        container.bind(HandlerRegistry).toConstantValue(new HandlerRegistry(appClasses, messagesOf(this.options.app), translator));
-        // A testing module runs as one process, so a cross-shard call runs once, here
-        container.bind(ShardContext).toConstantValue(new ShardContext(undefined, shardCallHandler(container, ()=>[
-                ...appClasses,
-                ...[
-                    ...providers.keys()
-                ].filter(isAppClassToken)
-            ], 'this testing module')));
-        bindsOwnToken(container, HandlerRegistry);
-        bindsOwnToken(container, ShardContext);
-        // Checked as the app checks its own: the app's providers in their order, then the test's, which replace them
-        // by token, then the overrides, which win
-        const providers = providerMap(this.wiring?.providers ?? [], '@MeoCord({ providers })');
-        for (const [token, provider] of providerMap(this.options.providers ?? [], "the testing module's providers"))providers.set(token, provider);
-        for (const [token, override] of this.overrides)providers.set(token, override);
-        const services = this.wiring?.services ?? [];
-        const appOptions = this.options.app ? Reflect.getMetadata(META.appOptions, this.options.app) : undefined;
-        // The app's own store, as the bot binds it, whether the module is given the app or built from it; none when the
-        // test provides the CooldownStore, so nothing builds the app's or asks for what it injects
-        const store = providers.has(CooldownStore) ? undefined : appOptions?.cooldownStore;
-        // The themeFor class this module runs, the app's or overrideThemeFor's, bound on its own as the app binds it
-        const themeResolver = themeResolverClass(stages?.themeFor?.resolvers);
-        // Every class the module runs, as the app finds them, except stage classes an override stands in for
-        const i18n = this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.i18n;
-        const startup = startupClasses({
-            controllers: this.options.controllers ?? [],
-            services,
-            providers,
-            stages,
-            presenter: this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.presenter,
-            cooldownStore: store,
-            themeFor: stages?.themeFor?.resolvers,
-            observers: [
-                ...this.options.app ? appObservers(this.options.app) : [],
-                ...this.options.observers ?? []
-            ],
-            stubs: [
-                ...this.guardOverrides.keys(),
-                ...this.interceptorOverrides.keys(),
-                ...this.filterOverrides.keys()
-            ]
-        });
-        const hasTranslator = i18n !== undefined || providers.has(Translator);
-        assertStartupClasses(startup, {
-            translator: hasTranslator
-        });
-        markStartupChecked(container, [
-            ...startup.classes,
-            ...meocordClasses()
-        ], lateGuardCheck(providers, hasTranslator));
-        // The bot binds the Client it logs in with; a test gives its own, and is told so where one is needed
-        const needClient = startup.classes.filter((cls)=>injectedTokens(cls).includes(Client));
-        if (needClient.length > 0 && !providers.has(Client)) {
-            container.bind(Client).toDynamicValue(()=>{
-                throw new Error(`${needClient.map((cls)=>cls.name).join(', ')} ${needClient.length === 1 ? 'injects' : 'inject'} the Discord Client, ` + 'which a testing module does not make: give one in its providers, such as ' + '{ provide: Client, useValue: createMockClient() }.');
-            });
-        }
-        // Bind guard overrides — prevents inversify from auto-wiring guard dependencies
-        for (const [guardClass, stub] of this.guardOverrides){
-            container.bind(guardClass).toConstantValue(stub);
-        }
-        for (const [filterClass, stub] of this.filterOverrides){
-            container.bind(filterClass).toConstantValue(stub);
-        }
-        for (const [interceptorClass, stub] of this.interceptorOverrides){
-            container.bind(interceptorClass).toConstantValue(stub);
-        }
-        // The app's cooldown policy, so a test of a failing store sees what the bot would do
-        if (appOptions && !container.isBound(COOLDOWN_POLICY)) container.bind(COOLDOWN_POLICY).toConstantValue(cooldownPolicyFrom(appOptions));
-        // The app's translator, unless a provider stands in for it
-        if (i18n && !providers.has(Translator)) {
-            container.bind(Translator).toConstantValue(i18n);
-            bindsOwnToken(container, Translator);
-        }
-        // Recursively bind controllers and their dependencies, skipping already-bound tokens
-        const bindClass = (cls)=>{
-            // A provided class is bound by its own provider, wherever in the list that provider comes
-            if (container.isBound(cls) || providers.has(cls)) return;
-            if (injectedTokens(cls).includes(ExecutionContext)) throw singletonContextError(cls);
-            assertStartupChecked(container, cls);
-            makeInjectable(cls);
-            container.bind(cls).toSelf().inSingletonScope();
-            // By constructor type or @inject token, as the app binds them
-            for (const dep of injectedTokens(cls)){
-                if (dep === Translator && !container.isBound(Translator)) throw missingTranslatorError(cls);
-                if (isAppClassToken(dep)) bindClass(dep);
-            }
-        };
-        // The app's own store, resolved like a service, unless the test provides the CooldownStore itself; bound first, as the
-        // app binds it, so a class that injects the token gets the store
-        if (!providers.has(CooldownStore)) {
-            if (store) {
-                bindClass(store);
-                container.bind(CooldownStore).toService(store);
-            } else {
-                container.bind(CooldownStore).toConstantValue(new MemoryCooldownStore());
-            }
-            bindsOwnToken(container, CooldownStore, store);
-        }
-        // Before the controllers, so a class token that is provided is not also bound as itself
-        for (const provider of providers.values())bindProvider(container, provider, bindClass);
-        for (const ctrl of this.options.controllers ?? []){
-            bindClass(ctrl);
-            // Stamp container on controller class so @UseGuard works in tests too
-            Reflect.defineMetadata(META.container, container, ctrl);
-        }
-        for (const service of services)bindClass(service);
-        if (themeResolver) bindClass(themeResolver);
-        // The classes whose @On and @Once handlers emit reaches: class providers bound as themselves, the
-        // controllers, and what they inject; factories resolve in the same order
-        const order = resolutionOrder(container, providers, [
-            ...providers.keys(),
-            ...services,
-            ...themeResolver ? [
-                themeResolver
-            ] : [],
-            ...this.options.controllers ?? []
-        ], {
-            followOwnTokens: false
-        });
-        appClasses.push(...order.filter((token)=>{
-            const provider = providers.get(token);
-            return isAppClassToken(token) && (!provider || isClassProvider(provider) && provider.useClass === token);
-        }));
-        assertProvided(container, providers, startup.classes, "the testing module's providers");
-        // Every class the module runs, so @UseGuard resolves guards on a direct call to any of them
-        for (const cls of startup.classes)Reflect.defineMetadata(META.container, container, cls);
-        prepareHandlerStages(container, appClasses);
-        const messages = messagesOf(this.options.app);
-        // As the app would at startup, refuses a message pattern that cannot be read or two that match the same messages
-        buildMessageRoutes(this.options.controllers ?? [], messages);
-        // As the app does when it is created, so a test sees the refusal the bot would give
-        assertDistinctCommands(this.options.controllers ?? []);
-        // A handler with no builder is how a fixture is written, so only what is always a mistake is named
-        warnUnregisteredCommands(this.options.controllers ?? [], {
-            missingBuilders: false
-        });
-        warnInheritedRoutes(this.options.controllers ?? []);
-        warnOverlappingPatterns(this.options.controllers ?? []);
-        warnHandlersOffControllers(this.options.controllers ?? [], appClasses);
-        if (this.options.app) bindAppPresenter(container, this.options.app);
-        const observers = [
-            ...this.options.app ? appObservers(this.options.app) : [],
-            ...this.options.observers ?? []
-        ];
-        assertObservers("the testing module's observers", observers);
-        bindObservers(container, observers);
-        // The store calls ask: the test's own when it provides CooldownStore, else the app's
-        const boundStore = store ?? (providers.has(CooldownStore) ? CooldownStore : undefined);
-        // The order the app runs lifecycle hooks in: its cooldown store, then providers, controllers and observers, each
-        // after what it injects
-        const lifecycle = resolutionOrder(container, providers, [
-            ...boundStore ? [
-                boundStore
-            ] : [],
-            ...providers.keys(),
-            ...services,
-            ...themeResolver ? [
-                themeResolver
+        // With startupErrors: 'all', what the decorators kept on the classes this module runs
+        const declared = declaredErrorsOf([
+            ...this.options.app ? [
+                this.options.app
             ] : [],
             ...this.options.controllers ?? [],
-            ...observers
-        ]).map((token)=>({
-                token,
-                name: tokenName(token),
-                dependencies: tokenDependencies(container, providers, token),
-                ...token === boundStore && {
-                    cooldownStore: true
+            ...this.wiring?.services ?? [],
+            ...this.options.observers ?? []
+        ]);
+        // Every error each check finds is reported, as the bot reports them, and the first is thrown
+        try {
+            return collectStartupErrors(()=>{
+                declared.forEach(startupError);
+                const container = new Container();
+                const stages = this.globalStages();
+                if (stages) bindGlobalStages(container, stages);
+                // Bound first, as in the app, so a class that injects it gets this instance
+                const appClasses = [];
+                const translator = ()=>container.isBound(Translator) ? container.get(Translator) : undefined;
+                container.bind(HandlerRegistry).toConstantValue(new HandlerRegistry(appClasses, messagesOf(this.options.app), translator));
+                // A testing module runs as one process, so a cross-shard call runs once, here
+                container.bind(ShardContext).toConstantValue(new ShardContext(undefined, shardCallHandler(container, ()=>[
+                        ...appClasses,
+                        ...[
+                            ...providers.keys()
+                        ].filter(isAppClassToken)
+                    ], 'this testing module')));
+                bindsOwnToken(container, HandlerRegistry);
+                bindsOwnToken(container, ShardContext);
+                // Checked as the app checks its own: the app's providers in their order, then the test's, which replace them
+                // by token, then the overrides, which win
+                const providers = providerMap(this.wiring?.providers ?? [], '@MeoCord({ providers })');
+                for (const [token, provider] of providerMap(this.options.providers ?? [], "the testing module's providers"))providers.set(token, provider);
+                for (const [token, override] of this.overrides)providers.set(token, override);
+                // Each pass of checks ends before the next step that is no check, so a module with one error stops where it always did
+                stopOnStartupErrors();
+                const services = this.wiring?.services ?? [];
+                const appOptions = this.options.app ? Reflect.getMetadata(META.appOptions, this.options.app) : undefined;
+                // The app's own store, as the bot binds it, whether the module is given the app or built from it; none when the
+                // test provides the CooldownStore, so nothing builds the app's or asks for what it injects
+                const store = providers.has(CooldownStore) ? undefined : appOptions?.cooldownStore;
+                // The themeFor class this module runs, the app's or overrideThemeFor's, bound on its own as the app binds it
+                const themeResolver = themeResolverClass(stages?.themeFor?.resolvers);
+                // Every class the module runs, as the app finds them, except stage classes an override stands in for
+                const i18n = this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.i18n;
+                const startup = startupClasses({
+                    controllers: this.options.controllers ?? [],
+                    services,
+                    providers,
+                    stages,
+                    presenter: this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.presenter,
+                    cooldownStore: store,
+                    themeFor: stages?.themeFor?.resolvers,
+                    observers: [
+                        ...this.options.app ? appObservers(this.options.app) : [],
+                        ...this.options.observers ?? []
+                    ],
+                    stubs: [
+                        ...this.guardOverrides.keys(),
+                        ...this.interceptorOverrides.keys(),
+                        ...this.filterOverrides.keys()
+                    ]
+                });
+                const hasTranslator = i18n !== undefined || providers.has(Translator);
+                assertStartupClasses(startup, {
+                    translator: hasTranslator
+                });
+                // Those of the stages, guards and other classes they reach
+                declaredErrorsOf(startup.classes).forEach(startupError);
+                stopOnStartupErrors();
+                markStartupChecked(container, [
+                    ...startup.classes,
+                    ...meocordClasses()
+                ], lateGuardCheck(providers, hasTranslator));
+                // The bot binds the Client it logs in with; a test gives its own, and is told so where one is needed
+                const needClient = startup.classes.filter((cls)=>injectedTokens(cls).includes(Client));
+                if (needClient.length > 0 && !providers.has(Client)) {
+                    container.bind(Client).toDynamicValue(()=>{
+                        throw new Error(`${needClient.map((cls)=>cls.name).join(', ')} ${needClient.length === 1 ? 'injects' : 'inject'} the Discord Client, ` + 'which a testing module does not make: give one in its providers, such as ' + '{ provide: Client, useValue: createMockClient() }.');
+                    });
+                }
+                // Bind guard overrides — prevents inversify from auto-wiring guard dependencies
+                for (const [guardClass, stub] of this.guardOverrides){
+                    container.bind(guardClass).toConstantValue(stub);
+                }
+                for (const [filterClass, stub] of this.filterOverrides){
+                    container.bind(filterClass).toConstantValue(stub);
+                }
+                for (const [interceptorClass, stub] of this.interceptorOverrides){
+                    container.bind(interceptorClass).toConstantValue(stub);
+                }
+                // The app's cooldown policy, so a test of a failing store sees what the bot would do
+                if (appOptions && !container.isBound(COOLDOWN_POLICY)) container.bind(COOLDOWN_POLICY).toConstantValue(cooldownPolicyFrom(appOptions));
+                // The app's translator, unless a provider stands in for it
+                if (i18n && !providers.has(Translator)) {
+                    container.bind(Translator).toConstantValue(i18n);
+                    bindsOwnToken(container, Translator);
                 }
-            }));
-        // Recorded as the container makes each one, so close() shuts down exactly what exists
-        const constructed = new Set();
-        for (const { token } of lifecycle){
-            container.onActivation(token, (_context, instance)=>{
-                constructed.add(token);
-                return instance;
+                // Recursively bind controllers and their dependencies, skipping already-bound tokens
+                const bindClass = (cls)=>{
+                    // A provided class is bound by its own provider, wherever in the list that provider comes
+                    if (container.isBound(cls) || providers.has(cls)) return;
+                    if (injectedTokens(cls).includes(ExecutionContext)) return startupError(singletonContextError(cls));
+                    assertStartupChecked(container, cls);
+                    makeInjectable(cls);
+                    container.bind(cls).toSelf().inSingletonScope();
+                    // By constructor type or @inject token, as the app binds them
+                    for (const dep of injectedTokens(cls)){
+                        if (dep === Translator && !container.isBound(Translator)) startupError(missingTranslatorError(cls));
+                        else if (isAppClassToken(dep)) bindClass(dep);
+                    }
+                };
+                // The app's own store, resolved like a service, unless the test provides the CooldownStore itself; bound first, as the
+                // app binds it, so a class that injects the token gets the store
+                if (!providers.has(CooldownStore)) {
+                    if (store) {
+                        bindClass(store);
+                        container.bind(CooldownStore).toService(store);
+                    } else {
+                        container.bind(CooldownStore).toConstantValue(new MemoryCooldownStore());
+                    }
+                    bindsOwnToken(container, CooldownStore, store);
+                }
+                // Before the controllers, so a class token that is provided is not also bound as itself
+                for (const provider of providers.values())bindProvider(container, provider, bindClass);
+                for (const ctrl of this.options.controllers ?? [])bindClass(ctrl);
+                for (const service of services)bindClass(service);
+                if (themeResolver) bindClass(themeResolver);
+                // What follows walks what these bound, so a class refused here is not reported again as missing
+                stopOnStartupErrors();
+                // The classes whose @On and @Once handlers emit reaches: class providers bound as themselves, the
+                // controllers, and what they inject; factories resolve in the same order
+                const order = resolutionOrder(container, providers, [
+                    ...providers.keys(),
+                    ...services,
+                    ...themeResolver ? [
+                        themeResolver
+                    ] : [],
+                    ...this.options.controllers ?? []
+                ], {
+                    followOwnTokens: false
+                });
+                appClasses.push(...order.filter((token)=>{
+                    const provider = providers.get(token);
+                    return isAppClassToken(token) && (!provider || isClassProvider(provider) && provider.useClass === token);
+                }));
+                assertProvided(container, providers, startup.classes, "the testing module's providers");
+                prepareHandlerStages(container, appClasses);
+                const messages = messagesOf(this.options.app);
+                // As the app would at startup, refuses a message pattern that cannot be read or two that match the same messages
+                buildMessageRoutes(this.options.controllers ?? [], messages);
+                // As the app does when it is created, so a test sees the refusal the bot would give
+                assertDistinctCommands(this.options.controllers ?? []);
+                if (this.options.app) prepareAppPresenter(container, this.options.app);
+                const observers = [
+                    ...this.options.app ? appObservers(this.options.app) : [],
+                    ...this.options.observers ?? []
+                ];
+                assertObservers("the testing module's observers", observers);
+                // Only @Observer classes are bound as observers
+                stopOnStartupErrors();
+                bindObservers(container, observers);
+                // The store calls ask: the test's own when it provides CooldownStore, else the app's
+                const boundStore = store ?? (providers.has(CooldownStore) ? CooldownStore : undefined);
+                // The order the app runs lifecycle hooks in: its cooldown store, then providers, controllers and observers, each
+                // after what it injects
+                const lifecycle = resolutionOrder(container, providers, [
+                    ...boundStore ? [
+                        boundStore
+                    ] : [],
+                    ...providers.keys(),
+                    ...services,
+                    ...themeResolver ? [
+                        themeResolver
+                    ] : [],
+                    ...this.options.controllers ?? [],
+                    ...observers
+                ]).map((token)=>({
+                        token,
+                        name: tokenName(token),
+                        dependencies: tokenDependencies(container, providers, token),
+                        ...token === boundStore && {
+                            cooldownStore: true
+                        }
+                    }));
+                // Every check has run, and touched only the container: from here the module is made, once none found an error
+                stopOnStartupErrors();
+                // Every class the module runs, so @UseGuard resolves guards on a direct call to any of them
+                for (const cls of [
+                    ...this.options.controllers ?? [],
+                    ...startup.classes
+                ])Reflect.defineMetadata(META.container, container, cls);
+                prepareThemes(container, appClasses);
+                // A handler with no builder is how a fixture is written, so only what is always a mistake is named
+                warnUnregisteredCommands(this.options.controllers ?? [], {
+                    missingBuilders: false
+                });
+                warnInheritedRoutes(this.options.controllers ?? []);
+                warnOverlappingPatterns(this.options.controllers ?? []);
+                warnHandlersOffControllers(this.options.controllers ?? [], appClasses);
+                if (this.options.app) bindAppPresenter(container, this.options.app);
+                // Recorded as the container makes each one, so close() shuts down exactly what exists
+                const constructed = new Set();
+                for (const { token } of lifecycle){
+                    container.onActivation(token, (_context, instance)=>{
+                        constructed.add(token);
+                        return instance;
+                    });
+                }
+                const warnUnanswered = this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.warnUnanswered;
+                return new TestingModule(container, [
+                    ...this.options.controllers ?? []
+                ], appClasses, providers, order, messages, lifecycle, constructed, warnUnanswered, services, this.options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT_MS);
             });
+        } catch (error) {
+            if (isRefusal(error) && !isExplainedError(error)) {
+                if (logStartupErrors(error, (text)=>new Logger('TestingModule').error(text), 'the testing module did not compile')) markExplained(error);
+            }
+            throw error;
         }
-        const warnUnanswered = this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.warnUnanswered;
-        return new TestingModule(container, [
-            ...this.options.controllers ?? []
-        ], appClasses, providers, order, messages, lifecycle, constructed, warnUnanswered, services, this.options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT_MS);
     }
     constructor(options, wiring){
         this.options = options;
@@ -887,7 +928,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
  * @category Module
  * @see {@link TestingModuleBuilder}
  * @see {@link TestingModule}
- * @see {@link https://meocord.dev/docs/4.1/testing | The testing module}
+ * @see {@link https://meocord.dev/docs/4.2/testing | The testing module}
  */ class MeoCordTestingModule {
     /**
    * Starts building a testing module from the classes a test needs.

package/dist/esm/testing/mock-fn.js

@@ -27,12 +27,70 @@
 // Every mock createMockFn made, held weakly so the mocks of a finished test can still be collected
 const created = new Set();
 const collected = new FinalizationRegistry((ref)=>created.delete(ref));
+// The runner's factory useMockFn registered, and for each of its mocks how to give back the implementation it was
+// created with, through the runner's own setter, which a mock's behaviour may wrap
+let runnerFactory;
+const restoreImpl = new WeakMap();
+/**
+ * Makes every mock `meocord/testing` creates with the test runner's own mock function, such as Vitest's `vi.fn`.
+ *
+ * Call it once in the runner's setup file. The runner then treats meocord's mocks as its own: its `clearMocks` and
+ * `mockReset` config and `vi.clearAllMocks()` reach them, its matchers read them, and its whole mock API is there.
+ * Without it, mocks are {@link createMockFn}'s own, which jest's and Vitest's `expect` read too.
+ *
+ * @remarks
+ * Each mock starts with the runner's mock holding meocord's behaviour, such as an interaction's replies, as its own
+ * implementation. {@link resetAllMocks} puts that behaviour back where the runner's `mockReset` drops it, as jest's and
+ * bun's do; a runner's own reset-all, such as jest's `resetMocks`, can't, so under jest and bun reset with
+ * {@link resetAllMocks}. node:test's `mock.fn` records calls in a shape of its own, so under node:test leave meocord's
+ * own function in place. Calling it again with the same factory does nothing; another, once a mock exists, throws.
+ *
+ * @param factory - The runner's mock function factory: `vi.fn`, `jest.fn` or bun's `mock`.
+ * @throws Error when a mock already exists from another factory, or when `factory` doesn't make a mock with jest's and
+ *   Vitest's API.
+ *
+ * @example
+ * ```ts
+ * // vitest.setup.ts
+ * import { vi } from 'vitest'
+ *
+ * useMockFn(vi.fn)
+ * ```
+ *
+ * @group Testing
+ * @category Mocks
+ * @see {@link createMockFn}
+ */ function useMockFn(factory) {
+    if (factory === runnerFactory) return;
+    if ([
+        ...created
+    ].some((ref)=>ref.deref() !== undefined)) {
+        throw new Error("useMockFn() goes before any mock is made: a mock made before it keeps meocord's own function, and the two kinds " + "would mix. Call it once, in the test runner's setup file.");
+    }
+    const probe = factory();
+    const api = [
+        'mockImplementation',
+        'mockClear',
+        'mockReset'
+    ];
+    if (!isMockFunction(probe) || !Array.isArray(probe.mock?.calls) || api.some((name)=>typeof probe[name] !== 'function')) {
+        throw new Error("useMockFn() takes a function that makes mocks with jest's and Vitest's API, such as vi.fn, jest.fn or bun's " + "mock. node:test's mock.fn records calls in its own shape, so under node:test leave meocord's own mock function " + 'in place.');
+    }
+    runnerFactory = factory;
+}
+/** Tracks a mock for clearAllMocks and resetAllMocks. */ function track(mockFn) {
+    const ref = new WeakRef(mockFn);
+    created.add(ref);
+    collected.register(mockFn, ref);
+    return mockFn;
+}
 /**
  * Clears the calls every mock from `meocord/testing` has recorded, keeping what each was told to do.
  *
- * Vitest's `clearMocks` and jest's `clearAllMocks()` reach only their own `vi.fn()` and `jest.fn()` mocks. This one
- * covers `createMockFn` and everything built on it, such as `createMockInteraction` and `createMockClient`. To also
- * undo what a test set, use {@link resetAllMocks}.
+ * Vitest's `clearMocks` and jest's `clearAllMocks()` reach only their own `vi.fn()` and `jest.fn()` mocks, and
+ * meocord's too once {@link useMockFn} makes them with the runner's function. This one covers `createMockFn` and
+ * everything built on it, such as `createMockInteraction` and `createMockClient`, either way. To also undo what a test
+ * set, use {@link resetAllMocks}.
  *
  * @example
  * ```ts
@@ -68,13 +126,20 @@ const collected = new FinalizationRegistry((ref)=>created.delete(ref));
  * @category Mocks
  * @see {@link clearAllMocks}
  */ function resetAllMocks() {
-    for (const ref of created)ref.deref()?.mockReset();
+    for (const ref of created){
+        const mockFn = ref.deref();
+        if (!mockFn) continue;
+        mockFn.mockReset();
+        // A runner whose reset drops the implementation the mock was created with, as jest's and bun's do, gets it back
+        restoreImpl.get(mockFn)?.();
+    }
 }
 /**
  * Creates a mock function that jest's and Vitest's `expect` both read.
  *
  * Use it for a function double in code that must not depend on one test runner, such as a shared test helper; in a
- * Vitest test, `vi.fn()` works as well. {@link clearAllMocks} and {@link resetAllMocks} reach it.
+ * Vitest test, `vi.fn()` works as well. {@link clearAllMocks} and {@link resetAllMocks} reach it. Once
+ * {@link useMockFn} registers a runner's function, it returns that runner's mock.
  *
  * @remarks
  * `mockReturnValue`, `mockResolvedValue`, `mockRejectedValue` and `mockImplementation` share one implementation, so
@@ -97,6 +162,14 @@ const collected = new FinalizationRegistry((ref)=>created.delete(ref));
  * @category Mocks
  * @see {@link MockInstance}
  */ function createMockFn(impl) {
+    if (runnerFactory) {
+        const runnerMock = runnerFactory(impl);
+        if (impl) {
+            const setImpl = runnerMock.mockImplementation.bind(runnerMock);
+            restoreImpl.set(runnerMock, ()=>setImpl(impl));
+        }
+        return track(runnerMock);
+    }
     // One persistent implementation and one queue of single-use ones, as in jest and vitest: the
     // four setters share the slot, so the last call wins, and the `*Once` variants share the queue,
     // so they run in declaration order.
@@ -209,10 +282,7 @@ const collected = new FinalizationRegistry((ref)=>created.delete(ref));
         name = n;
         return mockFn;
     };
-    const ref = new WeakRef(mockFn);
-    created.add(ref);
-    collected.register(mockFn, ref);
-    return mockFn;
+    return track(mockFn);
 }
 
-export { clearAllMocks, createMockFn, isMockFunction, resetAllMocks };
+export { clearAllMocks, createMockFn, isMockFunction, resetAllMocks, useMockFn };