--------------------------------------------------------------------------------
[](https://github.com/promptromp/mockstack/actions/workflows/ci.yml)
[](https://github.com/promptromp/mockstack/blob/main/LICENSE)
[](https://pypi.org/project/mockstack/)
[](https://pypi.org/project/mockstack/)
An API mocking workhorse :racehorse:
Enabling a sane development lifecycle for microservice-oriented architectures and LLM-driven tool chains.
Use mockstack for:
* **Development** :pencil2:. Simulating HTTP-based interactions between a particular component you're developing or debugging locally and multiple other components it depends on during execution of a particular flow. You can create template-based mock responses, simulate creation of resources in a realistic way, as well as proxy to other services using a rich rules DSL. Full request and response metadata and payloads can be observed via OpenTelemetry integration.
* **Integration Testing** :ok_hand:. Creating a consistent environment for running integration tests on a single component, using fixture responses.
* **LLM-powered Workflows** :alien:. Speeding up development and reducing per-token costs of LLM-based workflows and tools for use with frameworks such as [LangChain](https://python.langchain.com/docs/introduction/), [LangGraph](https://www.langchain.com/langgraph) and others. When developing LLM-driven execution graphs. Optional [Ollama](https://ollama.com/) integration allows for realistic mocking of 3rd party LLMs without changing a line of code in your project. In addition, when you want to have a consistent response from a tool while you're tuning prompts or debugging other aspects of a particular trace you can create various fixture responses with varying levels of dynamic content that is template-driven. **mockstack** can give you a solid foundation for this.
* **Chaos Engineering** :boom:. mockstack can simulate various real-world runtime error scenarios such as timeouts, http error codes, and invalid response payloads. This can be a great way to do some upfront [Chaos Monkey](https://github.com/Netflix/chaosmonkey) type of testing on software components.
Highlights include:
* Multiple strategies for handling requests such as [Jinja](https://jinja.palletsprojects.com/en/stable/) template files with intelligent URL request-to-template routing, proxy strategy, and mixed strategies. :game_die:
* Observability via [OpenTelemetry](https://opentelemetry.io/) integration. Get detailed traces of your sessions instantly reported to backends such as [Grafana](https://grafana.com/), [Jaeger](https://www.jaegertracing.io/), [Zipkin](https://zipkin.io/), etc. :eyes:
* Configurability via [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) supports customizing behaviour via environment variables and a `.env` file. :flags:
* Comprehensive unit-tests, linting and formatting coverage as well as vulnerabilities and security scanning with full CI automation to ensure stability and a high-quality codebase for production-grade use. :+1:
## Installation
Install using [uv](https://docs.astral.sh/uv/). This package conforms the concept of a [tool](https://docs.astral.sh/uv/concepts/tools/) and hence can simply install / run with [uvx](https://docs.astral.sh/uv/guides/tools/):
uvx mockstack --help
or install into a persistent environment and add it to the PATH with:
uv tool install mockstack
## Usage
See the [examples](https://github.com/promptromp/mockstack/blob/main/examples/) directory for complete examples with documentation.
Available configuration options are [here](https://github.com/promptromp/mockstack/blob/main/mockstack/config.py).
Setting individual options can be done either through an `.env` file, individual environment variables, or command-line arguments.
Minimal example to get you started:
```shell
mkdir -p ~/mockstack-templates
echo '{"message": "Hello from mockstack!"}' > ~/mockstack-templates/myservice-api-myresource.j2
export MOCKSTACK__TEMPLATES_DIR=~/mockstack-templates/
uvx mockstack
```
You can then hit `http://localhost:8000/myservice/api/myresource/23faa8cf-5daa-4bcb-8c92-27018b712aa9` (or any other UUID).
This is of course just the tip of the iceberg.
See also the included [.env.example](https://github.com/promptromp/mockstack/blob/main/.env.example) for more settings you are likely to find useful. You can copy that file to `.env` and fill in configuration as needed based on the given examples.
Out of the box, you get the following behavior when using the default `filefixtures` strategy:
- The HTTP request `GET /someservice/api/v1/user/c27f5b2b-6e81-420d-a4e4-6426e1c32db8` will try to find `<templates_dir>/someservice-api-v1-user.c27f5b2b-6e81-420d-a4e4-6426e1c32db8.j2`,
and will fallback to `<templates_dir>/someservice-api-v1-user.j2` (and finally to `index.j2` if exists). These are j2 files that have access to request body context variables.
- The HTTP request `POST /someservice/api/v2/item` with a JSON body will attempt to intelligently simulate the creation of a resource, returning the appropriate status code and will echo back the provided request resource, after injecting additional metadata fields based on strategy configuration. This is useful for services that expect fields such as `id` and `created_at` on returned created resources.
- HTTP requests for `DELETE` / `PUT` / `PATCH` are a no-op by default, simply returning the appropriate status code.
- The HTTP request `POST /someservice/api/v2/embedding_search` will be handled as a search request rather than a resource creation, returning an appropriate http status code and mock results based on user-configurable formatting.
Overall, the design philosophy is that things "just work". The framework attempts to intelligently deduce the intent of the request as much as possible and act accordingly,
while leaving room for advanced users to go in and customize behavior using the configuration options.
## Testing
Invoke unit-tests with:
uv run python -m pytest
Linting, formatting, static type checks etc. are all managed via [pre-commit](https://pre-commit.com/) hooks. These will run automatically on every commit. You can invoke these manually on all files with:
pre-commit run --all-files
## Contributing
If you are contributing to development, you will want to clone this project, and can then install it locally with:
gh repo clone promptromp/mockstack
cd mockstack/
uv sync
uv pip install -e .
Run in development mode (for live-reload of changes when developing):
uv run uvicorn --factory mockstack.main:create_app --reload
Note that when you run using the uvicorn CLI, you will need to set any configuration via `.env` file or environment variables.
Raw data
{
"_id": null,
"home_page": null,
"name": "mockstack",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "mocking, integration-testing, testing, microservices, api",
"author": null,
"author_email": "Adam Ever-Hadani <mockstack.contact@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/99/51/9e34679874f7f86c0209999d1e2276c073d5b2963cc3e15f25df86bd4f2d/mockstack-0.11.1.tar.gz",
"platform": null,
"description": "\n\n--------------------------------------------------------------------------------\n\n\n[](https://github.com/promptromp/mockstack/actions/workflows/ci.yml)\n[](https://github.com/promptromp/mockstack/blob/main/LICENSE)\n[](https://pypi.org/project/mockstack/)\n[](https://pypi.org/project/mockstack/)\n\n\nAn API mocking workhorse :racehorse:\n\nEnabling a sane development lifecycle for microservice-oriented architectures and LLM-driven tool chains.\n\nUse mockstack for:\n\n* **Development** :pencil2:. Simulating HTTP-based interactions between a particular component you're developing or debugging locally and multiple other components it depends on during execution of a particular flow. You can create template-based mock responses, simulate creation of resources in a realistic way, as well as proxy to other services using a rich rules DSL. Full request and response metadata and payloads can be observed via OpenTelemetry integration.\n\n* **Integration Testing** :ok_hand:. Creating a consistent environment for running integration tests on a single component, using fixture responses.\n\n* **LLM-powered Workflows** :alien:. Speeding up development and reducing per-token costs of LLM-based workflows and tools for use with frameworks such as [LangChain](https://python.langchain.com/docs/introduction/), [LangGraph](https://www.langchain.com/langgraph) and others. When developing LLM-driven execution graphs. Optional [Ollama](https://ollama.com/) integration allows for realistic mocking of 3rd party LLMs without changing a line of code in your project. In addition, when you want to have a consistent response from a tool while you're tuning prompts or debugging other aspects of a particular trace you can create various fixture responses with varying levels of dynamic content that is template-driven. **mockstack** can give you a solid foundation for this.\n\n* **Chaos Engineering** :boom:. mockstack can simulate various real-world runtime error scenarios such as timeouts, http error codes, and invalid response payloads. This can be a great way to do some upfront [Chaos Monkey](https://github.com/Netflix/chaosmonkey) type of testing on software components.\n\nHighlights include:\n\n* Multiple strategies for handling requests such as [Jinja](https://jinja.palletsprojects.com/en/stable/) template files with intelligent URL request-to-template routing, proxy strategy, and mixed strategies. :game_die:\n* Observability via [OpenTelemetry](https://opentelemetry.io/) integration. Get detailed traces of your sessions instantly reported to backends such as [Grafana](https://grafana.com/), [Jaeger](https://www.jaegertracing.io/), [Zipkin](https://zipkin.io/), etc. :eyes:\n* Configurability via [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) supports customizing behaviour via environment variables and a `.env` file. :flags:\n* Comprehensive unit-tests, linting and formatting coverage as well as vulnerabilities and security scanning with full CI automation to ensure stability and a high-quality codebase for production-grade use. :+1:\n\n\n## Installation\n\nInstall using [uv](https://docs.astral.sh/uv/). This package conforms the concept of a [tool](https://docs.astral.sh/uv/concepts/tools/) and hence can simply install / run with [uvx](https://docs.astral.sh/uv/guides/tools/):\n\n uvx mockstack --help\n\nor install into a persistent environment and add it to the PATH with:\n\n uv tool install mockstack\n\n\n## Usage\n\nSee the [examples](https://github.com/promptromp/mockstack/blob/main/examples/) directory for complete examples with documentation.\n\nAvailable configuration options are [here](https://github.com/promptromp/mockstack/blob/main/mockstack/config.py).\n\nSetting individual options can be done either through an `.env` file, individual environment variables, or command-line arguments.\n\n\nMinimal example to get you started:\n\n```shell\n mkdir -p ~/mockstack-templates\n echo '{\"message\": \"Hello from mockstack!\"}' > ~/mockstack-templates/myservice-api-myresource.j2\n\n export MOCKSTACK__TEMPLATES_DIR=~/mockstack-templates/\n uvx mockstack\n```\n\nYou can then hit `http://localhost:8000/myservice/api/myresource/23faa8cf-5daa-4bcb-8c92-27018b712aa9` (or any other UUID).\n\nThis is of course just the tip of the iceberg.\n\nSee also the included [.env.example](https://github.com/promptromp/mockstack/blob/main/.env.example) for more settings you are likely to find useful. You can copy that file to `.env` and fill in configuration as needed based on the given examples.\n\nOut of the box, you get the following behavior when using the default `filefixtures` strategy:\n\n- The HTTP request `GET /someservice/api/v1/user/c27f5b2b-6e81-420d-a4e4-6426e1c32db8` will try to find `<templates_dir>/someservice-api-v1-user.c27f5b2b-6e81-420d-a4e4-6426e1c32db8.j2`,\n and will fallback to `<templates_dir>/someservice-api-v1-user.j2` (and finally to `index.j2` if exists). These are j2 files that have access to request body context variables.\n- The HTTP request `POST /someservice/api/v2/item` with a JSON body will attempt to intelligently simulate the creation of a resource, returning the appropriate status code and will echo back the provided request resource, after injecting additional metadata fields based on strategy configuration. This is useful for services that expect fields such as `id` and `created_at` on returned created resources.\n- HTTP requests for `DELETE` / `PUT` / `PATCH` are a no-op by default, simply returning the appropriate status code.\n- The HTTP request `POST /someservice/api/v2/embedding_search` will be handled as a search request rather than a resource creation, returning an appropriate http status code and mock results based on user-configurable formatting.\n\nOverall, the design philosophy is that things \"just work\". The framework attempts to intelligently deduce the intent of the request as much as possible and act accordingly,\nwhile leaving room for advanced users to go in and customize behavior using the configuration options.\n\n\n## Testing\n\nInvoke unit-tests with:\n\n uv run python -m pytest\n\nLinting, formatting, static type checks etc. are all managed via [pre-commit](https://pre-commit.com/) hooks. These will run automatically on every commit. You can invoke these manually on all files with:\n\n pre-commit run --all-files\n\n\n## Contributing\n\nIf you are contributing to development, you will want to clone this project, and can then install it locally with:\n\n gh repo clone promptromp/mockstack\n cd mockstack/\n uv sync\n uv pip install -e .\n\nRun in development mode (for live-reload of changes when developing):\n\n uv run uvicorn --factory mockstack.main:create_app --reload\n\nNote that when you run using the uvicorn CLI, you will need to set any configuration via `.env` file or environment variables.\n",
"bugtrack_url": null,
"license": null,
"summary": "An API mocking workhorse",
"version": "0.11.1",
"project_urls": {
"Homepage": "https://github.com/promptromp/mockstack",
"Issues": "https://github.com/promptromp/mockstack/issues"
},
"split_keywords": [
"mocking",
" integration-testing",
" testing",
" microservices",
" api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4199472213c977a876ba59a94be002c34db6a002776647ff5d16295c303e343e",
"md5": "bf695ac0dc9c57e3475d91d2c7ef6395",
"sha256": "0ace4df8311a4358ed5616bb46399dbba74bc132336548983e9833be3ec6d988"
},
"downloads": -1,
"filename": "mockstack-0.11.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf695ac0dc9c57e3475d91d2c7ef6395",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 46551,
"upload_time": "2025-07-11T22:54:57",
"upload_time_iso_8601": "2025-07-11T22:54:57.005998Z",
"url": "https://files.pythonhosted.org/packages/41/99/472213c977a876ba59a94be002c34db6a002776647ff5d16295c303e343e/mockstack-0.11.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "99519e34679874f7f86c0209999d1e2276c073d5b2963cc3e15f25df86bd4f2d",
"md5": "3bbfe06b18c8fbf5a46734a88889c681",
"sha256": "d0a8ec018850366b043896b964f9e996bf5990cdd81b077c9811591f83b437a1"
},
"downloads": -1,
"filename": "mockstack-0.11.1.tar.gz",
"has_sig": false,
"md5_digest": "3bbfe06b18c8fbf5a46734a88889c681",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 895741,
"upload_time": "2025-07-11T22:54:58",
"upload_time_iso_8601": "2025-07-11T22:54:58.824765Z",
"url": "https://files.pythonhosted.org/packages/99/51/9e34679874f7f86c0209999d1e2276c073d5b2963cc3e15f25df86bd4f2d/mockstack-0.11.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 22:54:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "promptromp",
"github_project": "mockstack",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mockstack"
}
JSON
