Skip to content
The unmock javascript and typescript client
Branch: dev
Clone or download
Latest commit 7c57308 Apr 21, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci npm ci Apr 20, 2019
.env.example Bumps version Feb 14, 2019
.gitignore Uses lerna Apr 20, 2019
.npmignore Adds additional api calls to test Dec 27, 2018
.prettierignore Uses lerna Apr 20, 2019
.prettierrc.js Uses lerna Apr 20, 2019 Adds more robust readme Feb 12, 2019 s/unmock/unmock-core/g Apr 20, 2019
jest.config.base.js s/unmock/unmock-core/g Apr 20, 2019
package.json Removes spurious version Apr 20, 2019
tsconfig.base.json Uses lerna Apr 20, 2019 s/unmock/unmock-core/g Apr 20, 2019
tsconfig.json Uses lerna Apr 20, 2019
tsconfig.test.base.json Uses lerna Apr 20, 2019
tsconfig.test.json s/unmock/unmock-core/g Apr 20, 2019
tslint.json Initial commit Nov 18, 2018


npm CircleCI Known Vulnerabilities

Public API mocking for Node.js.

Unmock can be used to test modules that perform requests to third-party APIs like Hubspot, SendGrid, Behance, and hundreds of other public APIs.

Unmock can also be used to mock these APIs in a development environment, ie an express server on a local machine or in a staging environment.

Unmock is an isomorphic javascript package that can be used in Node or in the browser, including polyglot projects mixing the two (ie NextJS).

The ultimate goal of unmock is to provide a semantically and functionally adequate mock of the internet.

Table of Contents

How does it work?

Unmock works by overriding Node's http.request and https.request functions in addition to their follow-redirect versions, injecting JIT or persisted mocks of hundreds of APIs.


$ npm install --save unmock

Node version support

The latest version of unmock supports all currently maintained Node versions, see Node Release Schedule



In your unit tests, you can invoke unmock like this:

import { unmock } from "unmock-core";

beforeEach(async () => await unmock());

test("unmock mocks behance", {
  const { project } = await axios(``);

The above syntax uses jest, but the same is easily accomplishable in mocha, tape and most popular JS testing libraries.

Unmock will then either serve JIT semantically functionally correct mocks from its database or an empty JSON object for unmocked APIs that can be filled in by the user. The address of these editable objects is printed to the command line during tests.


After you create your express, hapi, koa, nextjs or apollo server, call

await unmock(ignoreStory());

This has the same effect as activating unmock in your tests. It will intercept http traffic and serve semantically and functionally adequate mocks of the APIs in the unmock catalogue. The main difference is the result of ignoreStory() passed to unmock, which tells the service to ignore the order of mocked requests. Always use this option when the order of mocked data does not matter, ie when you are in sandbox or development mode. For users of the service, this will help unmock better organize your mocks in its web dashboard.

Headless usage

Unmock works out of the box for most APIs that it mocks and does not require any additional configuration. For APIs that it does not mock yet, or to tweak return values from the unmock service, you can consult the URLs printed to the command line by unmock.

The URLs printed to the command line are hosted by You can consult the documentation about that service here.

Saving mocks

All mocks can be saved to a folder called .unmock in your project's root directory by adding a save field to the unmock options object like so:

await unmock({
  // ...
  save: "true",
  // ...

Unmock refers to every mock by a unique hash. Individual mocks or groups of mocks can be saved by setting save to either a single hash or an array of hashes like so:

await unmock({
  // ...
  save: ["ahash", "anotherhash", "yetanotherhash"],
  // ...

Ignoring aspects of a mock

Sometimes, you would like for two mocks of slightly API calls to be treated as equivalent by unmock. For example, you may want all GET calls to the same path with different headers to be served the same mock. To do this, use the ignore field of the unmock options object.

await unmock({
  // ...
  ignore: ["headers", "story"],
  // ...

The following fields may be ignored:

  • headers: the headers of the request
  • hostname: the hostname of the request
  • method: the method of the request (ie GET, POST, PUT, DELETE). Note that this is case insensitive!
  • path: the path of the request
  • story: the story of the request, meaning its order in a series of requests

Ignore evaluates regular expressions, so you can also pass "headers|path" instead of ["headers", "path"]. Furthermore, to ignore nested headers, pass an object such as {headers: "Authorization" }, or to match against the value of a header, {headers: { Authorization: "Bearer *" }}.

The default ignore is {headers: "\w*User-Agent\w*"} and will be incorporated into the ignore pattern unless ignore is explicitly set to an empty object, ie unmock({ ignore: {} }).

Helper calls to ignore are composable, ie unmock(ignoreAuth(ignoreStory())).

Adding a signature

Sometimes, it is useful to sign a mock with a unique signature. This is useful, for example, when AB testing code that should serve two different mocks for the same endpoint in otherwise similar conditions. Do this, use the signature field of the unmock options object:

await unmock({
  // ...
  signature: "signature-for-this-particular-test",
  // ...

Whitelisting API

If you do not want a particular API to be mocked, whitelist it.

await unmock({
  // ...
  whitelist: ["", ""],
  // ...
})); tokens

If you are subscribed to the service, you can pass your unmock token directly to the unmock object.

await unmock({
  // ...
  token: "my-token",
  // ...

At a certain point this becomes a bit tedious, at which point you will want to create a credentials file. See for more information on credential files.


Thanks for wanting to contribute! Take a look at our Contributing Guide for notes on our commit message conventions and how to run tests.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.



Copyright (c) 2018–2019 Meeshkan and other contributors.

You can’t perform that action at this time.