meocord 4.1.2 → 4.2.1

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

@@ -6,8 +6,8 @@ import { ReactionHandlerAction } from '../enum/controller.enum.js';
 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 { injectedTokens, singletonContextError, recordInstanceContainers } from '../core/guard-runner.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,21 +21,26 @@ 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 { startupClasses, assertStartupClasses, lateGuardCheck, stageDependencies } 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';
-import { createMockClient } from './mock-interaction.js';
+import { runShutdownSequence, runReadyHooks, ReadyPass, lifecycleEntry, callsSettled } from '../core/lifecycle-hooks.js';
+import { createMockClient, noteReactionDispatch } 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';
+import { getReactionHandlers } from '../decorator/controller.decorator.js';
+import { strictMocks } from './strict-mocks.js';
+import { warnOnce } from '../common/deprecation.js';
 import { META } from '../util/metadata-keys.js';
 import { isUserOutcome } from '../common/user-outcome.js';
 
@@ -69,7 +74,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
@@ -108,7 +113,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
         await this.resolving;
         if (options.ready) {
             const { client = createMockClient(), primary = true } = options.ready === true ? {} : options.ready;
-            this.readying ?? (this.readying = this.runReady(client, primary));
+            this.readying ?? (this.readying = this.readyPass.run(()=>this.runReady(client, primary)));
             await this.readying;
         }
         return this;
@@ -123,12 +128,21 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * It first gives up the theme read outside calls, if `init({ ready: true })` made it this module's;
    * reads outside calls then return MeoCord's defaults until another module or app is ready.
    *
+   * A stopped bot runs nothing more. Once `close()` is called, a module still runs what `dispatch`, `invoke` and `emit`
+   * are given, against services shut down, or shutting down, and warns once that it is closed, so a `close()` in the
+   * wrong place shows.
+   *
    * The cooldown store and what it injects shut down last, in the same sequence as the bot's. When any of them has an
    * `onShutdown`, the calls `invoke`, `dispatch` and `emit` have under way finish first, then the store operations
    * they started, so the store's last writes still reach it. The module stops waiting for the whole sequence after
    * its `shutdownTimeout`, 10 seconds unless set, and logs that it did. Give a test whose fake store never answers, or
    * whose `onShutdown` never settles, a short `shutdownTimeout`.
    *
+   * A `close()` while `init({ ready: true })` runs the `onReady` hooks waits for them first, within the same
+   * `shutdownTimeout`. An `onReady` still running once only the hooks' share of it is left is named in a warning, and
+   * its class is shut down all the same, as everything the module constructed is. One that calls `close()` itself isn't
+   * waited for.
+   *
    * @returns Once every hook has run. Rejects with the error of a hook that failed, or an
    *   `AggregateError` naming each when several did.
    *
