Meeshkan is a tool that mocks HTTP APIs for use in sandboxes as well as for automated and exploratory testing. It uses a combination of API definitions, recorded traffic and code in order to make crafting mocks as enjoyable as possible.
Chat with us on Gitter to let us know about questions, problems or ideas!
What's in this document
- Getting started with Meeshkan
- Collect recordings of API traffic
- Build a Meeshkan spec from recordings
- Mock server traffic using a Meeshkan spec
Install via pip (requires Python 3.6+):
pip install meeshkan
macOS users can install Meeshkan with Homebrew:
brew tap meeshkan/tap brew install meeshkan
Debian and Ubuntu users can install Meeshkan with
echo "deb [trusted=yes] https://dl.bintray.com/meeshkan/apt all main" | tee -a /etc/apt/sources.list apt-get -qq update && apt-get install meeshkan
Getting started with Meeshkan
The basic Meeshkan flow is collect, build and mock.
- First, collect data from recorded server traffic and/or OpenAPI specs.
- Then, build a schema that unifies these various data sources.
- Finally, use this schema to create a mock server of an API.
The quickest way to get an overview of Meeshkan is to complete our interactive tutorial. It walks you through the collect, build, and mock flow - while also covering the concepts necessary for development.
meeshkan-tutorial via pip:
$ pip install meeshkan-tutorial $ meeshkan-tutorial
Note: This tutorial has been tested on Python 3.6, 3.7, and 3.8.
After installing, you can begin the tutorial by invoking from the command line:
Once you've run this, you should see:
__ __ ____ ___ ___ ___ _____/ /_ / /______ _____ / __ `__ \/ _ \/ _ \/ ___/ __ \/ //_/ __ `/ __ \ / / / / / / __/ __(__ ) / / / ,< / /_/ / / / / /_/ /_/ /_/\___/\___/____/_/ /_/_/|_|\__,_/_/ /_/ The tutorial!! Press ENTER to continue...
If not, it's probably our fault. Please let us know by filing an issue on the meeshkan-tutorial repo.
Collect recordings of API traffic
Let's look at how to build a Meeshkan spec. First, you have to collect recordings of server traffic and/or OpenAPI server specs.
To record API traffic, the Meeshkan CLI provides a
record mode that captures API traffic using a proxy.
$ meeshkan record
This command starts Meeshkan as a reverse proxy on the default port of
8000 and creates two directories:
With curl, for example, you can use Meeshkan as a proxy like so:
$ curl http://localhost:8000/http://api.example.com
By default, the recording proxy treats the path as the target URL. It then writes a
.jsonl file containing logs of all server traffic to the
logs directory. All logs are created in the
http-types format. This is because Meeshkan's
build tool expects all recordings to be represented in a
.jsonl file containing recordings represented in the
For more information about recording, including direct file writing and kafka streaming, see the recording documentation.
Build a Meeshkan spec from recordings
Using the Meeshkan CLI, you can build an OpenAPI schema from a single
.jsonl file, in addition to any existing OpenAPI specs that describe how your service works.
$ meeshkan build --input-file path/to/recordings.jsonl
Optionally, you can also specify an output directory using the
--out flag followed by the path to this directory. By default, Meeshkan will build the new OpenAPI specifications in the
Use dash (
--input-file -) to read from standard input:
$ meeshkan build --input-file - < recordings.jsonl
You can use a mode flag to indicate how the OpenAPI spec should be built, for example:
meeshkan build --input-file path/to/recordings.jsonl --mode gen
Supported modes are:
- gen [default] - infer a schema from the recorded data
- replay - replay the recorded data based on exact matching
For more information about building, including mixing together the two modes and editing the created OpenAPI schema, see the building documentation.
Mock server traffic using a Meeshkan spec
You can use an OpenAPI spec, such as the one created with
meeshkan build, to create a mock server using Meeshkan.
$ meeshkan mock path/to/dir/
Note: You can specify a path to the directory your OpenAPI spec is in or a path to one specific file.
For more information about mocking, including adding custom middleware and modifying the mocking schema JIT via an admin API, see the mocking documentation.
Here are some useful tips for building and running Meeshkan from source.
If you run into any issues, please reach out to our team on Gitter.
- Clone this repository:
git clone https://github.com/meeshkan/meeshkan
- Create a virtual environment:
virtualenv .venv && source .venv/bin/activate
- Install dependencies:
pip install --upgrade -e '.[dev]'
Run all checks:
$ python setup.py test
Run tests/ with
pytest # or python setup.py test
pytest is found in pytest.ini.
Formatting is checked by the above mentioned
python setup.py test command.
To fix formatting:
$ python setup.py format
Run style checks:
$ flake8 .
You can run type-checking by installing pyright globally:
$ npm -i -g pyright
And then running:
$ pyright --lib $ # or $ python setup.py typecheck
Using the Pyright extension is recommended for development in VS Code.
Publishing Meeshkan as a PyPi package
To publish Meeshkan as a PyPi package, complete the following steps:
- Bump the version in setup.py if the version is the same as in the published package. Commit and push.
python setup.py testto check that everything works
- To build and upload the package, run
python setup.py upload. Insert PyPI credentials to upload the package to
PyPI. The command will also run
git tagto tag the commit as a release and push the tags to remote.
To see what the different commands do, see
Commandclasses in setup.py.
Thanks for your interest in contributing! Please take a look at our development guide for notes on how to develop the package locally. A great way to start contributing is to file an issue or make a pull request.
Code of Conduct
Please note that this project is governed by the Meeshkan Community Code of Conduct. By participating, you agree to abide by its terms.