{"id":14406,"library":"a_mock","title":"a_mock Mocking Framework","description":"a_mock is a focused JavaScript mocking framework designed to be used with any JavaScript testing framework. It enables the creation of both partial and strict mocks, offering granular control over function behavior for testing purposes. Developers can define specific expectations for arguments (single, multiple, arrays, and complex objects), specify return values, configure exceptions to be thrown, and manage call repetition. The library provides capabilities for ignoring arguments or entire calls when precision isn't necessary. It is currently at version 2.0.5 and includes TypeScript type definitions, facilitating its use in TypeScript projects. While a_mock emphasizes explicit expectation setup and strict argument matching, particularly for object arguments, its core utility lies in providing a clear, declarative API for creating test doubles without imposing a specific test runner or assertion library. The release cadence for a_mock is not explicitly detailed in the provided documentation, but it presents as a stable, utility-focused library for fundamental mocking scenarios.","status":"active","version":"2.0.5","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/alfateam/a_mock","tags":["javascript","mock","mocking","partial mock","strict mock","tdd","stub","stubbing","mock require","typescript"],"install":[{"cmd":"npm install a_mock","lang":"bash","label":"npm"},{"cmd":"yarn add a_mock","lang":"bash","label":"yarn"},{"cmd":"pnpm add a_mock","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For modern JavaScript modules (ESM), import the `mock` factory function as a named export.","wrong":"import aMock from 'a_mock';","symbol":"mock","correct":"import { mock } from 'a_mock';"},{"note":"For CommonJS environments, access the `mock` factory function directly as a property of the module export.","wrong":"const mockFactory = require('a_mock');","symbol":"mock","correct":"const mockFactory = require('a_mock').mock;"},{"note":"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`).","wrong":"import { MockInstance } from 'a_mock';","symbol":"MockInstance","correct":"import type { MockInstance } from 'a_mock';"}],"quickstart":{"code":"import { mock } from 'a_mock';\n\n// Minimal declaration for a_mock to satisfy TypeScript for quickstart\n// In a real project, these types would be automatically available from 'a_mock'\ndeclare module 'a_mock' {\n    interface MockExpectation {\n        return(value: any): MockExpectation;\n        throw(error: Error): MockExpectation;\n        repeat(count: number): MockExpectation;\n        repeatAny(): MockExpectation;\n        whenCalled(callback: (...args: any[]) => any): MockExpectation;\n    }\n\n    interface MockInstance extends Function {\n        expect(...args: any[]): MockExpectation;\n        ignore(): MockInstance;\n        ignoreAll(): { return(value: any): MockExpectation; };\n    }\n\n    function mock(originalFunction?: Function): MockInstance;\n}\n\n// Mocking a function that expects multiple arguments\nconst myMock = mock();\n\nmyMock.expect('firstArg1', 'secondArg1').return('fake1');\nmyMock.expect('firstArg2', 'secondArg2').return('fake2');\n\nconsole.log('Call 1:', myMock('firstArg1', 'secondArg1')); // Expected: fake1\nconsole.log('Call 2:', myMock('firstArg2', 'secondArg2')); // Expected: fake2\n\ntry {\n  myMock('foo');\n} catch (e: any) {\n  console.error(\"Error on single arg call:\", e.message); // Expected: throws unexpected arguments\n}\n\ntry {\n  myMock('foo', 'bar');\n} catch (e: any) {\n  console.error(\"Error on unexpected args:\", e.message); // Expected: throws unexpected arguments\n}\n\n// Demonstrate a partial mock\nconst originalAdder = (a: number, b: number) => `Original sum: ${a + b}`;\nconst partialAdderMock = mock(originalAdder);\n\npartialAdderMock.expect(10, 20).return('Mocked 10+20');\n\nconsole.log('Partial mock call 1:', partialAdderMock(10, 20)); // Expected: Mocked 10+20\nconsole.log('Partial mock call 2:', partialAdderMock(5, 5));   // Expected: Original sum: 10 (falls back)","lang":"typescript","description":"Demonstrates creating both strict and partial mocks, showing how to define expected arguments, handle multiple calls, and observe strict matching behavior with unexpected inputs."},"warnings":[{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"A strict mock was called with arguments that do not match any active `expect()` criteria, or all predefined expectations have already been consumed.","error":"throws unexpected arguments"},{"fix":"Verify that the object passed to the mock call precisely matches the structure and leaf property values defined in the `mock.expect({ ... })` call.","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.","error":"throws unexpected arguments cause leaf properties are not equal"},{"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.","cause":"The mock was specifically configured using `mock.expect().throw(errorInstance)` to throw a particular error for the current call.","error":"Error: invalid operation"}],"ecosystem":"npm"}