Metadata-Version: 2.4
Name: mocktown
Version: 1.0.0
Summary: Programmable mock internet for integration testing - Official Python SDK
Author-email: Vikas Budde <vikas.budde@hotmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/pisigmac/MockTown
Project-URL: Documentation, https://github.com/pisigmac/MockTown/blob/main/docs/SDK.md
Project-URL: Repository, https://github.com/pisigmac/MockTown.git
Keywords: mock,testing,stripe,s3,twilio,mocktown,integration-testing,pytest
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Mocking
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0

# 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

```bash
pip install mocktown
```

---

## Quick Start

### Using the Context Manager (Recommended)

```python
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:
  ```python
  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

```python
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:

| Variable | Description | Default |
|---|---|---|
| `MOCKTOWN_API_KEY` | Bearer API key | — |
| `MOCKTOWN_BASE_URL` | Core server API endpoint | `http://localhost:8080` |
| `MOCKTOWN_TIMEOUT` | Request timeout in seconds | `30` |

---

## License

MIT License. Copyright (c) 2026 Vikas Budde.
