{"id":12787,"library":"a","title":"A Mocking Framework","description":"The `a` package provides a versatile mocking framework for JavaScript and TypeScript, designed to be used with any testing framework. It is currently stable at version 4.0.8, with recent updates including the addition of comprehensive TypeScript types in v4.0.7, indicating an active development cadence. Key differentiators include its ability to create both partial mocks (which fall back to the original function) and strict mocks (which throw on unexpected calls), alongside detailed argument expectation, advanced matching for arrays and objects, and control over repeat behaviors. This allows for precise control over test doubles, supporting TDD and BDD methodologies in unit testing scenarios. The framework provides flexible options for stubbing and verification of function calls.","status":"active","version":"4.0.8","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/alfateam/a","tags":["javascript","mock","mocking","partial mock","strict mock","tdd","bdd","test runner","stub","typescript"],"install":[{"cmd":"npm install a","lang":"bash","label":"npm"},{"cmd":"yarn add a","lang":"bash","label":"yarn"},{"cmd":"pnpm add a","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary mocking utility is the default export of the 'a' package.","wrong":"import { a } from 'a';","symbol":"a","correct":"import a from 'a';"},{"note":"To get type information for functions returned by `a.mock()`, import `MockedFunction` as a type.","wrong":"import { MockedFunction } from 'a';","symbol":"MockedFunction","correct":"import type { MockedFunction } from 'a';"},{"note":"For CommonJS modules, use `require()` to import the library. Direct ESM imports might fail in older Node.js environments without transpilation or `\"type\": \"module\"`.","wrong":"import a from 'a'; // in CommonJS environments","symbol":"a (CommonJS)","correct":"const a = require('a');"}],"quickstart":{"code":"import a from 'a';\n\n// Example 1: Strict mock with argument expectation and repeat controls\nconst strictMock = a.mock();\nstrictMock.expect('firstArg').return('First Value').repeat(1);\nstrictMock.expect('secondArg', 123).return('Second Value').repeatAny();\n\nconsole.log('Strict Mock Call 1 (firstArg):', strictMock('firstArg')); // Should return 'First Value'\n// The next call with 'firstArg' would throw an error as its repeat(1) is exhausted.\n\nconsole.log('Strict Mock Call 2 (secondArg):', strictMock('secondArg', 123)); // Returns 'Second Value'\nconsole.log('Strict Mock Call 3 (secondArg):', strictMock('secondArg', 123)); // Returns 'Second Value' indefinitely\n\ntry {\n  strictMock('unexpected'); // This will throw an error: 'unexpected arguments'\n} catch (e: any) {\n  console.error('Strict Mock Error:', e.message);\n}\n\n// Example 2: Partial mock, falling back to original function\nfunction originalFunction(input: string) {\n  return `Original says: ${input}`;\n}\n\nconst partialMock = a.mock(originalFunction);\npartialMock.expect('mockedInput').return('Mocked Override!');\n\nconsole.log('Partial Mock Call 1 (mocked):', partialMock('mockedInput')); // Returns 'Mocked Override!'\nconsole.log('Partial Mock Call 2 (not mocked):', partialMock('any other input')); // Calls original: 'Original says: any other input'","lang":"typescript","description":"Demonstrates creating strict and partial mocks, expecting arguments, controlling call repeats, and handling unexpected calls."},"warnings":[{"fix":"Always define expectations for all possible call patterns or use `mock.ignoreAll().return(...)` for a wildcard match, or `repeatAny()` for infinite repeats.","message":"Strict mocks throw an `unexpected arguments` error if called with arguments that do not match any configured expectation, or if all expected calls for a specific argument set have been exhausted (unless `repeatAny()` is used).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure that your expected object or array exactly matches the structure and values of the input you anticipate, or use `ignore()` for specific arguments if their value doesn't matter.","message":"When expecting objects or arrays, the `expect()` method performs a strict comparison. For objects, all leaf properties must match exactly. An empty object expectation (`expect({})`) will not match a non-empty actual object.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If a mock expectation should be valid indefinitely, explicitly chain `.repeatAny()` to it. Otherwise, ensure your test logic does not call the mock more times than expected.","message":"The `repeat(N)` method configures an expectation to be valid for exactly `N` calls. After `N` calls, subsequent matching calls will result in an `unexpected arguments` error, unless `repeatAny()` is used.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Review the mock's `expect()` configurations. Ensure all valid call patterns are defined, or use `repeatAny()` if calls should be infinite. If it's a strict mock, ensure only expected arguments are passed.","cause":"A strict mock was called with arguments that do not match any defined expectation, or a repeated expectation was called more times than specified.","error":"Error: unexpected arguments"},{"fix":"Verify that `a` is imported as the default export (`import a from 'a';` for ESM or `const a = require('a');` for CommonJS). Check your `package.json` for `\"type\": \"module\"` if using ESM.","cause":"The `a` object was imported incorrectly, or `a` is `undefined` because of an environment issue (e.g., trying to use ESM `import` in a pure CommonJS file without proper Node.js configuration).","error":"TypeError: a.mock is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}