a_mock Mocking Framework

Common errors

• throws unexpected arguments

  cause A strict mock was called with arguments that do not match any active `expect()` criteria, or all predefined expectations have already been consumed.
  fix Add an `expect()` clause for the specific arguments being used, configure the expectation with `repeatAny()`, or use `ignore()` / `ignoreAll()` if argument matching is not necessary for that call path.

• throws unexpected arguments cause leaf properties are not equal

  cause A mock expectation was set for an object (struct), but the object provided during the mock call did not have exactly matching leaf properties or values as defined in the expectation.
  fix Verify that the object passed to the mock call precisely matches the structure and leaf property values defined in the `mock.expect({ ... })` call.

• Error: invalid operation

  cause The mock was specifically configured using `mock.expect().throw(errorInstance)` to throw a particular error for the current call.
  fix This is expected behavior as per the mock's configuration. If unintended, review and remove or reconfigure the `throw()` expectation in your test setup.

Warnings

• gotcha Strict mocks (created without an original function) will throw an 'unexpected arguments' error if called with any arguments that do not precisely match a predefined expectation, or if called after all expectations have been consumed.
  Fix: Ensure all anticipated call paths are covered by `expect()` calls, or utilize `repeatAny()` for indefinitely repeatable expectations. For calls where argument specifics are not critical, consider using `ignore()` or `ignoreAll()`.
• gotcha When matching objects (referred to as 'structs' in the documentation), `a_mock` performs strict equality checks exclusively on *leaf properties*. This means an empty object expectation `{}` will not match any non-empty object provided, and all leaf property values in the actual object must exactly match those in the expected struct for a successful match.
  Fix: Design mock expectations with precise leaf property values for object arguments. If exact object matching is not required, consider using argument ignoring functions like `ignore()` or `ignoreAll()`.
• gotcha Expectations are consumed sequentially in the order they are defined. Once an `expect()` call is met and it's not configured with `repeatAny()`, that expectation is removed. Subsequent calls made after all expectations have been consumed will result in an 'unexpected arguments' error.
  Fix: Carefully plan the order of your `expect()` calls. For expectations that should be matched multiple times, use `repeat(count)` or `repeatAny()`. For partial mocks, ensure that any unmatched arguments should genuinely fall back to the original function.

Install

• npm install a_mock npm
• yarn add a_mock yarn
• pnpm add a_mock pnpm

Imports

• mock
  wrong:

  import aMock from 'a_mock';

  correct:

  import { mock } from 'a_mock';

  For modern JavaScript modules (ESM), import the `mock` factory function as a named export.
• mock
  wrong:

  const mockFactory = require('a_mock');

  correct:

  const mockFactory = require('a_mock').mock;

  For CommonJS environments, access the `mock` factory function directly as a property of the module export.
• MockInstance
  wrong:

  import { MockInstance } from 'a_mock';

  correct:

  import type { MockInstance } from 'a_mock';

  Used for TypeScript type annotations when working with the mock object created by the `mock()` factory function. The exact type name might vary (e.g., `Mock` or `AMock`).

Quickstart

Demonstrates creating both strict and partial mocks, showing how to define expected arguments, handle multiple calls, and observe strict matching behavior with unexpected inputs.

import { mock } from 'a_mock';

// Minimal declaration for a_mock to satisfy TypeScript for quickstart
// In a real project, these types would be automatically available from 'a_mock'
declare module 'a_mock' {
    interface MockExpectation {
        return(value: any): MockExpectation;
        throw(error: Error): MockExpectation;
        repeat(count: number): MockExpectation;
        repeatAny(): MockExpectation;
        whenCalled(callback: (...args: any[]) => any): MockExpectation;
    }

    interface MockInstance extends Function {
        expect(...args: any[]): MockExpectation;
        ignore(): MockInstance;
        ignoreAll(): { return(value: any): MockExpectation; };
    }

    function mock(originalFunction?: Function): MockInstance;
}

// Mocking a function that expects multiple arguments
const myMock = mock();

myMock.expect('firstArg1', 'secondArg1').return('fake1');
myMock.expect('firstArg2', 'secondArg2').return('fake2');

console.log('Call 1:', myMock('firstArg1', 'secondArg1')); // Expected: fake1
console.log('Call 2:', myMock('firstArg2', 'secondArg2')); // Expected: fake2

try {
  myMock('foo');
} catch (e: any) {
  console.error("Error on single arg call:", e.message); // Expected: throws unexpected arguments
}

try {
  myMock('foo', 'bar');
} catch (e: any) {
  console.error("Error on unexpected args:", e.message); // Expected: throws unexpected arguments
}

// Demonstrate a partial mock
const originalAdder = (a: number, b: number) => `Original sum: ${a + b}`;
const partialAdderMock = mock(originalAdder);

partialAdderMock.expect(10, 20).return('Mocked 10+20');

console.log('Partial mock call 1:', partialAdderMock(10, 20)); // Expected: Mocked 10+20
console.log('Partial mock call 2:', partialAdderMock(5, 5));   // Expected: Original sum: 10 (falls back)