meocord 4.1.2 → 4.2.1

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,15 +24,90 @@
  */ 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));
+/**
+ * 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`.
+ *
+ * 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 === mocks.runnerFactory) return;
+    if ([
+        ...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 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 refusal();
+    }
+    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);
+    mocks.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
@@ -45,7 +120,7 @@ const collected = new FinalizationRegistry((ref)=>created.delete(ref));
  * @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.
@@ -68,18 +143,33 @@ 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 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
+        mocks.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
  * 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
@@ -97,6 +187,15 @@ const collected = new FinalizationRegistry((ref)=>created.delete(ref));
  * @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);
+            mocks.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.
@@ -106,9 +205,20 @@ const collected = new FinalizationRegistry((ref)=>created.delete(ref));
     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 {
@@ -119,10 +229,36 @@ const collected = new FinalizationRegistry((ref)=>created.delete(ref));
             } 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({
@@ -150,6 +286,18 @@ const collected = new FinalizationRegistry((ref)=>created.delete(ref));
             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
@@ -186,16 +334,22 @@ const collected = new FinalizationRegistry((ref)=>created.delete(ref));
         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;
@@ -209,10 +363,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, usesRunnerMockFn };