@@ -143,14 +157,18 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * expect(module.get(POOL).ended).toBe(true)
    * ```
    */ async close() {
+        // An onReady awaiting close() would otherwise hold up the close that waits for it
+        this.readyPass.excuseCurrent();
         this.closing ?? (this.closing = (async ()=>{
-            // A close during init waits for the hooks it started, so it shuts down whatever they constructed
-            await this.readying?.catch(()=>undefined);
-            const entries = this.lifecycle.filter((unit)=>this.constructed.has(unit.token))// Already made, so this returns the instance; a provided value may be anything, null included
-            .map((unit)=>lifecycleEntry(unit, this.container.get(unit.token) ?? {}));
+            // A close during init waits for the providers it started, and the sequence for its onReady hooks, so it shuts
+            // down whatever they constructed
+            await this.resolving?.catch(()=>undefined);
+            const entries = ()=>this.lifecycle.filter((unit)=>this.constructed.has(unit.token))// Already made, so this returns the instance; a provided value may be anything, null included
+                .map((unit)=>lifecycleEntry(unit, this.container.get(unit.token) ?? {}));
             const failures = [];
             await runShutdownSequence(this.container, entries, {
                 drainCalls: ()=>callsSettled(this.calls),
+                readyPass: this.readyPass,
                 timeoutMs: this.shutdownTimeout,
                 hookFailed: (name, error)=>failures.push({
                         name,
@@ -164,6 +182,11 @@ import { isUserOutcome } from '../common/user-outcome.js';
         })());
         await this.closing;
     }
+    /** Warns once, after `close()`, that a call runs against services already shut down. */ warnIfClosed() {
+        if (this.closing === undefined || this.warnedClosed) return;
+        this.warnedClosed = true;
+        new Logger('TestingModule').warn('This testing module is closed, and its services are shut down, or shutting down, so dispatch, invoke and emit run ' + 'against that state. Close it after the last call, in afterEach.');
+    }
     async runReady(client, primary) {
         // As the bot claims it before it comes online, so onReady reads the app's theme
         claimAmbientAppTheme(this.container);
@@ -179,6 +202,8 @@ import { isUserOutcome } from '../common/user-outcome.js';
         }, [], {
             resolveFailed: failed,
             hookFailed: failed
+        }, {
+            runOnReady: this.readyPass.runOnReady
         });
         throwFailures('onReady', failures);
     }
@@ -250,7 +275,9 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * @returns Whether the handler ran, and the error a filter handled, if any. Rejects with an error no
    *   filter handles, or with the error a filter throws: the built-in fallback, which answers such
    *   errors in the bot, does not run here. Rejects before running anything with an interaction or a
-   *   message the handler's route does not match, naming both.
+   *   message the handler's route does not match, naming both. Given fewer arguments than the handler
+   *   declares, with a first that is neither an interaction nor a message, such as a reaction without its
+   *   `ReactionEvent`, it rejects under `useStrictMocks()`, and otherwise warns once and runs the handler.
    *
    * @example
    * ```ts
@@ -272,6 +299,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * expect(outcome.error).toBeInstanceOf(GuardDeniedError)
    * ```
    */ async invoke(controller, methodName, ...args) {
+        this.warnIfClosed();
         await this.init();
         if (!this.controllers.includes(controller)) {
             throw new Error(`${controller.name} is not a controller of this testing module. Add it to \`controllers\`.`);
@@ -301,6 +329,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
                 hooks = messageCommandHooks(route, params, first, start, given, this.messageOptions.types);
             }
         }
+        this.checkArgumentCount(controller, methodName, instance[methodName], first, callArgs.length);
         const presenter = appPresenterOf(this.container);
         // A message command's errors are drawn by the app's presenter too, as an interaction's are
         const client = first instanceof BaseInteraction || first instanceof Message ? first.client : undefined;
@@ -317,6 +346,19 @@ import { isUserOutcome } from '../common/user-outcome.js';
             error
         };
     }
