meocord 4.2.0 → 4.2.2

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 };