MockTown Python SDK

A programmable mock internet for integration testing.

MockTown lets you spin up stateful, scenario-driven mock services (Stripe, AWS S3, Twilio, etc.) on dedicated ports for reproducible, zero-flakiness testing.

Installation

pip install mocktown

Quick Start

Using the Context Manager (Recommended)

from mocktown import MockTown

mt = MockTown(api_key="mt_your_api_key", base_url="http://localhost:8080")

with mt.session("checkout-test") as session:
    # Spin up mock Stripe on port 9101
    stripe_mock = session.start_mock("stripe", port=9101)

    # Point your application / test client to MockTown
    import stripe
    stripe.api_key = "sk_test_fake"
    stripe.api_base = stripe_mock.url  # "http://localhost:9101"

    # Run your application logic
    customer = stripe.Customer.create(email="test@example.com")
    assert customer.id.startswith("cus_")

    # Inspect internal mock state
    assert len(stripe_mock.state["customers"]) == 1
    assert stripe_mock.state["customers"][0]["email"] == "test@example.com"

Features

• Context Manager: Sessions and mocks automatically clean up when your test block finishes.
• State Inspection: Inspect internal service state directly via .state property (e.g. mock.state["customers"], mock.state["objects"]).
• Scenario Simulation: Test retry logic, chaos injection, latency delays, and fixed failure responses:

  session.start_mock("stripe", scenario="payment_failure_retry", port=9101)
  

• Record & Replay: Capture live API interactions and replay them in deterministic CI environments.
• Verification Assertions: Run automated assertion suites against mock logs.

Pytest Fixture Example

import pytest
from mocktown import MockTown

@pytest.fixture(scope="session")
def mt():
    return MockTown()

@pytest.fixture
def mock_stripe(mt):
    with mt.session("test-stripe-session") as session:
        mock = session.start_mock("stripe", port=9101)
        yield mock

Configuration

The SDK can be configured programmatically or via environment variables:

License

MIT License. Copyright (c) 2026 Vikas Budde.