Mockintosh is a a powerful, lightweight, and low footprint API Mock for microservices. Mockintosh can be used for all testing types that require mocks, and is especially valuable for performance testing, resilience testing in chaos engineering, and frontend testing.

Mockintosh helps developers and testers easily orchestrate and manage multiple mocking services. It is also friendly to maintain and deploy, does not consume a lot of RAM or Docker image space, is simple to configure, and is language neutral.

Mockintosh Quickstart

Copy to clipboard
pip3 install mockintosh

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

Copy to clipboard
mockintosh my_mocks.yaml

You can also run Mockintosh as a Docker container:

Copy to clipboard
docker run -it -p 8000-8005:8000-8005 -v 

Use the -p flag to publish the container's ports, and -v to mount the directory with configuration into the container.

Once the server starts, you can issue requests against it. For example, curl -v http://localhost:8000/ would respond hello world.

To see Mockintosh’s management UI, point your browser to http://localhost:8000/_admin. Management UI offers visual tools to see available mock endpoints, traffic logs, and many other features.

Using Mockintosh

Command-line Arguments

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

If you don’t want to listen to all of the services in a configuration file, you can specify a list of service names. Name is a string attribute you can set per service. For example:

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

--quiet and --verbose change the verbosity of Mockintosh's diagnostic logging.

--bind specifies the bind address for the mock server, e.g. mockintosh --bind

--enable-tags enables tags in the configuration file at startup time, e.g. mockintosh --enable-tags first,second


You 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 request to a path starting with /admin, sets the reponse status code to 403:

Copy to clipboard
import re
from mockintosh import Request, Response
def forbid_admin(req: Request, resp: Response):
if'^/admin.*$', req.path):
resp.status = 403

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

Copy to clipboard
mockintosh some

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

Copy to clipboard
PYTHONPATH=/some/dir mockintosh some

Note: With interceptors, you can omit the 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 here, but 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:

  • resp.status holds the HTTP status codes, e.g. 200, 201, 302, 404, etc.
  • resp.headers is a Python dictionary where you access or modify the response headers, e.g. resp.headers['Cache-Control'] == 'no-cache'
  • resp.body is usually either str or bytes, but can be anything that is supported by tornado.web.RequestHandler.write.

Learn More

Learn more at


For support, feel free to use any one of the three: