Mocks for microservice environments

Getting Started

Learning Videos

Config Syntax

Request Matching

Response Templating

Async Actors (Kafka etc.)

Performance & Chaos Testing

Remote Management




Mockintosh aims to provide usual HTTP mock service functionality with small resource footprint, making it friendly for microservice applications. You can have tens of mocks at once, inside moderate laptop or single Docker container. Also, we have some additional ideas on how to make mocks simple and useful.

Key features:

Note: There is an article on UP9 blog explaining motivation behind Mockintosh project.

Quick Start

pip3 install mockintosh

If you have installed Mockintosh as Python package (requires Python 3.x+), start it with JSON/YAML configuration as an argument (consider my_mocks.yaml as example):

mockintosh my_mocks.yaml

Alternatively, you can run Mockintosh as Docker container:

docker run -it -p 8000-8005:8000-8005 -v `pwd`:/tmp up9inc/mockintosh /tmp/config.json

Please note the -p flag used to publish container’s ports and -v to mount directory with config into container.

After server starts, you can issue requests against it. For example, curl -v http://localhost:8000/ would respond hello world. Also, consider opening Management UI in your browser: http://localhost:8000/__admin. Management UI offers visual tools to see available mock endpoints, traffic log and many other features.

Command-line Arguments

The list of command-line arguments can be seen by running mockintosh --help.

If you don’t want to listen all of the services in a configuration file then you can specify a list of service names (name is a string attribute you can set per service):

mockintosh my_mocks.yaml 'Mock for Service1' 'Mock for Service2'

Using --quiet and --verbose options the logging level can be changed.

Using --bind option the bind address for the mock server can be specified, e.g. mockintosh --bind

Using --enable-tags option the tags in the configuration file can be enabled in startup time, e.g. mockintosh --enable-tags first,second


One can also specify a list of interceptors to be called in <package>.<module>.<function> format using the --interceptor option. The interceptor function get a mockintosh.Request and a mockintosh.Response instance. Here is an example interceptor that for every requests to a path starts with /admin, sets the reponse status code to 403:

import re
from mockintosh import Request, Response

def forbid_admin(req: Request, resp: Response):
    if re.search(r'^\/admin.*$', req.path):
        resp.status = 403

and you would specify such interceptor with a command like below:

mockintosh some_config.json --interceptor=mypackage.mymodule.forbid_admin

Instead of specifying a package name, you can alternatively set the PYTHONPATH environment variable to a directory that contains your interceptor modules like this:

PYTHONPATH=/some/dir mockintosh some_config.json --interceptor=mymodule.forbid_admin

Note: With interceptors, you can even omit endpoints section from the service config. You will still get all requests to the service into your interceptor.

Request Object

The Request object is exactly the same object defined in here with a minor difference: Instead of accesing the dictonary elements using .<key>, you access them using ['<key>'] e.g. request.queryString['a'].

Response Object

The Response object consists of three fields: