Installing

npm i -g ezmockserver

Setting up a default configuration

cd /path/to/my/mock/directory

ezmockserver init

With this init configuration you can set up the server after configuring your ezmockserver Obs:. It will automatically create the ezmockserver json file and setting up a default folder with some default settings in order to see how it is meant to work. In this first draft it will just work a default setting

Configuration file

// ezmockserver.json
{
  "logLevel": "DEBUG",
  "sessionsDirectory": "./sessions",
  "api": { // one of httpPort|httpsPort must be provided
    "httpPort": 3050,
    "httpsPort": 3051,
  },
  "server": { // one of httpPort|httpsPort must be provided
    "httpPort": 3000,
    "httpsPort": 3001,
  },
  "proxy": { // optional
    "prefix": [
      { "path": "/path-one", "proxyPass": "https://server-one.com" },
      { "path": "/path-two", "proxyPass": "https://server-two.com" },
      { "path": "/path-three", "proxyPass": "https://server-three.com", "rewrite": "/" }
    ]
  },
  "defaultSession": { // optional
    "name": "my-session",
    "fileType": "content",
    "logRequest": true,
    "countMode": "COUNT_ALL",
    "groupResponsesByIp": true,
    "matchers": [ // optional
      {
        "name": "users-with-id-route",
        "method": "^GET$", // regex
        "url": "/users/\\\\d+" // regex
      },
      {
        "name": "any-other-routes",
        "method": "^(GET|POST|PUT|DELETE)$",
        "url": "/.*"
      }
    ]
  },
  "defaultMatchers": [
    {
      "name": "users-with-id-route",
      "method": "^GET$", // regex
      "url": "/users/\\\\d+" // regex
    },
    {
      "name": "any-other-routes",
      "method": "^(GET|POST|PUT|DELETE)$",
      "url": "/.*"
    }
  ]
}

logLevel: [DEBUG|INFO|WARN|ERROR]
Default: INFO

Session schema:

name:
Session name to be activated. Required

fileType: [script|content]
Set if mockserver should load "js" files or "content" files for response. Optional
Default: content

If script is selected, then the file should have the following syntax:

// my-mock.js
module.exports = {
  execute: (ctx) => {
    // do some logic here with request context
    return {
      status: 200,
      delay: 0, // delay in millis
      body: "response body here... it also can be a buffer",
      headers: {
        "custom-header-1":"custom-header-1-value",
        "set-cookie": [
          "cookie1=cookie1-value; domain=my-domain.com; path=/; Max-Age=3600; HttpOnly",
          "cookie2=cookie2-value; domain=my-domain.com; path=/; Max-Age=3600; HttpOnly"
        ]
      }
    }
  }
}

Mockserver will call execute function to any received request passing ctx variable as argument. This configuration make sense when you want to simulate differente values and timings for the requested route.

logRequest:
Set if a file should be created with all incoming request data. Optional
Default: true
Output file: <session-directory>/<session-name>/[<counter>.]<method>.<url>.req.json

Example:

curl --location --request GET 'localhost:3000/path/to/resource1'
curl --location --request POST 'localhost:3000/path/to/resource2'
curl --location --request DELETE 'localhost:3000/path/to/resource3'

The incoming requests will generate the following files:

./sessions/my-session/1.get.path-to-resource1.req.json
./sessions/my-session/2.post.path-to-resource2.req.json
./sessions/my-session/3.delete.path-to-resource3.req.json

countMode: [NO_COUNT|COUNT_BY_REQUEST_URL|COUNT_ALL]. Optional
Set how mockserver will behave towards the counter on each request received.
Default: COUNT_ALL

To explain better what these options means, let's suppose the mockserver receives the following requests in order:

curl --location --request GET 'localhost:3000/path/to/resource1'
curl --location --request GET 'localhost:3000/path/to/resource1'
curl --location --request GET 'localhost:3000/path/to/resource2'
curl --location --request GET 'localhost:3000/path/to/resource2'
curl --location --request GET 'localhost:3000/path/to/resource3'
curl --location --request GET 'localhost:3000/path/to/resource3'

When this parameter is set to NO_COUNT, the server will not increment any counter, and it will look to the following file prefix:

get.path-to-resource1
get.path-to-resource2
get.path-to-resource3

When this parameter is set to COUNT_BY_REQUEST_URL, the server will increment the counter grouping by their URLs and it will look to the following file prefix:

1.get.path-to-resource1
2.get.path-to-resource1
1.get.path-to-resource2
2.get.path-to-resource2
1.get.path-to-resource3
2.get.path-to-resource3

When this parameter is set to COUNT_ALL, the server will increment the counter at any request received and it will look to the following file prefix:

1.get.path-to-resource1
2.get.path-to-resource1
3.get.path-to-resource2
4.get.path-to-resource2
5.get.path-to-resource3
6.get.path-to-resource3

groupResponsesByIp:
Set if mockserver will group counter (set in countMode) by incoming IP address. Optional
Default: true

matchers:
Matchers is an easy way of intercepting/responding to requests applying regex patterns on http method and url. Make sure to escape the regex to a javascript string.
A good way to validate regex is to write the following code to a javascript console, get the output, copy to a validator such as regex101 and validate the expression with the given text

new RegExp("/oauth2/token\\?grant_type=client_credentials")

// output:

/\/oauth2\/token\?grant_type=client_credentials/

Optional
default: []

Any matcher should follow this object

{
  "name": "matcher-for-my-regex",
  "method": "(GET|POST)", // regex to apply to the http method
  "url": "/my/url/\\d+/regex/.*" // regex to apply to the path
}

If matcher is not provided, the server will use defaultMatchers from configuration file.

Checkout examples here.

Starting a session

There are two ways to start a session

• Setting defaultSession at startup configuration file (ezmockserver.json)
• Through the API server

If a file named .config.json is found at session directory, then the session will be merged with it. This file should follow Session schema

API Server

Starting a session

# data-raw should follow Session schema
curl --location --request POST 'http://localhost:3050/sessions/current' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "my-session",
    "countMode": "NO_COUNT",
    "fileType": "script",
    "logRequest": false
  }'

Getting information about active session

# get only the name of active session
curl --location --request GET 'http://localhost:3050/sessions/current'

# this request shows all received requests with its url, headers and body
curl --location --request GET 'http://localhost:3050/sessions/current?tracedRequests=true'

Uploading a session

# session.zip should be a zip file performed at session directory
curl --location --request POST 'http://localhost:3050/sessions' --form 'file=@"/path/to/my-session.zip"'

Listing available sessions

curl --location --request GET 'http://localhost:3050/sessions'

Running with Docker

Mount folder containing ezmockserver.json to "/ezmockserver"

docker run --rm \
  -v $(pwd)/ezmockserver:/ezmockserver \
  -p 3000:3000 \
  -p 3050:3050 \
  trzenaro/ezmockserver:latest

HTTPS support

ezmockserver has a built-in self-signed certificate to respond to HTTPS connections for localhost

openssl req \
  -newkey rsa:4096 \
  -x509 \
  -sha256 \
  -days 3650 \
  -nodes \
  -out certs/localhost.crt \
  -keyout certs/localhost.key \
  -subj "/C=BR/ST=Sao Paulo/L=Sao Jose do Rio Preto/O=ezmockserver/OU=development/CN=localhost"

To Do list

• Implement tests validating:

  Server

  • matchers
  • default matchers
  • count mode
  • fixed response
  • scripted response
  • logging (application log)
  • logging (request log file)
  • grouping request by ip

  API

  • get active session
  • get available sessions
  • activating session
  • stopping session
  • uploading session
  • downloading session