+    /**
+   * Refuses under `useStrictMocks()`, or warns once otherwise, a call that gives a handler fewer arguments than it
+   * declares when `invoke` builds none for it, as for a reaction given without its `ReactionEvent`.
+   */ checkArgumentCount(controller, methodName, method, first, given) {
+        if (first instanceof BaseInteraction || first instanceof Message || method.length <= given) return;
+        const reaction = getReactionHandlers(controller.prototype).some((handler)=>handler.method === methodName);
+        const problem = `${controller.name}.${methodName} takes ${method.length} arguments, and invoke was given ${given}: ` + (reaction ? 'pass its ReactionEvent after the reaction, as { user, action }.' : 'pass each argument it takes.');
+        if (strictMocks()) throw new Error(problem);
+        const key = `${controller.name}.${methodName}`;
+        if (this.warnedArgumentCounts.has(key)) return;
+        this.warnedArgumentCounts.add(key);
+        new Logger('TestingModule').warn(problem);
+    }
     /** Counts `call` as under way until it settles. */ track(call) {
         this.calls.add(call);
         void call.then(()=>this.calls.delete(call), ()=>this.calls.delete(call));
@@ -343,6 +385,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,
@@ -360,6 +404,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
         return this.dispatcher;
     }
     async dispatch(input, options) {
+        this.warnIfClosed();
         await this.init();
         this.registerClient(input);
         const dispatcher = this.dispatcherOf();
@@ -377,6 +422,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
             unhandled: (error)=>unhandled.push(error)
         };
         if (options) {
+            noteReactionDispatch(input);
             await this.track(dispatcher.reaction(input, {
                 user: options.user,
                 action: options.action ?? ReactionHandlerAction.ADD
@@ -406,15 +452,20 @@ import { isUserOutcome } from '../common/user-outcome.js';
         };
     }
     /**
-   * Emits a client event to the module's `@On` and `@Once` handlers, through the same pipeline the app
-   * runs them in: the global guards of the module's `app`, then each handler's own. Handlers on the
-   * module's controllers, class providers and their dependencies all receive it. A `@Once` handler
-   * handles only the first event, as it would on a client.
+   * Emits a client event to the module's `@On` and `@Once` handlers, through the pipeline the app runs
+   * them in up to its event fallback: the global guards of the module's `app`, then each handler's own.
+   * Handlers on the module's controllers, class providers and their dependencies all receive it. A
+   * `@Once` handler handles only the first event, as it would on a client.
+   *
+   * The bot's event fallback doesn't run here. On a bot, a guard's `GuardDeniedError` is logged and the
+   * event skipped, and a handler's `UserError` is logged and, when the event carries a message, answered
+   * as a reply to it; here both reject `emit` as any error does, so a test checks them with `rejects`.
    *
    * @param event - The client event, such as `'guildMemberAdd'`.
    * @param args - The event's arguments, typed from discord.js's `ClientEvents`.
-   * @returns How many handlers ran. Rejects once every handler has settled if any threw: with that
-   *   error when one handler failed, or an `AggregateError` of them when several did.
+   * @returns How many handlers ran. Rejects once every handler has settled if any threw, a guard's
+   *   `GuardDeniedError` and a handler's `UserError` included: with that error when one handler failed,
+   *   or an `AggregateError` of them when several did.
    *
    * @example
    * ```ts
@@ -426,6 +477,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * expect(ran).toBe(1)
    * ```
    */ async emit(event, ...args) {
+        this.warnIfClosed();
         await this.init();
         const calls = [];
         for (const cls of this.eventClasses){
@@ -470,7 +522,10 @@ import { isUserOutcome } from '../common/user-outcome.js';
         this.appWarnUnanswered = appWarnUnanswered;
         this.services = services;
         this.shutdownTimeout = shutdownTimeout;
+        /** The `onReady` hooks' pass, which `close()` waits for, less one whose `onReady` called `close()`. */ this.readyPass = new ReadyPass();
+        this.warnedClosed = false;
         /** The `@Once` handlers that have already handled their event, as a client forgets its once listeners. */ this.firedOnce = new Set();
+        /** The handlers already warned about for being given fewer arguments than they take, so each is named once. */ this.warnedArgumentCounts = new Set();
         /** The calls under way, each removed once it settles: what `close()` lets finish before the cooldown store stops. */ this.calls = new Set();
     }
 }
@@ -509,7 +564,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.
@@ -535,6 +590,10 @@ import { isUserOutcome } from '../common/user-outcome.js';
     /**
    * Replaces a guard with a stub wherever it applies, globally or on a controller or handler.
    *
+   * It stands in for the guard wherever the guard is bound, a provider of the same token included, and wins over an
+   * `overrideProvider` of it. The stub needs a `canActivate`, its own or its prototype's: `compile()` refuses one without
+   * it under `useStrictMocks()`, and otherwise warns.
+   *
    * @param guard - The guard class to replace.
    * @example
    * ```ts
@@ -552,6 +611,10 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * Replaces an interceptor with a stub wherever it applies, globally or on a controller or handler.
    * The stub's `intercept` receives the context and `next`; call `next.handle()` to run the handler.
    *
+   * It stands in for the interceptor wherever it is bound, a provider of the same token included, and wins over an
+   * `overrideProvider` of it. A stub without `intercept` is refused by `compile()` under `useStrictMocks()`, and
+   * otherwise warned about.
+   *
    * @param interceptor - The interceptor class to replace.
    * @example
    * ```ts
@@ -569,6 +632,10 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * Replaces an exception filter with a stub wherever it applies. The filter's `@Catch` still decides
    * which errors reach the stub.
    *
+   * It stands in for the filter wherever it is bound, a provider of the same token included, and wins over an
+   * `overrideProvider` of it. A stub without `catch` is refused by `compile()` under `useStrictMocks()`, and otherwise
+   * warned about.
+   *
    * @param filter - The filter class to replace.
    * @example
    * ```ts
@@ -657,199 +724,271 @@ 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);
+                // A stage override stands in for its class wherever the class is bound. A stage also provided takes the stub in
+                // place of its provider, one binding per token, and runs lifecycle hooks as that provider would; any other is
+                // bound on its own below, as the bot never makes a lifecycle unit of it. A stub that can't run is named here
+                const stageStubs = new Map();
+                for (const [method, overrides, kind] of [
+                    [
+                        'canActivate',
+                        this.guardOverrides,
+                        'overrideGuard'
+                    ],
+                    [
+                        'intercept',
+                        this.interceptorOverrides,
+                        'overrideInterceptor'
+                    ],
+                    [
+                        'catch',
+                        this.filterOverrides,
+                        'overrideFilter'
+                    ]
+                ]){
+                    for (const [stage, stub] of overrides){
+                        if (providers.has(stage)) providers.set(stage, {
+                            provide: stage,
+                            useValue: stub
+                        });
+                        else stageStubs.set(stage, stub);
+                        if (typeof stub[method] === 'function') continue;
+                        const problem = `${kind}(${stage.name}).useValue(…) has no ${method} method.`;
+                        if (strictMocks()) startupError(new Error(problem));
+                        else warnOnce(new Logger('TestingModule'), `${problem} A call that reaches ${stage.name} fails; useStrictMocks() refuses it here.`);
+                    }
+                }
+                // 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 appPresenterClass = this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.presenter;
+                const startup = startupClasses({
+                    controllers: this.options.controllers ?? [],
+                    services,
+                    providers,
+                    stages,
+                    presenter: appPresenterClass,
+                    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() }.');
+                    });
+                }
+                // A stage override nothing provides, bound before the classes so none of them binds the stage itself
+                for (const [stage, stub] of stageStubs)container.bind(stage).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);
+                // What the stages and presenter inject, as the bot makes it; a stage the test replaced contributes nothing
+                const stageServices = stageDependencies(startup, providers, appPresenterClass);
+                for (const service of stageServices)bindClass(service);
+                // 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,
+                    ...stageServices,
+                    ...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);
+                // And each instance with the module that made it, as another module made from the same classes stamps them again
+                recordInstanceContainers(container, [
+                    ...this.options.controllers ?? [],
+                    ...startup.classes
+                ]);
+                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 +1026,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.
@@ -895,7 +1034,15 @@ import { isUserOutcome } from '../common/user-outcome.js';
    * @param options - The controllers, providers, observers and app the module is built from.
    * @returns The builder, to override what the test replaces before `compile()`.
    */ static create(options) {
-        return new TestingModuleBuilder(options);
+        // A controller listed twice is one controller, as the bot and fromApp take it
+        return new TestingModuleBuilder({
+            ...options,
+            ...options.controllers && {
+                controllers: [
+                    ...new Set(options.controllers)
+                ]
+            }
+        });
     }
     /**
    * Starts building a testing module from a whole `@MeoCord` app, wired as the bot wires it.