connect-api-mocker

connect-api-mocker is a connect.js middleware that fakes REST API server with filesystem. It will be helpful when you try to test your application without the actual REST API server.

It works with a wide range of servers: connect, express, browser-sync, lite-server, webpack-dev-server. Also it can be used as a command line tool with the help of cli-api-mocker.

Detailed article: https://medium.com/@muratcorlu/mocking-rest-endpoints-in-web-apps-easy-way-d4cd0e9db000

A presentation at AmsterdamJS'18 conference: https://www.youtube.com/watch?v=yF_8O4l-Ybc

Installation

npm install connect-api-mocker --save-dev

Usage

Using with Connect

var http = require('http');
var connect = require('connect');
var apiMocker = require('connect-api-mocker');

var app = connect();

app.use('/api', apiMocker('mocks/api'));

http.createServer(app).listen(8080);

Using with Express

var express = require('express');
var apiMocker = require('connect-api-mocker');

var app = express();

app.use('/api', apiMocker('mocks/api'));

app.listen(8080);

Using with BrowserSync

var browserSync = require('browser-sync').create();
var apiMocker = require('connect-api-mocker');

var restMock = apiMocker('/api', 'mocks/api');

browserSync.init({
  server: {
    baseDir: './',
    middleware: [
      restMock,
    ],
  },
  port: 8080,
});

Using with lite-server

bs-config.js file:

var apiMocker = require('connect-api-mocker');

var restMock = apiMocker('/api', 'mocks/api');

module.exports = {
  server: {
    middleware: {
      // Start from key `10` in order to NOT overwrite the default 2 middleware provided
      // by `lite-server` or any future ones that might be added.
      10: restMock,
    },
  },
  port: 8080,
};

Using with Grunt

You can use it with Grunt. After you install grunt-contrib-connect add api-mocker middleware to your grunt config. The mocks/api folder will be served as REST API at /api.

module.exports = function(grunt) {
  var apiMocker = require('connect-api-mocker');

  grunt.loadNpmTasks('grunt-contrib-connect');  // Connect - Development server

  // Project configuration.
  grunt.initConfig({

    // Development server
    connect: {
      server: {
        options: {
          base: './build',
          port: 9001,
          middleware: function(connect, options) {

            var middlewares = [];

            // mock/rest directory will be mapped to your fake REST API
            middlewares.push(apiMocker(
                '/api',
                'mocks/api'
            ));

            // Static files
            middlewares.push(connect.static(options.base));
            middlewares.push(connect.static(__dirname));

            return middlewares;
          }
        }
      }
    }
  });
}

After you can run your server with grunt connect command. You will see /api will be mapped to mocks/api.

Using with Webpack

To use api mocker on your Webpack projects, simply add a setup options to your webpack-dev-server options:

devServer.setup , This option is deprecated in favor of before and will be removed in v3.0.0.

  ...
  before: function(app) {
    app.use(apiMocker('/api', 'mocks/api'));
  },
  ...

Using with other languages other than JavaScript

If you have a Python/Ruby/.NET etc. project and want to use that mocking functionality, you can use cli-api-mocker as a wrapper of connect-api-mocker for command line. With the help of cli-api-mocker, if you run mockit command, you will have a seperate web server that will handle your mocks as a REST API. Please look for cli-api-mocker readme for details.

Directory Structure

You need to use service names as directory name and http method as filename. Files must be JSON. Middleware will match url to directory structure and respond with the corresponding http method file.

Example REST service: GET /api/messages

Directory Structure:

_ api
  \_ messages
     \_ GET.json

Example REST service: GET /api/messages/1

Directory Structure:

_ api
  \_ messages
     \_ 1
        \_ GET.json

Example REST service: POST /api/messages/1

Directory Structure:

_ api
  \_ messages
     \_ 1
        \_ POST.json

Example REST service: DELETE /api/messages/1

Directory Structure:

_ api
  \_ messages
     \_ 1
        \_ DELETE.json

Custom responses

If you want define custom responses you can use js files with a middleware function that handles requests.

Example REST service: POST /api/messages

Directory Structure:

_ api
  \_ messages
     \_ POST.js

POST.js file:

module.exports = function (request, response) {
  if (!request.get('X-Auth-Key')) {
    response.status(403).send({});
  } else {
    response.sendFile('POST.json', {root: __dirname});
  }
}

POST.js file for non ExpressJS server:

var fs = require('fs');
var path = require('path');

