fetch-mock

What is fetch-mock?

fetch-mock is a library for mocking HTTP requests made using the Fetch API. It allows developers to simulate different responses and behaviors for fetch calls, which is particularly useful for testing and development purposes.

What are fetch-mock's main functionalities?

Mocking a simple GET request

This feature allows you to mock a simple GET request. The code sample demonstrates how to mock a GET request to 'https://api.example.com/data' and return a JSON object with sample data.

const fetchMock = require('fetch-mock');
fetchMock.get('https://api.example.com/data', { data: 'sample data' });

fetch('https://api.example.com/data')
  .then(response => response.json())
  .then(data => console.log(data));

Mocking a POST request with specific body

This feature allows you to mock a POST request with a specific request body. The code sample demonstrates how to mock a POST request to 'https://api.example.com/submit' and return different responses based on the request body.

const fetchMock = require('fetch-mock');
fetchMock.post('https://api.example.com/submit', (url, options) => {
  if (options.body === JSON.stringify({ key: 'value' })) {
    return { status: 'success' };
  } else {
    return { status: 'error' };
  }
});

fetch('https://api.example.com/submit', {
  method: 'POST',
  body: JSON.stringify({ key: 'value' })
})
  .then(response => response.json())
  .then(data => console.log(data));

Mocking with delay

This feature allows you to mock a request with a delay. The code sample demonstrates how to mock a GET request to 'https://api.example.com/delayed' and return a response after a 1-second delay.

const fetchMock = require('fetch-mock');
fetchMock.get('https://api.example.com/delayed', new Promise(resolve => setTimeout(() => resolve({ data: 'delayed data' }), 1000)));

fetch('https://api.example.com/delayed')
  .then(response => response.json())
  .then(data => console.log(data));

Mocking with different response statuses

This feature allows you to mock requests with different HTTP response statuses. The code sample demonstrates how to mock a GET request to 'https://api.example.com/not-found' and return a 404 status.

const fetchMock = require('fetch-mock');
fetchMock.get('https://api.example.com/not-found', 404);

fetch('https://api.example.com/not-found')
  .then(response => {
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    return response.json();
  })
  .catch(error => console.error('Fetch error:', error));

Other packages similar to fetch-mock

nock

Nock is a HTTP mocking and expectations library for Node.js. It intercepts HTTP requests and allows you to define custom responses. Compared to fetch-mock, Nock is more focused on Node.js and works with any HTTP library, not just fetch.

msw

Mock Service Worker (MSW) is a library for mocking network requests in both browser and Node.js environments. It uses Service Workers to intercept requests in the browser, making it more versatile for front-end testing compared to fetch-mock.

axios-mock-adapter

Axios Mock Adapter is a library specifically designed for mocking requests made with the Axios HTTP client. It provides a simple API for defining request handlers and responses. While fetch-mock is designed for the Fetch API, axios-mock-adapter is tailored for Axios.

README

fetch-mock

Mock http requests made using fetch (or isomorphic-fetch). As well as shorthand methods for the simplest use cases, it offers a flexible API for customising all aspects of mocking behaviour.

Installation and usage

npm install fetch-mock then require('fetch-mock') in most environments.

Troubleshooting and alternative installation, V4 changelog

Basic usage

require('fetch-mock') exports a singleton with the following methods

mock(matcher, response) or mock(matcher, method, response)

Replaces fetch() with a stub which records its calls, grouped by route, and optionally returns a mocked Response object or passes the call through to fetch(). Calls to .mock() can be chained.

• matcher [required]: Condition for selecting which requests to mock Accepts any of the following
  • string: Either an exact url to match e.g. 'http://www.site.com/page.html' or, if the string begins with a ^, the string following the ^ must begin the url e.g. '^http://www.site.com' would match 'http://www.site.com' or 'http://www.site.com/page.html'
  • RegExp: A regular expression to test the url against
  • Function(url, opts): A function (returning a Boolean) that is passed the url and opts fetch() is called with (or, if fetch() was called with one, the Request instance)
