mockyeah

mockyeah

"An invaluable service mocking platform built on Express."

Testing is difficult when you don't have control of your data. This project puts you in complete control, enabling you to implement real mock web services with ease. Real mock services means you have control of response payloads, HTTP Status Codes, response latency, and more.

Have a requirement to implement specific behavior when a service is slow to respond or a server returns an unexpected status code? No problem! This platform makes developing for such requirements easy.

Install

$ npm install mockyeah --save-dev

Usage

• Introductory tutorial
• Testing example

API

Mock service creation API

mockyeah.get(path, options)
mockyeah.put(path, options)
mockyeah.post(path, options)
mockyeah.delete(path, options)
mockyeah.all(path, options)

Each of the methods creates a mock service with a HTTP verb matching its respective method name.

Parameters

Path String

Path to which to mount service. Fully supports all Express path matching options.

Options Object

Response options informing mockyeah how to respond to matching requests. Supported options:

One of the following options may be used per service:

• filePath (String; optional) - File with contents to include in response body. Assumes response Content-Type of file type.
• fixture (String; optional) - Fixture file with contents to include in response body. Assumes response Content-Type of file type. Default fixture file location is ./fixtures in your project.
• html (String; optional) - HTML to include in response body. Assumes response Content-Type of text/html.
• json (Object; optional) - JSON to include in response body. Assumes response Content-Type of application/json.
• raw (String; optional) - Text to include in response body. Content-Type is the default Express type if not specified in header.
• text (String; optional) - Text to include in response body. Assumes response Content-Type of text/plain.

Additional options:

• headers (Object; optional) - Header key value pairs to include in response.
• latency (Number in Milliseconds; optional) - Used to control the response timing of a response.
• type (String; optional) - Content-Type HTTP header to return with response. Proxies option to Express response method res.type(type); more info here: http://expressjs.com/en/4x/api.html#res.type
• status (String; optional; default: 200) - HTTP response status code.

Service capture recording and playback

mockyeah.record(name)

name (String; required) Directory name to save service responses recordings (i.e. ./mockyeah/[recording name]).

Configures mockyeah to proxy and record service requests. Recorded responses are written to ./mockyeah. To use this feature, you must update the service addresses in your application to proxy through mockyeah. Here is an example of an address configured for recording:

http://localhost:[mockyeah port]/http://example.com/your/service/url

mockyeah.play(name)

name (String; required) Directory name from which to mount contained service responses recordings (i.e. ./mockyeah/[recording name]).

Mounts each service response captured during a recording. Each service response will be mounted with exact same payload, headers, status, and latency as experienced during recording. This behavior may be changed by altering the values in the captured service response file.

Here is an example of a service response file:

{
  "method": "GET",
  "url": "http://example.com/some/service",
  "path": "/some/service",
  "options": {
    "headers": {
      "x-powered-by": "Express",
      "content-type": "text/plain; charset=utf-8",
      "content-length": "12",
      "etag": "W/\"5-iwTV43ddKY54RV78XKQE1Q\"",
      "date": "Sun, 21 Feb 2016 06:17:49 GMT",
      "connection": "close"
    },
    "status": 200,
    "raw": "Hello world!",
    "latency": 57
  }
}

Pseudo recordings may be created manually to ease repetitive setup of multiple services. Here are the steps to creating a pseudo recording:

1. Create a recording directory (e.g. ./mockyeah/pseudo-example)
2. Add one or more JSON files containing the following properties, at minimum:

  {
    "method": "GET",
    "path": "/some/service",
    "options": {
      "text": "Hello world!"
    }
  }

See Mock service creation API for details on supported options.

1. Play your pseudo recording.

  require('mockyeah').play('pseudo-example');

1. That's it!

Mock service and server management

mockyeah.reset()

Removes all mounted mock services. Best practice is to execute .reset() in an after test hook. Example usage with Mocha:

// unmounts all mounted services after each test
afterEach(() => mockyeah.reset());

You may remove specific services by passing paths matching services to unmount. Example:

mockyeah.get('/foo-1', { text: 'bar' });
mockyeah.get('/foo-2', { text: 'bar' });
mockyeah.get('/foo-3', { text: 'bar' });

// unmounts only /foo-1 and /foo-2
mockyeah.reset('/foo-1', '/bar-2');

mockyeah.close()

Stops mockyeah Express server. Useful when running mockyeah with a file watcher. mockyeah will attempt to start a new instance of Express with each iteration of test execution. After all tests run, mockyeah.close() should be called to shutdown mockyeah's Express server. Failing to do so will likely result in EADDRINUSE exceptions. This is due to mockyeah attempting to start a server on an occupied port.

mockyeah configuration

Default .mockyeah configuration:

{
  "name": "mockyeah",
  "host": "localhost",
  "port": 4001,
  "fixturesDir": "./fixtures",
  "capturesDir": "./mockyeah",
  "output": true,
  "journal": false,
  "verbose": false
}

Configuration options:

• name: Used to identify the origin of logged output.
• host: Host on which mockyeah will run.
• port: Port on which mockyeah will run.
• fixturesDir: Relative path to the fixtures directory.
• capturesDir: Relative path to the captures directory.
• output: Boolean to toggle mockyeah generated output written to stdout.
• journal: Boolean to toggle request journaling. Example:

[mockyeah][14:54:21][REQUEST][JOURNAL] {
  "callCount": 1,
  "url": "/foo?bar=baa",
  "fullUrl": "http://localhost:4001/foo?bar=baa",
  "clientIp": "127.0.0.1",
  "method": "GET",
  "headers": {
    "host": "localhost:4001",
    "user-agent": "curl/7.43.0",
    "accept": "*/*"
  },
  "query": {
    "bar": "baa"
  },
  "body": {}
}

• verbose: Boolean to toggle verbosity of mockyeah generated output.

Overriding any of these configurations can be done by placing a .mockyeah file in root of the project and adding the key value pair that needs to be updated. This file should be written using standard JSON.

Introductory tutorial

1. Create an example project and initialized with NPM

$ mkdir example-app && cd example-app
$ npm init # all defaults will be fine

1. Install mockyeah

$ npm install mockyeah --save-dev

1. Create script file and add the source below

$ touch index.js

const mockyeah = require('mockyeah');

mockyeah.get('/hello-world', { text: 'Hello World' });

1. Run the script file with Node

$ node index.js

1. Open http://localhost:4001/hello-world

2. Profit. You should see "Hello World" returned from your mock server.

Testing example

const request = require('supertest')('http://localhost:4001');
const mockyeah = require('mockyeah');

describe('Wondrous service', () => {
  // remove service mocks after each test
  afterEach(() => mockyeah.reset());

  // stop mockyeah server
  after(() => mockyeah.close());

  it('should create a mock service that returns an internal error', (done) => {
    // create failing service mock
    mockyeah.get('/wondrous', { status: 500 });

    // assert service mock is working
    request
      .get('/wondrous')
      .expect(500, done);
  });

  it('should create a mock service that returns JSON', (done) => {
    // create service mock that returns json data
    mockyeah.get('/wondrous', { json: { foo: 'bar' } });

    // assert service mock is working
    request
      .get('/wondrous')
      .expect(200, { foo: 'bar' }, done);
  });
});

Package dependencies

• mockyeah was built and tested with Node v4.2.3
• Mocha

Contributing

Getting started

Installing project and dependencies

# download project
$ git clone [e-mail]:ryanricard/mockyeah.git
$ cd mockyeah

# install proper Node version
$ nvm install v4.2.3
$ nvm use

# if tests pass, you're good to go
$ npm test