meocord 4.2.0 → 4.2.1

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

@@ -6,7 +6,7 @@ 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 { 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';
@@ -23,13 +23,13 @@ import { messageCommandHooks } from '../core/message-params.js';
 import { appObservers, assertObservers, bindObservers } from '../core/observer-runner.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';
@@ -38,6 +38,9 @@ import { declaredErrorsOf, collectStartupErrors, startupError, stopOnStartupErro
 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';
 
@@ -110,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;
@@ -125,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.
    *
@@ -145,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,
@@ -166,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);
@@ -181,6 +202,8 @@ import { isUserOutcome } from '../common/user-outcome.js';
         }, [], {
             resolveFailed: failed,
             hookFailed: failed
+        }, {
+            runOnReady: this.readyPass.runOnReady
         });
         throwFailures('onReady', failures);
     }
@@ -252,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
@@ -274,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\`.`);
@@ -303,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;
@@ -319,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));
@@ -364,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();
@@ -381,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
@@ -410,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
@@ -430,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){
@@ -474,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();
     }
 }
@@ -539,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
@@ -556,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
@@ -573,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
@@ -705,6 +768,39 @@ import { isUserOutcome } from '../common/user-outcome.js';
                 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 ?? [];
@@ -716,12 +812,13 @@ import { isUserOutcome } from '../common/user-outcome.js';
                 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: this.options.app && Reflect.getMetadata(META.appOptions, this.options.app)?.presenter,
+                    presenter: appPresenterClass,
                     cooldownStore: store,
                     themeFor: stages?.themeFor?.resolvers,
                     observers: [
@@ -752,16 +849,8 @@ import { isUserOutcome } from '../common/user-outcome.js';
                         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);
-                }
+                // 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
@@ -835,6 +924,9 @@ import { isUserOutcome } from '../common/user-outcome.js';
                 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, [
@@ -843,6 +935,7 @@ import { isUserOutcome } from '../common/user-outcome.js';
                     ] : [],
                     ...providers.keys(),
                     ...services,
+                    ...stageServices,
                     ...themeResolver ? [
                         themeResolver
                     ] : [],
@@ -863,6 +956,11 @@ import { isUserOutcome } from '../common/user-outcome.js';
                     ...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 ?? [], {
@@ -936,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.

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

@@ -1,7 +1,7 @@
+import { shared } from '../util/shared-state.util.js';
+
 // Framework-agnostic mock function, so `meocord/testing` depends on neither jest nor vitest.
 // Both detect it through `_isMockFunction` and read `fn.mock.calls` in their assertions.
-// Each call signature of `T`, up to four, as a union: `Parameters` and `ReturnType` read only an overloaded function's
-// last signature, such as the list form of a manager's `fetch`
 /**
  * Tells whether a value is a mock function: one from `meocord/testing`, `jest.fn()` or `vi.fn()`.
  *
@@ -24,13 +24,20 @@
  */ function isMockFunction(fn) {
     return typeof fn === 'function' && '_isMockFunction' in fn && fn._isMockFunction === true;
 }
-// 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();
+/**
+ * What `useMockFn` set and the mocks made, kept for both builds of this meocord version, so a setup file in one module
+ * format sets them for specs in the other:
+ * - `invocationOrder`: when each call of meocord's own mocks came, across all of them, as Vitest numbers its own;
+ * - `created`: every mock createMockFn made, held weakly so the mocks of a finished test can still be collected;
+ * - `runnerFactory` and `restoreImpl`: 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.
+ */ const mocks = shared('mocks', ()=>({
+        invocationOrder: 0,
+        created: new Set(),
+        runnerFactory: undefined,
+        restoreImpl: new WeakMap()
+    }));
+const collected = new FinalizationRegistry((ref)=>mocks.created.delete(ref));
 /**
  * Makes every mock `meocord/testing` creates with the test runner's own mock function, such as Vitest's `vi.fn`.
  *
@@ -61,26 +68,36 @@ const restoreImpl = new WeakMap();
  * @category Mocks
  * @see {@link createMockFn}
  */ function useMockFn(factory) {
-    if (factory === runnerFactory) return;
+    if (factory === mocks.runnerFactory) return;
     if ([
-        ...created
+        ...mocks.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 refusal = (cause)=>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.', cause === undefined ? undefined : {
+            cause
+        });
+    let probe;
+    try {
+        probe = factory();
+    } catch (error) {
+        // node:test's mock.fn, given on its own, throws for want of its tracker
+        throw refusal(error);
+    }
     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.');
+        throw refusal();
     }
-    runnerFactory = factory;
+    mocks.runnerFactory = factory;
 }
+/** Whether mocks are made with a runner's function, which {@link useMockFn} registered. */ const usesRunnerMockFn = ()=>mocks.runnerFactory !== undefined;
 /** Tracks a mock for clearAllMocks and resetAllMocks. */ function track(mockFn) {
     const ref = new WeakRef(mockFn);
-    created.add(ref);
+    mocks.created.add(ref);
     collected.register(mockFn, ref);
     return mockFn;
 }