• method [optional]: only matches requests using this http method
• response [required]: Configures the http response returned by the mock. Can take any of the following values (or be a Promise for any of them, enabling full control when testing race conditions etc.)
  • number: Creates a response with this status
  • string: Creates a 200 response with the string as the response body
  • object: As long as the object does not contain any of the properties below it is converted into a json string and returned as the body of a 200 response. If any of the properties below are defined it is used to configure a Response object
    • body: Set the response body (string or object)
    • status: Set the response status (defaut 200)
    • headers: Set the response headers. (object)
    • throws: If this property is present then a Promise rejected with the value of throws is returned
    • sendAsJson: This property determines whether or not the request body should be JSON.stringified before being sent (defaults to true).
  • Function(url, opts): A function that is passed the url and opts fetch() is called with and that returns any of the responses listed above (or a Promise for any of them)

restore()

Restores fetch() to its unstubbed state and clears all data recorded for its calls

reMock()

Calls restore() internally then calls mock(). This allows you to put some generic calls to mock() in a beforeEach() while retaining the flexibility to vary the responses for some tests. reMock() can be chained.

reset()

Clears all data recorded for fetch()'s calls

Note that restore(), reMock() and reset() are all bound to fetchMock, and can be used directly as callbacks e.g. afterEach(fetchMock.restore) will work just fine. There is no need for afterEach(function () {fetchMock.restore()})

For the methods below matcherName, if given, should be either the name of a route (see advanced usage below) or equal to matcher.toString() for any unnamed route

calls(matcherName)

Returns an object {matched: [], unmatched: []} containing arrays of all calls to fetch, grouped by whether fetch-mock matched them or not. If matcherName is specified then only calls to fetch matching that route are returned.

called(matcherName)

Returns a Boolean indicating whether fetch was called and a route was matched. If matcherName is specified it only returns true if that particular route was matched.

lastCall(matcherName)

Returns the arguments for the last matched call to fetch

lastUrl(matcherName)

Returns the url for the last matched call to fetch

lastOptions(matcherName)

Returns the options for the last matched call to fetch

Example

fetchMock
	.mock('http://domain1', 200)
	.mock('http://domain2', 'PUT', {
		affectedRecords: 1
	});

myModule.onlyCallDomain2()
	.then(() => {
		expect(fetchMock.called('http://domain2')).to.be.true;
		expect(fetchMock.called('http://domain1')).to.be.false;
		expect(fetchMock.calls().unmatched.length).to.equal(0);
		expect(JSON.parse(fetchMock.lastUrl('http://domain2'))).to.equal('http://domain2/endpoint');
		expect(JSON.parse(fetchMock.lastOptions('http://domain2').body)).to.deep.equal({prop: 'val'});
	})
	.then(fetchMock.restore)

Advanced usage

mock(routeConfig)

Use a configuration object to define a route to mock.

• name [optional]: A unique string naming the route. Used to subsequently retrieve references to the calls, grouped by name. If not specified defaults to matcher.toString() Note: If a non-unique name is provided no error will be thrown (because names are optional, so auto-generated ones may legitimately clash)
• method [optional]: http method
• matcher [required]: as specified above
• response [required]: as specified above

mock(routes)

Pass in an array of route configuration objects

mock(config)

Pass in an object containing more complex config for fine grained control over every aspect of mocking behaviour. May have the following properties

• routes: Either a single route config object or an array of them (see above).
• greed: Determines how the mock handles unmatched requests
  • 'none': all unmatched calls get passed through to fetch()
  • 'bad': all unmatched calls result in a rejected promise
  • 'good': all unmatched calls result in a resolved promise with a 200 status

deprecated useNonGlobalFetch(func)

