Skip to content

Latest commit

 

History

History
97 lines (75 loc) · 3.25 KB

user-guide.md

File metadata and controls

97 lines (75 loc) · 3.25 KB
Raw

User guide

Basic usage:

  • create a directory mock-server
  • place some handler files in it (read below for how to write them)
  • run mock-server

CLI options

  • root: mock server root directory, defaults to mock-server
  • port: mock server port, defaults to 3456
  • delay: milliseconds to delay all responses by, defaults to 0
  • watch: boolean flag, makes the server reload on file changes
  • serveConfig: boolean flag, serves a config script at /app-config.js. The script is generated by @staticdeploy/app-config from environment variables and - if a .env file il present - variables defined in it
  • require: require a module before startup, can be used multiple times
  • useHttps: boolean flag, makes mock-server serve requests via https. When enabled mock-server generates a self signed certificate that your borswer needs to trust before being able to make API calls to the server. To trust the certificate, visit https://localhost:3456 and dismiss the security warning
  • middleware: path to a file exporting an array of express middleware. The path should be relative to the mock server root directory. Defaults to middleware.js

Writing handler files

Handler files are files whose basename matches an http method: mock-server/get.js, mock-server/users/post.js etc.

Handler files export an express route handler:

// mock-server/get.js
module.exports = (req, res) => {
  res.status(200).send("OK");
};

The function exported by a handler file is registered as the handler for the route whose path matches the handler file's path relative to the mock-server directory, and whose method matches the handler file's name. Examples:

  • the function exported by mock-server/get.js is registered as the handler for route GET /
  • the function exported by mock-server/users/post.js is registered as the handler for route POST /users

You can also use route params:

  • the function exported by mock-server/users/{userId}/get.js is registered as the handler for route GET /users/:userId

Which you can access as you would in express:

// mock-server/users/{userId}/get.js
module.exports = (req, res) => {
  console.log(req.params.userId);
  res.status(200).send(`userId: ${req.params.userId}`);
};

Note: the path syntax for parametric routes is .../{param}/... instead of .../:param/... because the latter path is not valid for some filesystems (eg NTFS)

Request bodies are parsed according to their mime-type:

  • application/json: req.body is an object, the parsed json body
  • text/*: req.body is as string, the body
  • application/x-www-form-urlencoded: req.body is an object, the parsed urlencoded body
  • */*: req.body is a buffer, the raw body

Delaying responses

mock-server adds a delay method to the express response object which you can use to delay individual responses:

module.exports = (req, res) => {
  res
    // Delay in milliseconds
    .delay(1000)
    .status(200)
    .send("Delayed response");
};

Validating requests and responses

Read the validation guide to learn how to validate requests received by the mock-server, as well as responses generated by it.