The HTTP Mocking Toolkit (HMT) 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!
- Installation
- Getting started with HMT
- Collect recordings of API traffic
- Build a HMT spec from recordings
- Mock server traffic using a HMT spec
- Development
- Contributing
Install via pip (requires Python 3.6+):
pip install hmtmacOS users can install HMT with Homebrew:
brew tap meeshkan/tap
brew install hmtDebian and Ubuntu users can install HMT with apt:
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 hmtThe basic HMT 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 HMT is to complete our interactive tutorial. It walks you through the collect, build, and mock flow - while also covering the concepts necessary for development.
Note: This tutorial has been tested on Python 3.6, 3.7, and 3.8.
After installing HMT, you can begin the tutorial by invoking from the command line:
$ hmt tutorialOnce 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 this repo.
Let's look at how to build a HMT spec. First, you have to collect recordings of server traffic and/or OpenAPI server specs.
To record API traffic, the HMT CLI provides a record mode that captures API traffic using a proxy.
$ hmt recordThis command starts HMT as a reverse proxy on the default port of 8000 and creates two directories: logs and specs.
With curl, for example, you can use HMT as a proxy like so:
$ curl http://localhost:8000/http://api.example.comBy 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 HMT's build tool expects all recordings to be represented in a .jsonl file containing recordings represented in the http-types format.
For more information about recording, including direct file writing and kafka streaming, see the recording documentation.
Using the HMT 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.
$ hmt build --input-file path/to/recordings.jsonl Note: The input file should be in JSON Lines format and every line should be in http-types JSON format. For an example input file, see recordings.jsonl.
Optionally, you can also specify an output directory using the --out flag followed by the path to this directory. By default, HMT will build the new OpenAPI specifications in the specs directory.
Use dash (--input-file -) to read from standard input:
$ hmt build --input-file - < recordings.jsonlYou can use a mode flag to indicate how the OpenAPI spec should be built, for example:
hmt build --input-file path/to/recordings.jsonl --mode genSupported 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.
You can use an OpenAPI spec, such as the one created with hmt build, to create a mock server using HMT.
$ hmt 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 HMT 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/hmt - Create a virtual environment:
python3 -m venv .venv && source .venv/bin/activate - Install dependencies:
pip install --upgrade -e '.[dev]' - Install
pre-commithooks to automatically format code as a git hook:pre-commit install
Run all checks:
$ python setup.py testRun tests/ with pytest:
pytest
# or
python setup.py testConfiguration for pytest is found in pytest.ini.
Formatting is checked by the above mentioned python setup.py test command.
To fix formatting:
$ python setup.py formatRun style checks:
$ flake8 .You can run type-checking by installing pyright globally:
$ npm -i -g pyrightAnd then running:
$ pyright --lib
$ # or
$ python setup.py typecheckUsing the Pyright extension is recommended for development in VS Code.
Configuration for CircleCI build pipeline can be found in .circleci/config.yml.
To publish HMT 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.
- Run
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 toPyPI. The command will also rungit 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.
Please note that this project is governed by the Meeshkan Community Code of Conduct. By participating, you agree to abide by its terms.