jest-mock

What is jest-mock?

The jest-mock package is a module for mocking classes and objects in JavaScript tests. It is part of the Jest testing framework but can be used independently. It allows developers to create mock functions, spy on function calls, and set return values or implementations for testing purposes.

What are jest-mock's main functionalities?

Creating Mock Functions

This feature allows you to create a mock function that can track calls, arguments, and return values. It can be used to test how a function is used without actually executing its logic.

const mockFn = jest.fn();

Mocking Return Values

With this feature, you can set a default return value for a mock function. This is useful when you want to test the behavior of code that depends on the return value of the function being mocked.

const mockFn = jest.fn().mockReturnValue('default value');

Mocking Modules

This feature allows you to mock entire modules, which is particularly useful when you want to isolate the module being tested from its dependencies.

jest.mock('moduleName', () => { return jest.fn(() => 'mocked module') });

Spying on Methods

Spying on methods enables you to observe and track calls to object methods without affecting their actual implementation. This is useful for verifying that methods are called with the correct arguments.

const spy = jest.spyOn(object, 'methodName');

Other packages similar to jest-mock

sinon

Sinon is a standalone test spies, stubs, and mocks library for JavaScript. It provides similar functionalities to jest-mock, such as spying on functions, creating stubs, and mocking objects. Sinon can be used with any testing framework and is not tied to Jest.

proxyquire

Proxyquire is a tool for mocking modules in Node.js. It allows you to override dependencies during testing, which is similar to jest-mock's module mocking capabilities. However, proxyquire focuses specifically on Node.js module system and does not provide function mocking or spying.

testdouble

Testdouble.js (td.js) is a minimal test double library for TDD with JavaScript. It provides a similar API to jest-mock for creating test doubles like stubs, mocks, and spies. Testdouble.js aims to have a simpler and more expressive syntax compared to other mocking libraries.

README

jest-mock

API

generateFromMetadata(metadata)

Generates a mock based on the given metadata (Metadata for the mock in the schema returned by the getMetadata method of this module). Mocks treat functions specially, and all mock functions have additional members, described in the documentation for getMockFunction in this module.

One important note: function prototypes are handled specially by this mocking framework. For functions with prototypes, when called as a constructor, the mock will install mocked function members on the instance. This allows different instances of the same constructor to have different values for its mocks member and its return values.

getMetadata(component)

Inspects the argument and returns its schema in the following recursive format:

{
  type: ...
  members : {}
}

Where type is one of array, object, function, or ref, and members is an optional dictionary where the keys are member names and the values are metadata objects. Function prototypes are defined simply by defining metadata for the member.prototype of the function. The type of a function prototype should always be object. For instance, a simple class might be defined like this:

{
  type: 'function',
  members: {
    staticMethod: {type: 'function'},
    prototype: {
      type: 'object',
      members: {
        instanceMethod: {type: 'function'}
      }
    }
  }
}

Metadata may also contain references to other objects defined within the same metadata object. The metadata for the referent must be marked with refID key and an arbitrary value. The referrer must be marked with a ref key that has the same value as object with refID that it refers to. For instance, this metadata blob:

{
  type: 'object',
  refID: 1,
  members: {
    self: {ref: 1}
  }
}

defines an object with a slot named self that refers back to the object.

getMockFunction

Generates a stand-alone function with members that help drive unit tests or confirm expectations. Specifically, functions returned by this method have the following members:

.mock

An object with two members, calls, and instances, which are both lists. The items in the calls list are the arguments with which the function was called. The "instances" list stores the value of 'this' for each call to the function. This is useful for retrieving instances from a constructor.

.mockReturnValueOnce(value)

Pushes the given value onto a FIFO queue of return values for the function.

.mockReturnValue(value)

Sets the default return value for the function.

.mockImplementationOnce(function)

Pushes the given mock implementation onto a FIFO queue of mock implementations for the function.

.mockImplementation(function)

Sets the default mock implementation for the function.

.mockReturnThis()

Syntactic sugar for .mockImplementation(function() {return this;})

In case both mockImplementationOnce()/mockImplementation() and mockReturnValueOnce()/mockReturnValue() are called. The priority of which to use is based on what is the last call:

• if the last call is mockReturnValueOnce() or mockReturnValue(), use the specific return value or default return value. If specific return values are used up or no default return value is set, fall back to try mockImplementation();
• if the last call is mockImplementationOnce() or mockImplementation(), run the specific implementation and return the result or run default implementation and return the result.

Changelog

jest 16.0.0

• Previously failed tests are now always run first.
• A new concurrent reporter shows currently running tests, a test summary, a progress bar and estimated remaining time if possible.
• Improved CLI colors.
• jest <pattern> is now case-insensitive.
• Added it.only, it.skip, test.only, test.skip and xtest.
• Added --testNamePattern=pattern or -t <pattern> to run individual tests in test files.
• Jest now warns for duplicate mock files.
• Pressing a, o, p, q or enter while tests are running in the watch mode, the test run will be interrupted.
• --bail now works together with --watch.
• Added test.concurrent for concurrent async tests.
• Jest now automatically considers files and tests with the .jsx extension.
• Added jest.clearAllMocks to clear all mocks manually.
• Rewrote Jest's snapshot implementation. jest-snapshot can now be more easily integrated into other test runners and used in other projects.
• This requires most snapshots to be updated when upgrading Jest.
• Objects and Arrays in snapshots are now printed with a trailing comma.
• Function names are not printed in snapshots any longer to reduce issues with code coverage instrumentation and different Node versions.
• Snapshots are now sorted using natural sort order.
• Snapshots are not marked as obsolete any longer when using fit or when an error is thrown in a test.
• Finished migration of Jasmine matchers to the new Jest matchers.
• Pretty print toHaveBeenLastCalledWith, toHaveBeenCalledWith, lastCalledWith and toBeCalledWith failure messages.
• Added toBeInstanceOf matcher.
• Added toContainEqual matcher.
• Added toThrowErrorMatchingSnapshot matcher.
• Improved moduleNameMapper resolution.
• Module registry fixes.
• Fixed invocation of the setupTestFrameworkScriptFile script to make it easier to use chai together with Jest.
• Removed react-native special case in Jest's configuration.
• Added --findRelatedTests <fileA> <fileB> cli option to run tests related to the specified files.
• Added jest.deepUnmock to babel-plugin-jest-hoist.
• Added jest.runTimersToTime which is useful together with fake timers.
• Improved automated mocks for ES modules compiled with babel.