When using isomorphic-fetch or node-fetch ideally fetch should be added as a global. If not possible to do so you can still use fetch-mock in combination with mockery or similar in nodejs. To use fetch-mock with with mockery you may use this function to prevent fetch-mock trying to mock the function globally.

• func Optional reference to fetch (or any other function you may want to substitute for fetch in your tests). This will probably have zero effect on your tests unless you are deliberately using the greed: 'none' config option to let some requests pass through to the original fetch implementation

Troubleshooting and alternative installation

fetch is assigned to a local variable, not a global

First of all, consider whether you could just use fetch as a global. Here are 3 reasons why this is a good idea:

• The fetch standard defines it as a global (and in some cases it won't work unless bound to window), so to write isomorphic code it's probably best to stick to this pattern
• isomorphic-fetch takes care of installing it as a global in nodejs or the browser, so there's no effort on your part to do so.
• fetch-mock is primarily designed to work with fetch as a global and your experience of using it will be far more straightforward if you follow this pattern

Still not convinced?

In that case fetchMock.fetchMock (or [deprecated] call getMock()) gives you access to the mock implementation of fetch which you can pass in to a mock loading library such as mockery

Mockery example

var fetch = require('node-fetch');
var fetchMock = require('fetch-mock');
var mockery = require('mockery');

it('should make a request', function (done) {
	mockery.registerMock('node-fetch', fetchMock.fetchMock);
	fetchMock.mock('http://domain.com/', 200)
	const myModule = require('./src/my-mod'); // this module requires node-fetch and assigns to a variable
	// test code goes in here
	mockery.deregisterMock('fetch');
	done();
});

fetch doesn't seem to be getting mocked?

If using a mock loading library such as mockery, are you requiring the module you're testing after registering fetch-mock with the mock loader? You probably should be (Example incorrect usage). If you're using ES6 import it may not be possible to do this without reverting to using require() sometimes. I did warn you about not using fetch as a global (...sigh)

Environment doesn't support requiring fetch-mock?

• If your client-side code or tests do not use a loader that respects the browser field of package.json use require('fetch-mock/es5/client').
• If you need to use fetch-mock without commonjs, you can include the precompiled node_modules/fetch-mock/es5/client-browserified.js in a script tag. This loads fetch-mock into the fetchMock global variable.
• For server side tests running in nodejs 0.12 or lower use require('fetch-mock/es5/server')

Matching Request objects in node fails

In node, if using npm at a version less than 2 the Request constructor used by fetch-mock won't necessarily be the same as the one used by isomorphic-fetch. To fix this upgrade to npm@3.

Polyfilling fetch

• In nodejs require('isomorphic-fetch') before any of your tests.
• In the browser require('isomorphic-fetch') can also be used, but it may be easier to npm install whatwg-fetch (the module isomorphic-fetch is built around) and load ./node_modules/whatwg-fetch/fetch.js directly into the page, either in a script tag or by referencing it your test runner config.
• When using karma-webpack it's best not to use the webpack.ProvidePlugin for this. Instead just add node_modules/whatwg-fetch/fetch.js to your list of files to include, or require it directly into your tests before requiring fetch-mock.

V4 changelog

• registerRoute() and unregisterRoute() have been removed to simplify the API. Since V3, calls to .mock() can be chained, so persisting routes over a series of tests can easily be achieved by means of a beforeEach or helper e.g.

beforeEach(() => {
	fetchMock
		.mock('http://auth.service.com/user', 200)
		.mock('http://mvt.service.com/session', {test1: true, test2: false})
});

afterEach(() => {
	fetchMock.restore();
});

it('should be possible to augment persistent set of routes', () => {
	fetchMock.mock('http://content.service.com/contentid', {content: 'blah blah'})
	page.init();
	expect(fetchMock.called('http://content.service.com/contentid')).to.be.true;
});

• Defining two routes with the same name will no longer throw an error (previous implementation was buggy anyway)
• Added lastCall(), lastUrl() and lastOptions() utilities