@goast/kotlin 0.4.4-beta2 → 0.4.5

package/script/deps/jsr.io/@std/testing/1.0.5/mock.js

@@ -0,0 +1,1102 @@
+"use strict";
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockError = void 0;
+exports.mockSession = mockSession;
+exports.mockSessionAsync = mockSessionAsync;
+exports.restore = restore;
+exports.spy = spy;
+exports.stub = stub;
+exports.assertSpyCalls = assertSpyCalls;
+exports.assertSpyCall = assertSpyCall;
+exports.assertSpyCallAsync = assertSpyCallAsync;
+exports.assertSpyCallArg = assertSpyCallArg;
+exports.assertSpyCallArgs = assertSpyCallArgs;
+exports.returnsThis = returnsThis;
+exports.returnsArg = returnsArg;
+exports.returnsArgs = returnsArgs;
+exports.returnsNext = returnsNext;
+exports.resolvesNext = resolvesNext;
+const tslib_1 = require("tslib");
+/** A mocking and spying library.
+ *
+ * Test spies are function stand-ins that are used to assert if a function's
+ * internal behavior matches expectations. Test spies on methods keep the original
+ * behavior but allow you to test how the method is called and what it returns.
+ * Test stubs are an extension of test spies that also replaces the original
+ * methods behavior.
+ *
+ * ## Spying
+ *
+ * Say we have two functions, `square` and `multiply`, if we want to assert that
+ * the `multiply` function is called during execution of the `square` function we
+ * need a way to spy on the `multiply` function. There are a few ways to achieve
+ * this with Spies, one is to have the `square` function take the `multiply`
+ * multiply as a parameter.
+ *
+ * This way, we can call `square(multiply, value)` in the application code or wrap
+ * a spy function around the `multiply` function and call
+ * `square(multiplySpy, value)` in the testing code.
+ *
+ * ```ts
+ * import {
+ *   assertSpyCall,
+ *   assertSpyCalls,
+ *   spy,
+ * } from "@std/testing/mock";
+ * import { assertEquals } from "@std/assert";
+ *
+ * function multiply(a: number, b: number): number {
+ *   return a * b;
+ * }
+ *
+ * function square(
+ *   multiplyFn: (a: number, b: number) => number,
+ *   value: number,
+ * ): number {
+ *   return multiplyFn(value, value);
+ * }
+ *
+ * Deno.test("square calls multiply and returns results", () => {
+ *   const multiplySpy = spy(multiply);
+ *
+ *   assertEquals(square(multiplySpy, 5), 25);
+ *
+ *   // asserts that multiplySpy was called at least once and details about the first call.
+ *   assertSpyCall(multiplySpy, 0, {
+ *     args: [5, 5],
+ *     returned: 25,
+ *   });
+ *
+ *   // asserts that multiplySpy was only called once.
+ *   assertSpyCalls(multiplySpy, 1);
+ * });
+ * ```
+ *
+ * If you prefer not adding additional parameters for testing purposes only, you
+ * can use spy to wrap a method on an object instead. In the following example, the
+ * exported `_internals` object has the `multiply` function we want to call as a
+ * method and the `square` function calls `_internals.multiply` instead of
+ * `multiply`.
+ *
+ * This way, we can call `square(value)` in both the application code and testing
+ * code. Then spy on the `multiply` method on the `_internals` object in the
+ * testing code to be able to spy on how the `square` function calls the `multiply`
+ * function.
+ *
+ * ```ts
+ * import {
+ *   assertSpyCall,
+ *   assertSpyCalls,
+ *   spy,
+ * } from "@std/testing/mock";
+ * import { assertEquals } from "@std/assert";
+ *
+ * function multiply(a: number, b: number): number {
+ *   return a * b;
+ * }
+ *
+ * function square(value: number): number {
+ *   return _internals.multiply(value, value);
+ * }
+ *
+ * const _internals = { multiply };
+ *
+ * Deno.test("square calls multiply and returns results", () => {
+ *   const multiplySpy = spy(_internals, "multiply");
+ *
+ *   try {
+ *     assertEquals(square(5), 25);
+ *   } finally {
+ *     // unwraps the multiply method on the _internals object
+ *     multiplySpy.restore();
+ *   }
+ *
+ *   // asserts that multiplySpy was called at least once and details about the first call.
+ *   assertSpyCall(multiplySpy, 0, {
+ *     args: [5, 5],
+ *     returned: 25,
+ *   });
+ *
+ *   // asserts that multiplySpy was only called once.
+ *   assertSpyCalls(multiplySpy, 1);
+ * });
+ * ```
+ *
+ * One difference you may have noticed between these two examples is that in the
+ * second we call the `restore` method on `multiplySpy` function. That is needed to
+ * remove the spy wrapper from the `_internals` object's `multiply` method. The
+ * `restore` method is called in a finally block to ensure that it is restored
+ * whether or not the assertion in the try block is successful. The `restore`
+ * method didn't need to be called in the first example because the `multiply`
+ * function was not modified in any way like the `_internals` object was in the
+ * second example.
+ *
+ * Method spys are disposable, meaning that you can have them automatically restore
+ * themselves with the `using` keyword. Using this approach is cleaner because you
+ * do not need to wrap your assertions in a try statement to ensure you restore the
+ * methods before the tests finish.
+ *
+ * ```ts
+ * import {
+ *   assertSpyCall,
+ *   assertSpyCalls,
+ *   spy,
+ * } from "@std/testing/mock";
+ * import { assertEquals } from "@std/assert";
+ *
+ * function multiply(a: number, b: number): number {
+ *   return a * b;
+ * }
+ *
+ * function square(value: number): number {
+ *   return _internals.multiply(value, value);
+ * }
+ *
+ * const _internals = { multiply };
+ *
+ * Deno.test("square calls multiply and returns results", () => {
+ *   using multiplySpy = spy(_internals, "multiply");
+ *
+ *   assertEquals(square(5), 25);
+ *
+ *   // asserts that multiplySpy was called at least once and details about the first call.
+ *   assertSpyCall(multiplySpy, 0, {
+ *     args: [5, 5],
+ *     returned: 25,
+ *   });
+ *
+ *   // asserts that multiplySpy was only called once.
+ *   assertSpyCalls(multiplySpy, 1);
+ * });
+ * ```
+ *
+ * ## Stubbing
+ *
+ * Say we have two functions, `randomMultiple` and `randomInt`, if we want to
+ * assert that `randomInt` is called during execution of `randomMultiple` we need a
+ * way to spy on the `randomInt` function. That could be done with either of the
+ * spying techniques previously mentioned. To be able to verify that the
+ * `randomMultiple` function returns the value we expect it to for what `randomInt`
+ * returns, the easiest way would be to replace the `randomInt` function's behavior
+ * with more predictable behavior.
+ *
+ * You could use the first spying technique to do that but that would require
+ * adding a `randomInt` parameter to the `randomMultiple` function.
+ *
+ * You could also use the second spying technique to do that, but your assertions
+ * would not be as predictable due to the `randomInt` function returning random
+ * values.
+ *
+ * Say we want to verify it returns correct values for both negative and positive
+ * random integers. We could easily do that with stubbing. The below example is
+ * similar to the second spying technique example but instead of passing the call
+ * through to the original `randomInt` function, we are going to replace
+ * `randomInt` with a function that returns pre-defined values.
+ *
+ * The mock module includes some helper functions to make creating common stubs
+ * easy. The `returnsNext` function takes an array of values we want it to return
+ * on consecutive calls.
+ *
+ * ```ts
+ * import {
+ *   assertSpyCall,
+ *   assertSpyCalls,
+ *   returnsNext,
+ *   stub,
+ * } from "@std/testing/mock";
+ * import { assertEquals } from "@std/assert";
+ *
+ * function randomInt(lowerBound: number, upperBound: number): number {
+ *   return lowerBound + Math.floor(Math.random() * (upperBound - lowerBound));
+ * }
+ *
+ * function randomMultiple(value: number): number {
+ *   return value * _internals.randomInt(-10, 10);
+ * }
+ *
+ * const _internals = { randomInt };
+ *
+ * Deno.test("randomMultiple uses randomInt to generate random multiples between -10 and 10 times the value", () => {
+ *   const randomIntStub = stub(_internals, "randomInt", returnsNext([-3, 3]));
+ *
+ *   try {
+ *     assertEquals(randomMultiple(5), -15);
+ *     assertEquals(randomMultiple(5), 15);
+ *   } finally {
+ *     // unwraps the randomInt method on the _internals object
+ *     randomIntStub.restore();
+ *   }
+ *
+ *   // asserts that randomIntStub was called at least once and details about the first call.
+ *   assertSpyCall(randomIntStub, 0, {
+ *     args: [-10, 10],
+ *     returned: -3,
+ *   });
+ *   // asserts that randomIntStub was called at least twice and details about the second call.
+ *   assertSpyCall(randomIntStub, 1, {
+ *     args: [-10, 10],
+ *     returned: 3,
+ *   });
+ *
+ *   // asserts that randomIntStub was only called twice.
+ *   assertSpyCalls(randomIntStub, 2);
+ * });
+ * ```
+ *
+ * Like method spys, stubs are disposable, meaning that you can have them automatically
+ * restore themselves with the `using` keyword. Using this approach is cleaner because
+ * you do not need to wrap your assertions in a try statement to ensure you restore the
+ * methods before the tests finish.
+ *
+ * ```ts
+ * import {
+ *   assertSpyCall,
+ *   assertSpyCalls,
+ *   returnsNext,
+ *   stub,
+ * } from "@std/testing/mock";
+ * import { assertEquals } from "@std/assert";
+ *
+ * function randomInt(lowerBound: number, upperBound: number): number {
+ *   return lowerBound + Math.floor(Math.random() * (upperBound - lowerBound));
+ * }
+ *
+ * function randomMultiple(value: number): number {
+ *   return value * _internals.randomInt(-10, 10);
+ * }
+ *
+ * const _internals = { randomInt };
+ *
+ * Deno.test("randomMultiple uses randomInt to generate random multiples between -10 and 10 times the value", () => {
+ *   using randomIntStub = stub(_internals, "randomInt", returnsNext([-3, 3]));
+ *
+ *   assertEquals(randomMultiple(5), -15);
+ *   assertEquals(randomMultiple(5), 15);
+ *
+ *   // asserts that randomIntStub was called at least once and details about the first call.
+ *   assertSpyCall(randomIntStub, 0, {
+ *     args: [-10, 10],
+ *     returned: -3,
+ *   });
+ *   // asserts that randomIntStub was called at least twice and details about the second call.
+ *   assertSpyCall(randomIntStub, 1, {
+ *     args: [-10, 10],
+ *     returned: 3,
+ *   });
+ *
+ *   // asserts that randomIntStub was only called twice.
+ *   assertSpyCalls(randomIntStub, 2);
+ * });
+ * ```
+ *
+ * ## Faking time
+ *
+ * Say we have a function that has time based behavior that we would like to test.
+ * With real time, that could cause tests to take much longer than they should. If
+ * you fake time, you could simulate how your function would behave over time
+ * starting from any point in time. Below is an example where we want to test that
+ * the callback is called every second.
+ *
+ * With `FakeTime` we can do that. When the `FakeTime` instance is created, it
+ * splits from real time. The `Date`, `setTimeout`, `clearTimeout`, `setInterval`
+ * and `clearInterval` globals are replaced with versions that use the fake time
+ * until real time is restored. You can control how time ticks forward with the
+ * `tick` method on the `FakeTime` instance.
+ *
+ * ```ts
+ * import {
+ *   assertSpyCalls,
+ *   spy,
+ * } from "@std/testing/mock";
+ * import { FakeTime } from "@std/testing/time";
+ *
+ * function secondInterval(cb: () => void): number {
+ *   return setInterval(cb, 1000);
+ * }
+ *
+ * Deno.test("secondInterval calls callback every second and stops after being cleared", () => {
+ *   using time = new FakeTime();
+ *
+ *   const cb = spy();
+ *   const intervalId = secondInterval(cb);
+ *   assertSpyCalls(cb, 0);
+ *   time.tick(500);
+ *   assertSpyCalls(cb, 0);
+ *   time.tick(500);
+ *   assertSpyCalls(cb, 1);
+ *   time.tick(3500);
+ *   assertSpyCalls(cb, 4);
+ *
+ *   clearInterval(intervalId);
+ *   time.tick(1000);
+ *   assertSpyCalls(cb, 4);
+ * });
+ * ```
+ *
+ * @module
+ */
+const equals_js_1 = require("../../assert/1.0.8/equals.js");
+const is_error_js_1 = require("../../assert/1.0.8/is_error.js");
+const rejects_js_1 = require("../../assert/1.0.8/rejects.js");
+const assertion_error_js_1 = require("../../assert/1.0.8/assertion_error.js");
+const _mock_utils_js_1 = require("./_mock_utils.js");
+/**
+ * An error related to spying on a function or instance method.
+ *
+ * @example Usage
+ * ```ts
+ * import { MockError, spy } from "@std/testing/mock";
+ * import { assertThrows } from "@std/assert";
+ *
+ * assertThrows(() => {
+ *   spy({} as any, "no-such-method");
+ * }, MockError);
+ * ```
+ */
+class MockError extends Error {
+    /**
+     * Construct MockError
+     *
+     * @param message The error message.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "MockError";
+    }
+}
+exports.MockError = MockError;
+/** Wraps a function with a Spy. */
+function functionSpy(func) {
+    const original = func !== null && func !== void 0 ? func : (() => { });
+    const calls = [];
+    const spy = function (...args) {
+        const call = { args };
+        if (this)
+            call.self = this;
+        try {
+            call.returned = original.apply(this, args);
+        }
+        catch (error) {
+            call.error = error;
+            calls.push(call);
+            throw error;
+        }
+        calls.push(call);
+        return call.returned;
+    };
+    Object.defineProperties(spy, {
+        original: {
+            enumerable: true,
+            value: original,
+        },
+        calls: {
+            enumerable: true,
+            value: calls,
+        },
+        restored: {
+            enumerable: true,
+            get: () => false,
+        },
+        restore: {
+            enumerable: true,
+            value: () => {
+                throw new MockError("Cannot restore: function cannot be restored");
+            },
+        },
+    });
+    return spy;
+}
+function mockSession(func) {
+    if (func) {
+        return function (...args) {
+            const id = _mock_utils_js_1.sessions.length;
+            _mock_utils_js_1.sessions.push(new Set());
+            try {
+                return func.apply(this, args);
+            }
+            finally {
+                restore(id);
+            }
+        };
+    }
+    else {
+        _mock_utils_js_1.sessions.push(new Set());
+        return _mock_utils_js_1.sessions.length - 1;
+    }
+}
+/**
+ * Creates an async session that tracks all mocks created before the promise resolves.
+ *
+ * @example Usage
+ * ```ts
+ * import { mockSessionAsync, restore, stub } from "@std/testing/mock";
+ * import { assertEquals, assertNotEquals } from "@std/assert";
+ *
+ * const setTimeout = globalThis.setTimeout;
+ * const session = mockSessionAsync(async () => {
+ *   stub(globalThis, "setTimeout");
+ *   assertNotEquals(globalThis.setTimeout, setTimeout);
+ * });
+ *
+ * await session();
+ *
+ * assertEquals(globalThis.setTimeout, setTimeout); // stub is restored
+ * ```
+ * @typeParam Self The self type of the function.
+ * @typeParam Args The arguments type of the function.
+ * @typeParam Return The return type of the function.
+ * @param func The function.
+ * @returns The return value of the function.
+ */
+function mockSessionAsync(func) {
+    return async function (...args) {
+        const id = _mock_utils_js_1.sessions.length;
+        _mock_utils_js_1.sessions.push(new Set());
+        try {
+            return await func.apply(this, args);
+        }
+        finally {
+            restore(id);
+        }
+    };
+}
+/**
+ * Restores all mocks registered in the current session that have not already been restored.
+ * If an id is provided, it will restore all mocks registered in the session associed with that id that have not already been restored.
+ *
+ * @example Usage
+ * ```ts
+ * import { mockSession, restore, stub } from "@std/testing/mock";
+ * import { assertEquals, assertNotEquals } from "@std/assert";
+ *
+ * const setTimeout = globalThis.setTimeout;
+ *
+ * stub(globalThis, "setTimeout");
+ *
+ * assertNotEquals(globalThis.setTimeout, setTimeout);
+ *
+ * restore();
+ *
+ * assertEquals(globalThis.setTimeout, setTimeout);
+ * ```
+ *
+ * @param id The id of the session to restore. If not provided, all mocks registered in the current session are restored.
+ */
+function restore(id) {
+    id !== null && id !== void 0 ? id : (id = (_mock_utils_js_1.sessions.length || 1) - 1);
+    while (id < _mock_utils_js_1.sessions.length) {
+        const session = _mock_utils_js_1.sessions.pop();
+        if (session) {
+            for (const value of session) {
+                value.restore();
+            }
+        }
+    }
+}
+/** Wraps an instance method with a Spy. */
+function methodSpy(self, property) {
+    var _a, _b;
+    if (typeof self[property] !== "function") {
+        throw new MockError("Cannot spy: property is not an instance method");
+    }
+    if ((0, _mock_utils_js_1.isSpy)(self[property])) {
+        throw new MockError("Cannot spy: already spying on instance method");
+    }
+    const propertyDescriptor = Object.getOwnPropertyDescriptor(self, property);
+    if (propertyDescriptor && !propertyDescriptor.configurable) {
+        throw new MockError("Cannot spy: non-configurable instance method");
+    }
+    const original = self[property];
+    const calls = [];
+    let restored = false;
+    const spy = function (...args) {
+        const call = { args };
+        if (this)
+            call.self = this;
+        try {
+            call.returned = original.apply(this, args);
+        }
+        catch (error) {
+            call.error = error;
+            calls.push(call);
+            throw error;
+        }
+        calls.push(call);
+        return call.returned;
+    };
+    Object.defineProperties(spy, {
+        original: {
+            enumerable: true,
+            value: original,
+        },
+        calls: {
+            enumerable: true,
+            value: calls,
+        },
+        restored: {
+            enumerable: true,
+            get: () => restored,
+        },
+        restore: {
+            enumerable: true,
+            value: () => {
+                if (restored) {
+                    throw new MockError("Cannot restore: instance method already restored");
+                }
+                if (propertyDescriptor) {
+                    Object.defineProperty(self, property, propertyDescriptor);
+                }
+                else {
+                    delete self[property];
+                }
+                restored = true;
+                (0, _mock_utils_js_1.unregisterMock)(spy);
+            },
+        },
+        [Symbol.dispose]: {
+            value: () => {
+                spy.restore();
+            },
+        },
+    });
+    Object.defineProperty(self, property, {
+        configurable: true,
+        enumerable: (_a = propertyDescriptor === null || propertyDescriptor === void 0 ? void 0 : propertyDescriptor.enumerable) !== null && _a !== void 0 ? _a : false,
+        writable: (_b = propertyDescriptor === null || propertyDescriptor === void 0 ? void 0 : propertyDescriptor.writable) !== null && _b !== void 0 ? _b : false,
+        value: spy,
+    });
+    (0, _mock_utils_js_1.registerMock)(spy);
+    return spy;
+}
+/** Wraps a constructor with a Spy. */
+function constructorSpy(constructor) {
+    var _a;
+    const original = constructor;
+    const calls = [];
+    // @ts-ignore TS2509: Can't know the type of `original` statically.
+    const spy = (_a = class extends original {
+            // deno-lint-ignore constructor-super
+            constructor(...args) {
+                const call = { args };
+                try {
+                    super(...args);
+                    call.returned = this;
+                }
+                catch (error) {
+                    call.error = error;
+                    calls.push(call);
+                    throw error;
+                }
+                calls.push(call);
+            }
+            static restore() {
+                throw new MockError("Cannot restore: constructor cannot be restored");
+            }
+        },
+        tslib_1.__setFunctionName(_a, "spy"),
+        Object.defineProperty(_a, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: original.name
+        }),
+        Object.defineProperty(_a, "original", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: original
+        }),
+        Object.defineProperty(_a, "calls", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: calls
+        }),
+        Object.defineProperty(_a, "restored", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        }),
+        _a);
+    return spy;
+}
+function spy(funcOrConstOrSelf, property) {
+    if (!funcOrConstOrSelf) {
+        return functionSpy();
+    }
+    else if (property !== undefined) {
+        return methodSpy(funcOrConstOrSelf, property);
+    }
+    else if (funcOrConstOrSelf.toString().startsWith("class")) {
+        return constructorSpy(funcOrConstOrSelf);
+    }
+    else {
+        return functionSpy(funcOrConstOrSelf);
+    }
+}
+function stub(self, property, func) {
+    var _a, _b;
+    if (self[property] !== undefined && typeof self[property] !== "function") {
+        throw new MockError("Cannot stub: property is not an instance method");
+    }
+    if ((0, _mock_utils_js_1.isSpy)(self[property])) {
+        throw new MockError("Cannot stub: already spying on instance method");
+    }
+    const propertyDescriptor = Object.getOwnPropertyDescriptor(self, property);
+    if (propertyDescriptor && !propertyDescriptor.configurable) {
+        throw new MockError("Cannot stub: non-configurable instance method");
+    }
+    const fake = func !== null && func !== void 0 ? func : (() => { });
+    const original = self[property];
+    const calls = [];
+    let restored = false;
+    const stub = function (...args) {
+        const call = { args };
+        if (this)
+            call.self = this;
+        try {
+            call.returned = fake.apply(this, args);
+        }
+        catch (error) {
+            call.error = error;
+            calls.push(call);
+            throw error;
+        }
+        calls.push(call);
+        return call.returned;
+    };
+    Object.defineProperties(stub, {
+        original: {
+            enumerable: true,
+            value: original,
+        },
+        fake: {
+            enumerable: true,
+            value: fake,
+        },
+        calls: {
+            enumerable: true,
+            value: calls,
+        },
+        restored: {
+            enumerable: true,
+            get: () => restored,
+        },
+        restore: {
+            enumerable: true,
+            value: () => {
+                if (restored) {
+                    throw new MockError("Cannot restore: instance method already restored");
+                }
+                if (propertyDescriptor) {
+                    Object.defineProperty(self, property, propertyDescriptor);
+                }
+                else {
+                    delete self[property];
+                }
+                restored = true;
+                (0, _mock_utils_js_1.unregisterMock)(stub);
+            },
+        },
+        [Symbol.dispose]: {
+            value: () => {
+                stub.restore();
+            },
+        },
+    });
+    Object.defineProperty(self, property, {
+        configurable: true,
+        enumerable: (_a = propertyDescriptor === null || propertyDescriptor === void 0 ? void 0 : propertyDescriptor.enumerable) !== null && _a !== void 0 ? _a : false,
+        writable: (_b = propertyDescriptor === null || propertyDescriptor === void 0 ? void 0 : propertyDescriptor.writable) !== null && _b !== void 0 ? _b : false,
+        value: stub,
+    });
+    (0, _mock_utils_js_1.registerMock)(stub);
+    return stub;
+}
+/**
+ * Asserts that a spy is called as much as expected and no more.
+ *
+ * @example Usage
+ * ```ts
+ * import { assertSpyCalls, spy } from "@std/testing/mock";
+ *
+ * const func = spy();
+ *
+ * func();
+ * func();
+ *
+ * assertSpyCalls(func, 2);
+ * ```
+ *
+ * @typeParam Self The self type of the spy function.
+ * @typeParam Args The arguments type of the spy function.
+ * @typeParam Return The return type of the spy function.
+ * @param spy The spy to check
+ * @param expectedCalls The number of the expected calls.
+ */
+function assertSpyCalls(spy, expectedCalls) {
+    try {
+        (0, equals_js_1.assertEquals)(spy.calls.length, expectedCalls);
+    }
+    catch (e) {
+        (0, is_error_js_1.assertIsError)(e);
+        let message = spy.calls.length < expectedCalls
+            ? "Spy not called as much as expected:\n"
+            : "Spy called more than expected:\n";
+        message += e.message.split("\n").slice(1).join("\n");
+        throw new assertion_error_js_1.AssertionError(message);
+    }
+}
+function getSpyCall(spy, callIndex) {
+    if (spy.calls.length < (callIndex + 1)) {
+        throw new assertion_error_js_1.AssertionError("Spy not called as much as expected");
+    }
+    return spy.calls[callIndex];
+}
+/**
+ * Asserts that a spy is called as expected.
+ *
+ * @example Usage
+ * ```ts
+ * import { assertSpyCall, spy } from "@std/testing/mock";
+ *
+ * const func = spy((a: number, b: number) => a + b);
+ *
+ * func(3, 4);
+ * func(5, 6);
+ *
+ * // asserts each call made to the spy function.
+ * assertSpyCall(func, 0, { args: [3, 4], returned: 7 });
+ * assertSpyCall(func, 1, { args: [5, 6], returned: 11 });
+ * ```
+ *
+ * @typeParam Self The self type of the spy function.
+ * @typeParam Args The arguments type of the spy function.
+ * @typeParam Return The return type of the spy function.
+ * @param spy The spy to check
+ * @param callIndex The index of the call to check
+ * @param expected The expected spy call.
+ */
+function assertSpyCall(spy, callIndex, expected) {
+    var _a, _b;
+    const call = getSpyCall(spy, callIndex);
+    if (expected) {
+        if (expected.args) {
+            try {
+                (0, equals_js_1.assertEquals)(call.args, expected.args);
+            }
+            catch (e) {
+                (0, is_error_js_1.assertIsError)(e);
+                throw new assertion_error_js_1.AssertionError("Spy not called with expected args:\n" +
+                    e.message.split("\n").slice(1).join("\n"));
+            }
+        }
+        if ("self" in expected) {
+            try {
+                (0, equals_js_1.assertEquals)(call.self, expected.self);
+            }
+            catch (e) {
+                (0, is_error_js_1.assertIsError)(e);
+                let message = expected.self
+                    ? "Spy not called as method on expected self:\n"
+                    : "Spy not expected to be called as method on object:\n";
+                message += e.message.split("\n").slice(1).join("\n");
+                throw new assertion_error_js_1.AssertionError(message);
+            }
+        }
+        if ("returned" in expected) {
+            if ("error" in expected) {
+                throw new TypeError("Do not expect error and return, only one should be expected");
+            }
+            if (call.error) {
+                throw new assertion_error_js_1.AssertionError("Spy call did not return expected value, an error was thrown.");
+            }
+            try {
+                (0, equals_js_1.assertEquals)(call.returned, expected.returned);
+            }
+            catch (e) {
+                (0, is_error_js_1.assertIsError)(e);
+                throw new assertion_error_js_1.AssertionError("Spy call did not return expected value:\n" +
+                    e.message.split("\n").slice(1).join("\n"));
+            }
+        }
+        if ("error" in expected) {
+            if ("returned" in call) {
+                throw new assertion_error_js_1.AssertionError("Spy call did not throw an error, a value was returned.");
+            }
+            (0, is_error_js_1.assertIsError)(call.error, (_a = expected.error) === null || _a === void 0 ? void 0 : _a.Class, (_b = expected.error) === null || _b === void 0 ? void 0 : _b.msgIncludes);
+        }
+    }
+}
+/**
+ * Asserts that an async spy is called as expected.
+ *
+ * @example Usage
+ * ```ts
+ * import { assertSpyCallAsync, spy } from "@std/testing/mock";
+ *
+ * const func = spy((a: number, b: number) => new Promise((resolve) => {
+ *   setTimeout(() => resolve(a + b), 100)
+ * }));
+ *
+ * await func(3, 4);
+ * await func(5, 6);
+ *
+ * // asserts each call made to the spy function.
+ * await assertSpyCallAsync(func, 0, { args: [3, 4], returned: 7 });
+ * await assertSpyCallAsync(func, 1, { args: [5, 6], returned: 11 });
+ * ```
+ *
+ * @typeParam Self The self type of the spy function.
+ * @typeParam Args The arguments type of the spy function.
+ * @typeParam Return The return type of the spy function.
+ * @param spy The spy to check
+ * @param callIndex The index of the call to check
+ * @param expected The expected spy call.
+ */
+async function assertSpyCallAsync(spy, callIndex, expected) {
+    var _a, _b, _c, _d;
+    const expectedSync = expected && { ...expected };
+    if (expectedSync) {
+        delete expectedSync.returned;
+        delete expectedSync.error;
+    }
+    assertSpyCall(spy, callIndex, expectedSync);
+    const call = getSpyCall(spy, callIndex);
+    if (call.error) {
+        throw new assertion_error_js_1.AssertionError("Spy call did not return a promise, an error was thrown.");
+    }
+    if (call.returned !== Promise.resolve(call.returned)) {
+        throw new assertion_error_js_1.AssertionError("Spy call did not return a promise, a value was returned.");
+    }
+    if (expected) {
+        if ("returned" in expected) {
+            if ("error" in expected) {
+                throw new TypeError("Do not expect error and return, only one should be expected");
+            }
+            let expectedResolved;
+            try {
+                expectedResolved = await expected.returned;
+            }
+            catch (_e) {
+                throw new TypeError("Do not expect rejected promise, expect error instead");
+            }
+            let resolved;
+            try {
+                resolved = await call.returned;
+            }
+            catch (_f) {
+                throw new assertion_error_js_1.AssertionError("Spy call returned promise was rejected");
+            }
+            try {
+                (0, equals_js_1.assertEquals)(resolved, expectedResolved);
+            }
+            catch (e) {
+                (0, is_error_js_1.assertIsError)(e);
+                throw new assertion_error_js_1.AssertionError("Spy call did not resolve to expected value:\n" +
+                    e.message.split("\n").slice(1).join("\n"));
+            }
+        }
+        if ("error" in expected) {
+            await (0, rejects_js_1.assertRejects)(() => Promise.resolve(call.returned), (_b = (_a = expected.error) === null || _a === void 0 ? void 0 : _a.Class) !== null && _b !== void 0 ? _b : Error, (_d = (_c = expected.error) === null || _c === void 0 ? void 0 : _c.msgIncludes) !== null && _d !== void 0 ? _d : "");
+        }
+    }
+}
+/**
+ * Asserts that a spy is called with a specific arg as expected.
+ *
+ * @example Usage
+ * ```ts
+ * import { assertSpyCallArg, spy } from "@std/testing/mock";
+ *
+ * const func = spy((a: number, b: number) => a + b);
+ *
+ * func(3, 4);
+ * func(5, 6);
+ *
+ * // asserts each call made to the spy function.
+ * assertSpyCallArg(func, 0, 0, 3);
+ * assertSpyCallArg(func, 0, 1, 4);
+ * assertSpyCallArg(func, 1, 0, 5);
+ * assertSpyCallArg(func, 1, 1, 6);
+ * ```
+ *
+ * @typeParam Self The self type of the spy function.
+ * @typeParam Args The arguments type of the spy function.
+ * @typeParam Return The return type of the spy function.
+ * @typeParam ExpectedArg The expected type of the argument for the spy to be called.
+ * @param spy The spy to check.
+ * @param callIndex The index of the call to check.
+ * @param argIndex The index of the arguments to check.
+ * @param expected The expected argument.
+ * @returns The actual argument.
+ */
+function assertSpyCallArg(spy, callIndex, argIndex, expected) {
+    const call = getSpyCall(spy, callIndex);
+    const arg = call === null || call === void 0 ? void 0 : call.args[argIndex];
+    (0, equals_js_1.assertEquals)(arg, expected);
+    return arg;
+}
+function assertSpyCallArgs(spy, callIndex, argsStart, argsEnd, expected) {
+    const call = getSpyCall(spy, callIndex);
+    if (!expected) {
+        expected = argsEnd;
+        argsEnd = undefined;
+    }
+    if (!expected) {
+        expected = argsStart;
+        argsStart = undefined;
+    }
+    const args = typeof argsEnd === "number"
+        ? call.args.slice(argsStart, argsEnd)
+        : typeof argsStart === "number"
+            ? call.args.slice(argsStart)
+            : call.args;
+    (0, equals_js_1.assertEquals)(args, expected);
+    return args;
+}
+/**
+ * Creates a function that returns the instance the method was called on.
+ *
+ * @example Usage
+ * ```ts
+ * import { returnsThis } from "@std/testing/mock";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const func = returnsThis();
+ * const obj = { func };
+ * assertEquals(obj.func(), obj);
+ * ```
+ *
+ * @typeParam Self The self type of the returned function.
+ * @typeParam Args The arguments type of the returned function.
+ * @returns A function that returns the instance the method was called on.
+ */
+function returnsThis() {
+    return function () {
+        return this;
+    };
+}
+/**
+ * Creates a function that returns one of its arguments.
+ *
+ * @example Usage
+ * ```ts
+ * import { returnsArg } from "@std/testing/mock";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const func = returnsArg(1);
+ * assertEquals(func(1, 2, 3), 2);
+ * ```
+ *
+ * @typeParam Arg The type of returned argument.
+ * @typeParam Self The self type of the returned function.
+ * @param idx The index of the arguments to use.
+ * @returns A function that returns one of its arguments.
+ */
+function returnsArg(idx) {
+    return function (...args) {
+        return args[idx];
+    };
+}
+/**
+ * Creates a function that returns its arguments or a subset of them. If end is specified, it will return arguments up to but not including the end.
+ *
+ * @example Usage
+ * ```ts
+ * import { returnsArgs } from "@std/testing/mock";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const func = returnsArgs();
+ * assertEquals(func(1, 2, 3), [1, 2, 3]);
+ * ```
+ *
+ * @typeParam Args The arguments type of the returned function
+ * @typeParam Self The self type of the returned function
+ * @param start The start index of the arguments to return. Default is 0.
+ * @param end The end index of the arguments to return.
+ * @returns A function that returns its arguments or a subset of them.
+ */
+function returnsArgs(start = 0, end) {
+    return function (...args) {
+        return args.slice(start, end);
+    };
+}
+/**
+ * Creates a function that returns the iterable values. Any iterable values that are errors will be thrown.
+ *
+ * @example Usage
+ * ```ts
+ * import { returnsNext } from "@std/testing/mock";
+ * import { assertEquals, assertThrows } from "@std/assert";
+ *
+ * const func = returnsNext([1, 2, new Error("foo"), 3]);
+ * assertEquals(func(), 1);
+ * assertEquals(func(), 2);
+ * assertThrows(() => func(), Error, "foo");
+ * assertEquals(func(), 3);
+ * ```
+ *
+ * @typeParam Return The type of each item of the iterable
+ * @typeParam Self The self type of the returned function
+ * @typeParam Args The arguments type of the returned function
+ * @param values The iterable values
+ * @return A function that returns the iterable values
+ */
+function returnsNext(values) {
+    const gen = (function* returnsValue() {
+        yield* values;
+    })();
+    let calls = 0;
+    return function () {
+        const next = gen.next();
+        if (next.done) {
+            throw new MockError(`Not expected to be called more than ${calls} time(s)`);
+        }
+        calls++;
+        const { value } = next;
+        if (value instanceof Error)
+            throw value;
+        return value;
+    };
+}
+/**
+ * Creates a function that resolves the awaited iterable values. Any awaited iterable values that are errors will be thrown.
+ *
+ * @example Usage
+ * ```ts
+ * import { resolvesNext } from "@std/testing/mock";
+ * import { assertEquals, assertRejects } from "@std/assert";
+ *
+ * const func = resolvesNext([1, 2, new Error("foo"), 3]);
+ * assertEquals(await func(), 1);
+ * assertEquals(await func(), 2);
+ * assertRejects(() => func(), Error, "foo");
+ * assertEquals(await func(), 3);
+ * ```
+ *
+ * @typeParam Return The type of each item of the iterable
+ * @typeParam Self The self type of the returned function
+ * @typeParam Args The type of arguments of the returned function
+ * @param iterable The iterable to use
+ * @returns A function that resolves the awaited iterable values
+ */
+function resolvesNext(iterable) {
+    const gen = (async function* returnsValue() {
+        yield* iterable;
+    })();
+    let calls = 0;
+    return async function () {
+        const next = await gen.next();
+        if (next.done) {
+            throw new MockError(`Not expected to be called more than ${calls} time(s)`);
+        }
+        calls++;
+        const { value } = next;
+        if (value instanceof Error)
+            throw value;
+        return value;
+    };
+}