aimock-pytest

pytest fixtures for aimock — mock LLM APIs, MCP tools, A2A agents, vector databases, and more.

Install

# From PyPI (once published):
pip install aimock-pytest

# Local install from a repo checkout:
pip install ./packages/aimock-pytest

Requires: Node.js >= 20 on PATH (or set AIMOCK_NODE_PATH).

Quick Start

The plugin auto-registers two fixtures: aimock (function-scoped) and aimock_session (session-scoped).

def test_hello(aimock):
    import requests

    # Set up a fixture
    aimock.on_message("hello", {"content": "Hi there!"})

    # Point your SDK at aimock
    r = requests.post(
        f"{aimock.base_url}/v1/chat/completions",
        json={
            "model": "gpt-4",
            "messages": [{"role": "user", "content": "hello"}],
        },
    )
    assert r.json()["choices"][0]["message"]["content"] == "Hi there!"

Fixtures

Server API

# Add fixtures
aimock.on_message("pattern", {"content": "response"})
aimock.on_embedding("pattern", {"embedding": [0.1, 0.2]})
aimock.on_system_message("name=Atai", {"content": "..."}, user_message="who am I")
# Array form: all substrings must appear in the joined system text (AND)
aimock.on_system_message(["name=Atai", "tz=PST"], {"content": "..."})
aimock.add_fixture(match={...}, response={...}, chunkSize=10, latency=50)
# Ordered blocks: stream a tool call before text (tool-first / interleaved).
# A blocks-only response is first-class — see /fixtures#ordered-blocks
aimock.add_fixture(match={...}, response={"blocks": [
    {"type": "toolCall", "name": "get_weather", "arguments": {"city": "SF"}},
    {"type": "text", "text": "Here is the weather."},
]})
aimock.load_fixtures("path/to/fixtures.json")  # also loads the file's mcpFakes

# Inspect
aimock.get_journal()       # list of all recorded requests
aimock.get_last_request()  # most recent request or None

# Error injection
aimock.next_error(429, {"message": "Rate limited"})

# Reset
aimock.clear_fixtures()    # remove all fixtures, nothing else
aimock.reset()             # full reset: fixtures, journal entries + match-counts,
                           # video/fal job state, Gemini counters
aimock.reset_journal()     # clear only the request journal (fixtures preserved)
aimock.reset_fixtures()    # alias for reset() — a full reset, despite the name

MCP fakes

load_fixtures posts a file's mcpFakes key (see MCP scenario fakes) next to its fixtures. A file may hold only mcpFakes. reset(), reset_fixtures() and clear_fixtures() also unload the fakes.

When the server rejects a file with HTTP 400, load_fixtures raises requests.HTTPError with the message aimock rejected fixtures from <path>: <error>, followed by one line for each item of details. When the file has mcpFakes and the aimock server is a release without MCP fakes, load_fixtures raises RuntimeError (aimock server too old for mcpFakes: ...) and adds nothing from the file.

CLI Options

--aimock-node PATH       Path to node binary
--aimock-version VER     aimock npm version (default: 1.44.0)
--aimock-api-key KEY     Inbound API key for the aimock child process

API-key validation

Pass pytest --aimock-api-key test-key to protect the aimock child. The helper sends this key on all control API calls, and the child receives it through AIMOCK_API_KEYS, never through process arguments. Direct client calls must use Authorization: Bearer test-key. For direct construction, use AIMockServer(node_manager, api_key="test-key").

Environment Variables

Development

Prerequisites

• Node.js >= 20
• Python >= 3.10
• pnpm

Running tests locally

Build the npm package first, then point AIMOCK_CLI_PATH at the local build:

pnpm install && pnpm run build
AIMOCK_CLI_PATH=../../dist/cli.js pytest tests/ -v

If you install the test dependencies and run from the packages/aimock-pytest/ directory, conftest.py will auto-detect the local build so you can omit the env var:

pip install ./packages/aimock-pytest[test]
cd packages/aimock-pytest
pytest tests/ -v

How CI works

The test-pytest.yml workflow:

1. Checks out the repo
2. Builds the TypeScript package (pnpm run build)
3. Sets AIMOCK_CLI_PATH to the local dist/cli.js
4. Installs aimock-pytest[test] and runs pytest

Tests run across a matrix of Python 3.10--3.13 and Node 20/22.

The Release workflow publishes aimock-pytest to PyPI after its npm publish job succeeds. Its PyPI job verifies that the AIMOCK_VERSION pin exists on npm before building a wheel, so npm publication completes before the corresponding aimock-pytest release.

License

MIT