wiremock

wiremock (Python WireMock) is a Python library for interacting with a WireMock instance — the popular Java-based HTTP API mocking tool — from within a Python project. It provides a full REST API client for a standalone WireMock server (stubbing, request verification, scenarios, near-misses, settings) plus a Testcontainers Python module that spins up a disposable WireMock container for a test run.

It’s aimed at teams writing integration or contract tests in Python that need to mock an HTTP dependency with WireMock’s request-matching and stateful-scenario features rather than a pure-Python mocking library.

What You Get

• A REST API client (wiremock.client) for a standalone WireMock Java server covering mappings, requests, scenarios, near-misses, and settings
• A Testcontainers Python integration (wiremock.testing.testcontainer) that starts and stops a WireMock Docker container per test run
• A bundled wiremock-standalone JAR runner (wiremock.server.server) for launching a local WireMock process without Docker
• A structured exception hierarchy (not_found, invalid_input, forbidden, api_unavailable, etc.) mapped from WireMock’s Admin API error responses
• Example projects demonstrating both the Testcontainers and standalone-Java-server workflows against a sample service

Common Use Cases

• Mocking a third-party HTTP API in Python integration tests so the test suite doesn’t depend on the real service being available
• Verifying that application code sent the expected HTTP requests (headers, body, query params) by querying WireMock’s recorded request log through the client
• Simulating multi-step or stateful API interactions with WireMock’s scenario/state-machine features, driven from Python test setup
• Running WireMock as a disposable Testcontainers-managed dependency in CI pipelines without managing the server lifecycle by hand

Under The Hood

Architecture The package is organized around a thin wiremock.base.base_resource/base_entity layer that all Admin API resource wrappers build on, concrete resource modules under wiremock/resources/ (mappings, requests, scenarios, near_misses, settings) that model each WireMock Admin API endpoint group, wiremock/server/server.py for launching the bundled standalone JAR, and wiremock/testing/testcontainer.py for wrapping WireMock as a Testcontainers-managed Docker dependency — giving three ways to reach a running WireMock instance (external server, local JAR, or container) behind the same client API.

Tech Stack It’s a pure-Python (3.9–3.13) library with requests as its only hard runtime dependency, an optional testing extra pulling in docker and testcontainers for the container-based workflow, and it bundles a wiremock-standalone-2.35.1.jar directly in the package for the local-server launch path; the project uses uv/pyproject.toml for dependency management and tox for multi-version test runs.

Code Quality The repository has a tests/ directory (7+ entries) plus dedicated examples/ projects exercising both the Testcontainers and standalone-server paths end-to-end, a granular custom exception hierarchy for API error handling, and black formatting configured in the dev dependency group; GitHub activity has slowed over the last year (last push mid-2025), so recently opened WireMock server features may lag behind what the Python client exposes.

API Design The client follows a resource-per-module pattern mirroring WireMock’s own Admin API structure (mappings, scenarios, near-misses, settings), keeping the mental model close to WireMock’s official documentation, while the Testcontainers helper reduces the common case (“give me a running WireMock for this test”) to a single context-manager-style call.