Mocked API

This server can mock the responses of an API with files on disk. Most likely to be used in automatic testing or in early development of an API-depending project.

Installation

$ npm install mocked-api --save-dev

Usage

Configuration

To get things running (to use it in your test-suite for example), initialize it like this:

import MockedApi from 'mocked-api';

const api = MockedApi.setup({
  port: 3000, // port where you want the API to run on
  dir: './mocks' // directory where your JSON-files live
});

api.start().then() => {
  console.log('API ready')
});

You can do this once (like in a script that's running your test-suite). The server will keep running until that process is killed, so you don't have to setup the server for every single test.

JSON-files

Place JSON-files in the configured directory to accomodate the responses. You can use nested directories to simulate a path-hierarchy. For example, the file at ./mocks/content/article/42.json will be served at http://localhost:3000/content/article/42.json for the configuration above. If your API prohibits you from adding an extension, either create a file with or without an extension and it will be resolved.

Custom responses

Once initialized, you can mutate responses with the following methods:

import { api } from 'mocked-api';

api
  .respondTo(path) // Defines the path you're about to change
  .andReplace(pointer, value) // Replace a property in your JSON-file. This is based on JSON-pointers, described in [RFC 6901](https://tools.ietf.org/html/rfc6901).
  .withStatus(status) // Custom status-code (`200`, `404`, `500`, etc)

api
  .onResponse((status, body) => {}) // Callback fired for every request, handy for debugging
  .reset() // Removes _all_ custom mutations

You can use these methods to make small changes in a response and test your UI for every little variation that you make. This way your tests can be small and specific, and still cover a lot of edge-cases.

The following example is based on mocha/chai/jsdom, but you can use it similarly in other environments:

import { api } from 'mocked-api';

describe('article', () => {
  beforeEach(() => {
    // Don't forget to reset the API if
    // you're overriding responses:
    api.reset();
  });

  describe('title', () => {
    describe('when it has a title', () => {
      it('renders the title', () => {
        api
          .respondTo('/content/article/42.json')
          .andReplace('/title', 'test title');

        return browser
          .go(`${baseUrl}/article/42`)
          .then(window => {
            expect(window.$('#title').text()).to.equal('test title');
          });
      });
    });

    describe('when it has no title', () => {
      it('renders no title', () => {
        api
          .respondTo('/content/article/42.json')
          .andReplace('/title', null);

        return browser
          .go(`${baseUrl}/article/42`)
          .then(window => {
            expect(window.$('#title').length).to.equal(0);
          });
      });
    });
  });
});

Two API's at the same time

You can run multiple instances of MockedApi simultaneously. For that, pass it a name when you setup each:

import MockedApi from 'mocked-api';
const userApi = MockedApi.setup({ name: 'user', port: 3000, dir: './mocks/user' });
const blogApi = MockedApi.setup({ name: 'blog', port: 3001, dir: './mocks/blog' });

Anytime you need one of those API's to override, make sure you use that same name:

import MockedApi from 'mocked-api';
const userApi = MockedApi.getByName('user');

describe('user', () => {
  beforeEach(() => userApi.reset());

  describe('when logged in', () => {
    it('shows avatar', () => {
      const kitty = 'http://placekitten.com/200/300';

      userApi
        .respondTo('/me')
        .andReplace('/image/src', kitty);

      return browser
        .go('/')
        .then(window => {
          expect(window.$('#avatar').attr('src')).to.equal(kitty);
        });
    });
  });

  describe('when not logged in', () => {
    it('does not show avatar', () => {
      userApi
        .respondTo('/me')
        .withStatus(401)

      return browser
        .go('/')
        .then(window => {
          expect(window.$('#avatar').length).to.equal(0);
        });
    });
  });
});

Standalone

You can also run the server standalone, from your CLI:

$ node_modules/.bin/mocked-api --port 6000 --dir ./mocks

This will serve JSON-files in ./mocks at localhost:6000, but that's it. Custom mutation of responses is not possible through the CLI.

Notes

• POST/PUT/DELETE are not yet implemented. If you need one of those, please ping me and give me some time to work it out.
• Don't let anyone tell you different: Setting up a test-suite in the javascript world is not always super duper easy. Let me know if you're having problems with MockedApi!