module.exports = function (request, response) {
  if (!request.get('X-Auth-Key')) {
    response.statusCode = 403;
    response.end();
  } else {
    var filePath = path.join(__dirname, 'POST.json');    
    var stat = fs.statSync(filePath);
    
    response.writeHead(200, {
        'Content-Type': 'application/json',
        'Content-Length': stat.size
    });

    var readStream = fs.createReadStream(filePath);
    // We replaced all the event handlers with a simple call to readStream.pipe()
    readStream.pipe(response);
  }
}

Another Example: Respond different json files based on a query parameter:

Request to /users?type=active will be responded by mocks/users/GET_active.json
Request to /users will be responded by mocks/users/GET.json

GET.js file:

const fs = require('fs');
const path = require('path');

module.exports = function (request, response) {
  var targetFileName = 'GET.json';

  // Check is a type parameter exist
  if (request.query.type) {
    // Generate a new targetfilename with that type parameter
    targetFileName = 'GET_' + request.query.type + '.json';
  }
  const filePath = path.join(__dirname, targetFileName);
  // If file does not exist then respond with 404 header
  try {
    fs.accessSync(filePath);
  }
  catch (err) {
    return response.status(404);
  }
  // Respond with filePath
  response.sendFile(filePath);
}

GET.js file for non ExpressJS server:

var url =  require('url');
var fs = require('fs');
var path = require('path');

module.exports = function (request, response) {
  var targetFileName = 'GET.json';
  var typeQueryParam = url.parse(request.url, true).query.type;
  // Check is a type parameter exist
  if (typeQueryParam) {
    // Generate a new targetfilename with that type parameter
    targetFileName = 'GET_' + typeQueryParam + '.json';
  }

  var filePath = path.join(__dirname, targetFileName);

  // If file does not exist then respond with 404 header
  try {
    fs.accessSync(filePath);
  }
  catch (err) {
    response.statusCode = 404;
    response.end();
    return;
  }

  var stat = fs.statSync(filePath);
  response.writeHead(200, {
      'Content-Type': 'application/json',
      'Content-Length': stat.size
  });

  var readStream = fs.createReadStream(filePath);
  // We replaced all the event handlers with a simple call to readStream.pipe()
  readStream.pipe(response);
}

Wildcards in paths

You can use wildcards for paths to handle multiple urls(like for IDs). If you create a folder structure like api/users/__user_id__/GET.js, all requests like /api/users/321 or /api/users/1 will be responded by custom middleware that defined in your GET.js. Also id part of the path will be passed as a request parameter named as user_id to your middleware. So you can write a middleware like that:

api/users/__user_id__/GET.js file:

module.exports = function (request, response) {
  response.json({
    id: request.params.user_id
  });
}

XML Support

Api Mocker also can handle XML responses. As you can see, for custom responses, it's not an issue. Because you are completely free about responses in custom responses. But for simple mocks, api mocker try to find a json file by default. You can set that behaviour as type in api mocker configuration:

app.use('/user-api', apiMocker({
  target: 'other/target/path',
  type: 'xml'
}));

If you use xml as type, api mocker should look for mocks/users/GET.xml file for a request to /users. Also you can use auto for type:

app.use('/user-api', apiMocker({
  target: 'other/target/path',
  type: 'auto'
}));

In that case, api mocker will look for Accept header in the request to determine response format. So, if you make a request with a Accept: application/json header, it'll try to send a response with a json file. If you make a request with a Accept: application/xml header, it'll try to send a response with an xml file.

Defining multiple mock configurations

You can use apiMocker multiple times with your connect middleware server. In example below, we are defining 3 mock server for 3 different root paths:

app.use('/api/v1', apiMocker('target/path'));
app.use('/user-api', apiMocker({
  target: 'other/target/path'
}));
app.use(apiMocker('/mobile/api', {
  target: 'mocks/mobile'
});

Next on not found option

If you have some other middlewares that handles same url(a real server proxy etc.) you can set nextOnNotFound option to true. In that case, api mocker doesnt trigger a 404 error and pass request to next middleware. (default is false)

apiMocker('/api', {
  target: 'mocks/api',
  nextOnNotFound: true
});

With that option, you can mock only specific urls simply.

Logging

If you want to see which requests are being mocked, set the verbose option either to true or provide your own function.

apiMocker('/api', {
  target: 'mocks/api',
  verbose: ({ req, filePath, fileType }) => console.log(`Mocking endpoint ${req.originalUrl} using ${filePath}.${fileType}.`)
});

khelkun/connect-api-mocker

connect-api-mocker

Installation

Usage

Using with Connect

Using with Express

Using with BrowserSync

Using with lite-server

Using with Grunt

Using with Webpack

Using with other languages other than JavaScript

Directory Structure

Custom responses

Another Example: Respond different json files based on a query parameter:

Wildcards in paths

XML Support

Defining multiple mock configurations

Next on not found option

Logging