How to create a mock response

If you need a server-side resource or service which doesn't yet exist or is out of reach, the goal of mocks is to enable you to quickly create one.

If you have lws-mock-response present in your stack (included by default) you will have the option to set --mocks.

$ ws --mocks my-mocks-module.js

This is the minimum code required for a mock module, you can use it as a boilerplate template. Replace MyMockModule with a more useful name. The options argument will contain the currently active ws config.

module.exports = MockBase => class MyMockModule extends MockBase {
  mocks (options) {
    return []
  }
}

The mocks method must return one or more objects, each with two properties - route and responses. The route value can use any Express-style routing syntax, described here in the "Route paths" and "Route parameters" sections.

module.exports = MockBase => class MyMockModule extends MockBase {
  mocks (options) {
    return [
      {
        route: '/pizzas/:id',
        responses: []
      }
    ]
  }
}

The responses property must contain one or more objects, each with a response property. The response property value will be written directly to the Koa ctx object, meaning on this object you can set any of the standard ctx response values. The properties you will set must commonly are body, status and type.

This example will respond with 200 (the default statusCode) and the body Margerita to any request for /pizzas/:id, e.g. /pizzas/1.

module.exports = MockBase => class MyMockModule extends MockBase {
  mocks (options) {
    return [
      {
        route: '/pizzas/:id',
        responses: [
          {
            response: {
              body: 'Margerita'
            }
          }
        ]
      }
    ]
  }
}

We can convert our response to return JSON.

module.exports = MockBase => class MyMockModule extends MockBase {
  mocks (options) {
    return [
      {
        route: '/pizzas/:id',
        responses: [
          {
            response: {
              type: 'json',
              body: '{ "name": "Margerita" }'
            }
          }
        ]
      }
    ]
  }
}

Each response object can optionally include a request property. The request property limits which type of request should receive this mock response. The value should be an object with either of the two properties method or accepts.

In the following example, this request would receive a 404 Not Found:

$ curl http://127.0.0.1:8000/pizzas/1 --header 'accept: application/xml'

However, if our request accepts JSON will we receive a 200:

$ curl http://127.0.0.1:8000/pizzas/1 --header 'accept: application/json'

module.exports = MockBase => class MyMockModule extends MockBase {
  mocks (options) {
    return [
      {
        route: '/pizzas/:id',
        responses: [
          {
            request: {
              method: 'GET',
              accepts: 'json'
            },
            response: {
              type: 'json',
              body: '{ "name": "Margerita" }'
            }
          }
        ]
      }
    ]
  }
}

If you need to craft a more complex response and know what you're doing with the Koa ctx object, you can define response as a function and handle setting the ctx values yourself. Note that the response function also receives any route parameter values. Therefore, if the route is /pizzas/:id and you received a request for /pizzas/5 then id will equal 5.

module.exports = MockBase => class MyMockModule extends MockBase {
  mocks (options) {
    return [
      {
        route: '/pizzas/:id',
        responses: [
          {
            request: {
              method: 'GET',
              accepts: 'json'
            },
            response: function (ctx, id) {
              ctx.json = 'json'
              ctx.body = `{ "name": "Margerita", "id": ${id} }`
            }
          }
        ]
      }
    ]
  }
}

Finally, if you want to send any debug information to the --verbose output, you can do so by emitting the verbose event anywhere within the mocks method.

module.exports = MockBase => class MyMockModule extends MockBase {
  mocks (options) {
    this.emit('verbose', 'mock.MyMockModule', 'some debug information')
    return []
  }
}