@@ -103,7 +120,7 @@ const restoreImpl = new WeakMap();
  * @category Mocks
  * @see {@link resetAllMocks}
  */ function clearAllMocks() {
-    for (const ref of created)ref.deref()?.mockClear();
+    for (const ref of mocks.created)ref.deref()?.mockClear();
 }
 /**
  * Clears every mock from `meocord/testing`, and puts each back to the implementation it was created with.
@@ -126,12 +143,12 @@ const restoreImpl = new WeakMap();
  * @category Mocks
  * @see {@link clearAllMocks}
  */ function resetAllMocks() {
-    for (const ref of created){
+    for (const ref of mocks.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)?.();
+        mocks.restoreImpl.get(mockFn)?.();
     }
 }
 /**
@@ -145,6 +162,14 @@ const restoreImpl = new WeakMap();
  * `mockReturnValue`, `mockResolvedValue`, `mockRejectedValue` and `mockImplementation` share one implementation, so
  * the last one set wins. The `*Once` variants queue, and run first, in the order they were set.
  *
+ * It records what Vitest's `toHaveResolved` and `toHaveBeenCalledBefore` read as well. Its call order is counted
+ * across meocord's own mocks, apart from the runner's, so compare the order of two of meocord's mocks, or of two of the
+ * runner's, not one of each.
+ *
+ * A promise the implementation returns is handed back as one that settles the same way, not as the same object: test
+ * it with `toEqual`, `toHaveReturnedWith` or by awaiting it, not with `toBe`. A property set on the given promise, such
+ * as a `cancel` method, isn't carried over.
+ *
  * @param impl - The implementation to run until another is set.
  *
  * @example
@@ -162,11 +187,12 @@ const restoreImpl = new WeakMap();
  * @category Mocks
  * @see {@link MockInstance}
  */ function createMockFn(impl) {
+    const { runnerFactory } = mocks;
     if (runnerFactory) {
         const runnerMock = runnerFactory(impl);
         if (impl) {
             const setImpl = runnerMock.mockImplementation.bind(runnerMock);
-            restoreImpl.set(runnerMock, ()=>setImpl(impl));
+            mocks.restoreImpl.set(runnerMock, ()=>setImpl(impl));
         }
         return track(runnerMock);
     }
@@ -179,9 +205,20 @@ const restoreImpl = new WeakMap();
     const calls = [];
     const results = [];
     const instances = [];
+    const settledResults = [];
+    const invocationCallOrder = [];
+    const contexts = [];
     const mockFn = function(...args) {
         calls.push(args);
         instances.push(this);
+        contexts.push(this);
+        invocationCallOrder.push(++mocks.invocationOrder);
+        // Updated in place as the call settles, so a promise's outcome shows once it resolves or rejects
+        const settled = {
+            type: 'incomplete',
+            value: undefined
+        };
+        settledResults.push(settled);
         let type = 'return';
         let value;
         try {
@@ -192,10 +229,36 @@ const restoreImpl = new WeakMap();
             } else {
                 value = undefined;
             }
+            if (value instanceof Promise) {
+                // Returned in its place, so a rejection nobody awaits stays unhandled in the test, as it is on a bot: a handler
+                // on the implementation's own promise would mark it handled
+                value = value.then((resolved)=>{
+                    Object.assign(settled, {
+                        type: 'fulfilled',
+                        value: resolved
+                    });
+                    return resolved;
+                }, (rejected)=>{
+                    Object.assign(settled, {
+                        type: 'rejected',
+                        value: rejected
+                    });
+                    throw rejected;
+                });
+            } else {
+                Object.assign(settled, {
+                    type: 'fulfilled',
+                    value
+                });
+            }
             return value;
         } catch (err) {
             type = 'throw';
             value = err;
+            Object.assign(settled, {
+                type: 'rejected',
+                value: err
+            });
             throw err;
         } finally{
             results.push({
@@ -223,6 +286,18 @@ const restoreImpl = new WeakMap();
             return calls.length > 0 ? calls[calls.length - 1] : undefined;
         }
     };
+    // Out of the mock's keys, so a test comparing `mock` as a whole sees the shape it always had
+    Object.defineProperties(mock, {
+        settledResults: {
+            get: ()=>settledResults
+        },
+        invocationCallOrder: {
+            get: ()=>invocationCallOrder
+        },
+        contexts: {
+            get: ()=>contexts
+        }
+    });
     Object.defineProperty(mockFn, 'mock', {
         value: mock,
         enumerable: false
@@ -259,16 +334,22 @@ const restoreImpl = new WeakMap();
         onceQueue.push(fn);
         return mockFn;
     };
+    const forgetCalls = ()=>{
+        for (const record of [
+            calls,
+            results,
+            instances,
+            settledResults,
+            invocationCallOrder,
+            contexts
+        ])record.length = 0;
+    };
     mockFn.mockClear = ()=>{
-        calls.length = 0;
-        results.length = 0;
-        instances.length = 0;
+        forgetCalls();
         return mockFn;
     };
     mockFn.mockReset = ()=>{
-        calls.length = 0;
-        results.length = 0;
-        instances.length = 0;
+        forgetCalls();
         onceQueue = [];
         currentImpl = impl;
         return mockFn;
@@ -285,4 +366,4 @@ const restoreImpl = new WeakMap();
     return track(mockFn);
 }
 
-export { clearAllMocks, createMockFn, isMockFunction, resetAllMocks, useMockFn };
+export { clearAllMocks, createMockFn, isMockFunction, resetAllMocks, useMockFn, usesRunnerMockFn };