README.md

moxx

moxx is a tool to easily mock your external APIs. No more failed tests because of fragile dependencies.

Features

• yaml based configuration
• Watch mappings for auto reload
• Powerful request matching system
• Proxying
• Record API calls for mock generation

Disclaimer

This project is heavily inspired by wiremock written in java.

Requirements

• Node.js 6+
• npm 3+

Installation

npm i -g moxx

Usage

moxx

Options

Option	Default	Description
-h, --help		Output usage information
-V, --version		Output the version number
-p, --port <port>	5000	The port number for the server to listen on
-d, --dir <directory>	.	The root config/mapping/files directory
-w --watch	false	Watch for changes
-r, --record	false	Records proxy requests/responses
-x, --proxy <proxy>		Act as a proxy
--no-color	false	Disable color
-l, --loglevel	info	Sets logger log level

Configuration

moxx requires two directories, mappings and files to run, if they don't exist, it will create them. Those directories should be available under the dir option (default to .).

The mappings directory contains yaml files which define the mapping between incoming requests parameters (method, url, query, headers…) and responses, the files directory contains files to be used as response body.

The mappings files are loaded in memory whereas the files are loaded when required and not cached, it means if you modify a mapping file, the change you make won't be available immediately, if you want this you should consider using the watch option. If you change the content of a file or add one in the files directory, it will be available without restart or requiring the watch option.

Mapping file

The typical structure of a mapping file is:

get_users: # must be unique among all mappings
  request: # rules for matching
    method: GET
    url:    /users
  response: # response to send on match
    status: 200
    body:   hello world

Please, see request matching for further details on request configuration.

The response configuration accepts several keys:

get_users:
  # ...
  response:
    status: 200
    headers:
      Content-Type: application/json
    # you cannot use both body and bodyFile  
    body:     hello world
    bodyFile: hello-world.txt

Watching changes on mappings

moxx --watch

Request matching system

moxx provides a powerful request matching system.

• matching method
• matching url
• matching query
• matching headers
• scoring

Matching http method

# match GET method
method_get:
  request:
    method: GET
    
# match all methods
method_any:
  request:
    method: '*'

Matching url

Internally, moxx uses minimatch.

# match /users
users:
  request:
    url: /users

# match /users/2
user_2:
  request:
    url: /users/*
    
# match /users/2/profile
user_2_profile:
  request:
    url: /users/**    

Matching query

Unlike the method and url matchers, query matching provides more versatile matchers to ease mock definition.

# exists
get_user_with_id:
  request:
    query:
      id:
        exists: true

# equals        
get_user_with_id_2:
  request:
    query:
      id:
        equals: 2
      # alternative form
      id: 2 # defaults to equals matcher
        
# includes        
get_user_with_username_including_plouc:
  request:
    query:
      username:
        includes: plouc

Matching headers

Unlike the method and url matchers, headers matching provides more versatile matchers to ease mock definition.

# exists
get_user_with_x-id:
  request:
    headers:
      x-id:
        exists: true

# equals        
get_user_with_x-id_2:
  request:
    headers:
      x-id:
        equals: 2
      # alternative form
      x-id: 2 # defaults to equals matcher
        
# includes        
get_user_with_x-username_including_plouc:
  request:
    headers:
      x-username:
        includes: plouc

Scoring

moxx implements a scoring system to match requests, each rule you define increment the score of a mapping, in the end the response whose request has the highest score will be sent.

# this entry will be eligible but will always have a score of 0 because no rule is defined
default:
  request:  {}
  response:
    status: 200
    body:   moxx

# this entry will have a score of 1 if the incoming request is a GET request    
get_method:
  request:
    method: GET
  response:
    status: 200
    body:   moxx GET request
    
# this entry will have a score of 2 if the incoming request is a GET request and the url is /users
get_users:
  request:
    method: GET
    url:    /users
  response:
    status: 200
    body:   moxx GET users request

given this mapping:

• HEAD / will use default response (score: 0)
• GET / will use get_method response (score: 1)
• GET /users will use get_users response (score: 2)

Proxying

moxx --proxy https://api.github.com

Recording

moxx --proxy https://api.github.com --record