aimock-pytest 0.1.0__tar.gz

aimock_pytest-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.worktrees/
+.superpowers/
+coverage/
+**/__pycache__/

aimock_pytest-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: aimock-pytest
+Version: 0.1.0
+Summary: pytest fixtures for aimock — mock LLM APIs, MCP, A2A, vector DBs
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Requires-Dist: requests>=2.28; extra == 'test'
+Description-Content-Type: text/markdown
+
+# aimock-pytest
+
+pytest fixtures for [aimock](https://github.com/CopilotKit/llmock) — mock LLM APIs, MCP tools, A2A agents, vector databases, and more.
+
+## Install
+
+```bash
+# 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).
+
+```python
+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
+
+| Fixture          | Scope    | Description                    |
+| ---------------- | -------- | ------------------------------ |
+| `aimock`         | function | Fresh server per test          |
+| `aimock_session` | session  | Shared server across all tests |
+
+## Server API
+
+```python
+# Add fixtures
+aimock.on_message("pattern", {"content": "response"})
+aimock.on_embedding("pattern", {"embedding": [0.1, 0.2]})
+aimock.add_fixture(match={...}, response={...}, chunkSize=10, latency=50)
+aimock.load_fixtures("path/to/fixtures.json")
+
+# 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
+aimock.reset()             # clear fixtures + journal
+```
+
+## CLI Options
+
+```
+--aimock-node PATH       Path to node binary
+--aimock-version VER     aimock npm version (default: 1.7.0)
+```
+
+## Environment Variables
+
+| Variable           | Description                                           |
+| ------------------ | ----------------------------------------------------- |
+| `AIMOCK_NODE_PATH` | Path to node binary                                   |
+| `AIMOCK_CACHE_DIR` | Override cache directory (default: `~/.cache/aimock`) |
+
+## 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:
+
+```bash
+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:
+
+```bash
+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 `publish-pytest.yml` workflow publishes to PyPI on pushes to `main` when
+the version in `pyproject.toml` has not already been published.
+
+## License
+
+MIT

aimock_pytest-0.1.0/README.md

@@ -0,0 +1,124 @@
+# aimock-pytest
+
+pytest fixtures for [aimock](https://github.com/CopilotKit/llmock) — mock LLM APIs, MCP tools, A2A agents, vector databases, and more.
+
+## Install
+
+```bash
+# 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).
+
+```python
+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
+
+| Fixture          | Scope    | Description                    |
+| ---------------- | -------- | ------------------------------ |
+| `aimock`         | function | Fresh server per test          |
+| `aimock_session` | session  | Shared server across all tests |
+
+## Server API
+
+```python
+# Add fixtures
+aimock.on_message("pattern", {"content": "response"})
+aimock.on_embedding("pattern", {"embedding": [0.1, 0.2]})
+aimock.add_fixture(match={...}, response={...}, chunkSize=10, latency=50)
+aimock.load_fixtures("path/to/fixtures.json")
+
+# 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
+aimock.reset()             # clear fixtures + journal
+```
+
+## CLI Options
+
+```
+--aimock-node PATH       Path to node binary
+--aimock-version VER     aimock npm version (default: 1.7.0)
+```
+
+## Environment Variables
+
+| Variable           | Description                                           |
+| ------------------ | ----------------------------------------------------- |
+| `AIMOCK_NODE_PATH` | Path to node binary                                   |
+| `AIMOCK_CACHE_DIR` | Override cache directory (default: `~/.cache/aimock`) |
+
+## 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:
+
+```bash
+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:
+
+```bash
+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 `publish-pytest.yml` workflow publishes to PyPI on pushes to `main` when
+the version in `pyproject.toml` has not already been published.
+
+## License
+
+MIT

aimock_pytest-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aimock-pytest"
+version = "0.1.0"
+description = "pytest fixtures for aimock — mock LLM APIs, MCP, A2A, vector DBs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = ["requests>=2.28"]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0", "requests>=2.28"]
+
+[project.entry-points."pytest11"]
+aimock = "aimock_pytest.plugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aimock_pytest"]

aimock_pytest-0.1.0/src/aimock_pytest/__init__.py

@@ -0,0 +1,5 @@
+from aimock_pytest._version import AIMOCK_VERSION
+from aimock_pytest._server import AIMockServer
+from aimock_pytest._node_manager import NodeManager
+
+__all__ = ["AIMockServer", "NodeManager", "AIMOCK_VERSION"]

aimock_pytest-0.1.0/src/aimock_pytest/_node_manager.py

@@ -0,0 +1,189 @@
+"""Handles Node.js detection and npm tarball caching for aimock."""
+
+from __future__ import annotations
+
+try:
+    import fcntl
+except ImportError:
+    fcntl = None  # Windows — file locking not available
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+from pathlib import Path
+
+import requests
+
+from aimock_pytest._version import AIMOCK_VERSION
+
+
+class NodeManager:
+    """Manages node binary detection and aimock npm package caching."""
+
+    # Use @copilotkit/aimock since that's the published npm package name.
+    _NPM_TARBALL_URL = (
+        "https://registry.npmjs.org/@copilotkit/aimock/-/aimock-{version}.tgz"
+    )
+    _MIN_NODE_MAJOR = 20
+
+    def __init__(
+        self,
+        version: str = AIMOCK_VERSION,
+        cache_dir: str | Path | None = None,
+        node_path: str | None = None,
+    ) -> None:
+        self.version = version
+        self._custom_cache_dir = Path(cache_dir) if cache_dir else None
+        self._custom_node_path = node_path
+
+    # ── public API ──────────────────────────────────────────────────────
+
+    def ensure_installed(self) -> Path:
+        """Return path to the aimock ``dist/cli.js``.  Downloads if needed.
+
+        If ``AIMOCK_CLI_PATH`` is set, returns that path directly (bypassing
+        the npm tarball download entirely).  This is used for local development
+        and CI where we test against the repo's own build.
+        """
+        env_cli = os.environ.get("AIMOCK_CLI_PATH")
+        if env_cli:
+            p = Path(env_cli)
+            if not p.is_file():
+                raise RuntimeError(
+                    f"AIMOCK_CLI_PATH is set to {env_cli!r} but the file does not exist"
+                )
+            return p
+
+        cli_js = self._package_dir() / "dist" / "cli.js"
+        if cli_js.is_file():
+            return cli_js
+
+        self._download_tarball()
+
+        if not cli_js.is_file():
+            raise RuntimeError(
+                f"Expected cli.js at {cli_js} but it was not found after extraction"
+            )
+        return cli_js
+
+    def find_node(self) -> str:
+        """Find the node binary.  Checks ``AIMOCK_NODE_PATH`` env, the
+        constructor override, then ``PATH``."""
+        # Explicit override from constructor
+        if self._custom_node_path:
+            self._verify_node(self._custom_node_path)
+            return self._custom_node_path
+
+        # Environment variable
+        env_path = os.environ.get("AIMOCK_NODE_PATH")
+        if env_path:
+            self._verify_node(env_path)
+            return env_path
+
+        # PATH lookup
+        node = shutil.which("node")
+        if node is None:
+            raise RuntimeError(
+                "node is not installed or not on PATH.  "
+                "Install Node.js >= 20 or set AIMOCK_NODE_PATH."
+            )
+        self._verify_node(node)
+        return node
+
+    # ── internal ────────────────────────────────────────────────────────
+
+    def _cache_dir(self) -> Path:
+        """``~/.cache/aimock/{version}/`` or ``AIMOCK_CACHE_DIR`` env."""
+        base: Path
+        if self._custom_cache_dir:
+            base = self._custom_cache_dir
+        else:
+            env = os.environ.get("AIMOCK_CACHE_DIR")
+            if env:
+                base = Path(env)
+            else:
+                base = Path.home() / ".cache" / "aimock"
+        return base / self.version
+
+    def _package_dir(self) -> Path:
+        """The extracted package directory inside the cache."""
+        return self._cache_dir() / "package"
+
+    def _download_tarball(self) -> None:
+        """Download the @copilotkit/aimock tarball from the npm registry and
+        extract it into the cache directory.
+
+        Uses file-locking (``fcntl.flock``) so parallel pytest-xdist workers
+        don't race.  On Windows where fcntl is unavailable, locking is skipped.
+        """
+        cache = self._cache_dir()
+        cache.mkdir(parents=True, exist_ok=True)
+
+        _fcntl = fcntl  # local binding for type narrowing
+        if _fcntl is not None:
+            lock_path = cache / ".lock"
+            lock_fd = open(lock_path, "w")
+            _fcntl.flock(lock_fd, _fcntl.LOCK_EX)
+        else:
+            lock_fd = None
+
+        try:
+            # Double-check after acquiring lock — another worker may have
+            # finished the download while we waited.
+            if (self._package_dir() / "dist" / "cli.js").is_file():
+                return
+
+            url = self._NPM_TARBALL_URL.format(version=self.version)
+            resp = requests.get(url, timeout=60, stream=True)
+            resp.raise_for_status()
+
+            with tempfile.NamedTemporaryFile(suffix=".tgz", delete=False) as tmp:
+                for chunk in resp.iter_content(chunk_size=65536):
+                    tmp.write(chunk)
+                tmp_path = tmp.name
+
+            try:
+                # npm tarballs always contain a top-level ``package/`` dir.
+                with tarfile.open(tmp_path, "r:gz") as tar:
+                    if sys.version_info >= (3, 12):
+                        tar.extractall(path=str(cache), filter="data")  # type: ignore[call-overload]
+                    else:
+                        tar.extractall(path=str(cache))
+            finally:
+                os.unlink(tmp_path)
+        finally:
+            if lock_fd is not None and _fcntl is not None:
+                _fcntl.flock(lock_fd, _fcntl.LOCK_UN)
+                lock_fd.close()
+
+    def _verify_node(self, node_path: str) -> None:
+        """Verify the node binary exists and is >= the minimum version."""
+        try:
+            result = subprocess.run(
+                [node_path, "--version"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        except FileNotFoundError:
+            raise RuntimeError(f"node binary not found at {node_path}")
+        except subprocess.TimeoutExpired:
+            raise RuntimeError(f"node --version timed out for {node_path}")
+
+        version_str = result.stdout.strip()
+        match = re.match(r"v(\d+)\.", version_str)
+        if not match:
+            raise RuntimeError(
+                f"Could not parse node version from: {version_str!r}"
+            )
+
+        major = int(match.group(1))
+        if major < self._MIN_NODE_MAJOR:
+            raise RuntimeError(
+                f"Node.js >= {self._MIN_NODE_MAJOR} required, "
+                f"found {version_str} at {node_path}"
+            )

aimock_pytest-0.1.0/src/aimock_pytest/_server.py

@@ -0,0 +1,270 @@
+"""Manages the aimock subprocess and communicates via the /__aimock/* control API."""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import re
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from aimock_pytest._node_manager import NodeManager
+
+
+class AIMockServer:
+    """Wraps a running aimock Node.js process and exposes the control API as
+    Python methods."""
+
+    def __init__(
+        self,
+        node_manager: NodeManager,
+        port: int = 0,
+        fixtures_path: str | Path | None = None,
+    ) -> None:
+        self.node_manager = node_manager
+        self.port = port
+        self.fixtures_path = fixtures_path
+        self._proc: subprocess.Popen[str] | None = None
+        self._base_url: str | None = None
+
+    # ── lifecycle ───────────────────────────────────────────────────────
+
+    def start(self) -> str:
+        """Start the aimock subprocess, wait for it to be ready, and return
+        the base URL (e.g. ``http://127.0.0.1:54321``)."""
+        env_cli = os.environ.get("AIMOCK_CLI_PATH")
+        if env_cli:
+            cli_path = Path(env_cli)
+            if not cli_path.is_file():
+                raise RuntimeError(
+                    f"AIMOCK_CLI_PATH is set to {env_cli!r} but the file does not exist"
+                )
+        else:
+            cli_path = self.node_manager.ensure_installed()
+        node = self.node_manager.find_node()
+
+        # The CLI requires a valid fixtures path (exits 1 if not found).
+        # Use the provided path, or create an empty temp directory.
+        if self.fixtures_path:
+            fixtures_arg = str(self.fixtures_path)
+        else:
+            import tempfile
+
+            self._tmp_fixtures = tempfile.mkdtemp(prefix="aimock-fixtures-")
+            fixtures_arg = self._tmp_fixtures
+
+        cmd = [
+            node,
+            str(cli_path),
+            "--port",
+            str(self.port),
+            "--log-level",
+            "info",
+            "--fixtures",
+            fixtures_arg,
+        ]
+
+        self._proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+        atexit.register(self.stop)
+
+        self._base_url = self._wait_for_ready(timeout=15)
+        return self._base_url
+
+    def stop(self) -> None:
+        """Terminate the aimock subprocess."""
+        if self._proc is not None:
+            try:
+                self._proc.terminate()
+                self._proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self._proc.kill()
+                self._proc.wait()
+            except Exception:
+                try:
+                    self._proc.kill()
+                except Exception:
+                    pass
+            finally:
+                self._proc = None
+        # Clean up temp fixtures directory if we created one
+        if hasattr(self, "_tmp_fixtures") and self._tmp_fixtures:
+            import shutil
+
+            shutil.rmtree(self._tmp_fixtures, ignore_errors=True)
+            self._tmp_fixtures = None
+        atexit.unregister(self.stop)
+
+    @property
+    def base_url(self) -> str:
+        """The base URL of the running aimock server."""
+        if self._base_url is None:
+            raise RuntimeError("Server has not been started yet")
+        return self._base_url
+
+    @property
+    def url(self) -> str:
+        """Alias for :attr:`base_url`."""
+        return self.base_url
+
+    # ── control API methods ─────────────────────────────────────────────
+
+    def add_fixture(
+        self,
+        match: dict[str, Any],
+        response: dict[str, Any],
+        **opts: Any,
+    ) -> None:
+        """Add a single fixture via ``POST /__aimock/fixtures``."""
+        fixture: dict[str, Any] = {"match": match, "response": response}
+        if opts:
+            fixture["opts"] = opts
+        r = requests.post(
+            f"{self.base_url}/__aimock/fixtures",
+            json={"fixtures": [fixture]},
+            timeout=5,
+        )
+        r.raise_for_status()
+
+    def on_message(
+        self,
+        pattern: str,
+        response: dict[str, Any],
+        **opts: Any,
+    ) -> AIMockServer:
+        """Convenience: add a fixture matching ``userMessage``."""
+        self.add_fixture({"userMessage": pattern}, response, **opts)
+        return self
+
+    def on_embedding(
+        self,
+        pattern: str,
+        response: dict[str, Any],
+    ) -> AIMockServer:
+        """Convenience: add a fixture matching ``inputText``."""
+        self.add_fixture({"inputText": pattern}, response)
+        return self
+
+    def load_fixtures(self, path: str | Path) -> AIMockServer:
+        """Read a JSON fixture file and POST its contents to the control API.
+
+        The file must contain either:
+        - A JSON object with a ``"fixtures"`` key (list of fixtures)
+        - A JSON array of fixture objects
+        - A single fixture object (wrapped into a list automatically)
+
+        Raises :class:`ValueError` if the parsed JSON is not a dict or list.
+        """
+        with open(path) as f:
+            data = json.load(f)
+
+        if isinstance(data, list):
+            fixtures = data
+        elif isinstance(data, dict) and "fixtures" in data:
+            fixtures = data["fixtures"]
+        elif isinstance(data, dict):
+            fixtures = [data]
+        else:
+            raise ValueError(
+                f"Invalid fixture file {path}: expected a JSON object or array, "
+                f"got {type(data).__name__}"
+            )
+
+        r = requests.post(
+            f"{self.base_url}/__aimock/fixtures",
+            json={"fixtures": fixtures},
+            timeout=5,
+        )
+        r.raise_for_status()
+        return self
+
+    def clear_fixtures(self) -> AIMockServer:
+        """Delete all fixtures via ``DELETE /__aimock/fixtures``."""
+        requests.delete(
+            f"{self.base_url}/__aimock/fixtures", timeout=5
+        ).raise_for_status()
+        return self
+
+    def reset(self) -> AIMockServer:
+        """Clear fixtures, journal, and match counts via ``POST /__aimock/reset``."""
+        requests.post(
+            f"{self.base_url}/__aimock/reset", timeout=5
+        ).raise_for_status()
+        return self
+
+    def get_journal(self) -> list[dict[str, Any]]:
+        """Return all recorded journal entries."""
+        r = requests.get(f"{self.base_url}/__aimock/journal", timeout=5)
+        r.raise_for_status()
+        return r.json()  # type: ignore[no-any-return]
+
+    def get_last_request(self) -> dict[str, Any] | None:
+        """Return the most recent journal entry, or ``None``."""
+        journal = self.get_journal()
+        return journal[-1] if journal else None
+
+    def next_error(
+        self,
+        status: int,
+        body: dict[str, Any] | None = None,
+    ) -> AIMockServer:
+        """Queue a one-shot error via ``POST /__aimock/error``."""
+        requests.post(
+            f"{self.base_url}/__aimock/error",
+            json={"status": status, "body": body or {}},
+            timeout=5,
+        ).raise_for_status()
+        return self
+
+    # ── internal ────────────────────────────────────────────────────────
+
+    def _wait_for_ready(self, timeout: int = 15) -> str:
+        """Read stdout lines until we see the listening URL, then verify via
+        health check."""
+        assert self._proc is not None
+        assert self._proc.stdout is not None
+
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            # Check if process exited
+            if self._proc.poll() is not None:
+                remaining = ""
+                if self._proc.stdout:
+                    remaining = self._proc.stdout.read()
+                raise RuntimeError(
+                    f"aimock process exited with code {self._proc.returncode}"
+                    f"{': ' + remaining if remaining else ''}"
+                )
+
+            line = self._proc.stdout.readline()
+            if not line:
+                continue
+
+            m = re.search(r"listening on (http://\S+)", line)
+            if m:
+                url = m.group(1).rstrip("/")
+                # Verify health endpoint is reachable
+                for _ in range(30):
+                    try:
+                        r = requests.get(
+                            f"{url}/__aimock/health", timeout=0.5
+                        )
+                        if r.status_code == 200:
+                            return url
+                        time.sleep(0.1)
+                    except requests.RequestException:
+                        time.sleep(0.1)
+                raise RuntimeError(
+                    "aimock started but health check failed after 3 seconds"
+                )
+
+        raise RuntimeError(f"aimock did not start within {timeout}s")

aimock_pytest-0.1.0/src/aimock_pytest/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the aimock package version."""
+
+AIMOCK_VERSION = "1.7.0"

aimock_pytest-0.1.0/src/aimock_pytest/plugin.py

@@ -0,0 +1,55 @@
+"""pytest plugin — registers ``aimock`` and ``aimock_session`` fixtures.
+
+Auto-discovered by pytest via the ``pytest11`` entry point in pyproject.toml.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from aimock_pytest._version import AIMOCK_VERSION
+from aimock_pytest._node_manager import NodeManager
+from aimock_pytest._server import AIMockServer
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("aimock", "aimock mock server options")
+    group.addoption(
+        "--aimock-node",
+        default=None,
+        help="Path to node binary (default: auto-detect from PATH)",
+    )
+    group.addoption(
+        "--aimock-version",
+        default=AIMOCK_VERSION,
+        help=f"aimock npm package version to use (default: {AIMOCK_VERSION})",
+    )
+
+
+@pytest.fixture(scope="session")
+def _aimock_node_manager(request: pytest.FixtureRequest) -> NodeManager:
+    """Session-scoped :class:`NodeManager` — shared across all fixtures."""
+    return NodeManager(
+        version=request.config.getoption("--aimock-version"),
+        node_path=request.config.getoption("--aimock-node"),
+    )
+
+
+@pytest.fixture
+def aimock(_aimock_node_manager: NodeManager) -> AIMockServer:
+    """Function-scoped aimock server.  A fresh server is started for every
+    test that requests this fixture, and torn down afterwards."""
+    server = AIMockServer(_aimock_node_manager, port=0)
+    server.start()
+    yield server  # type: ignore[misc]
+    server.stop()
+
+
+@pytest.fixture(scope="session")
+def aimock_session(_aimock_node_manager: NodeManager) -> AIMockServer:
+    """Session-scoped aimock server.  One server is shared across all tests
+    that request this fixture."""
+    server = AIMockServer(_aimock_node_manager, port=0)
+    server.start()
+    yield server  # type: ignore[misc]
+    server.stop()

aimock_pytest-0.1.0/tests/conftest.py

@@ -0,0 +1,14 @@
+# The aimock plugin is auto-registered via the pytest11 entry point.
+# This file exists so pytest recognises this directory as a test root.
+
+import os
+import pathlib
+
+# Auto-detect local repo build for development.  If AIMOCK_CLI_PATH is not
+# already set and a built cli.js exists at the repo root, use it directly
+# so tests run against the local build instead of downloading from npm.
+REPO_ROOT = pathlib.Path(__file__).parent.parent.parent.parent
+LOCAL_CLI = REPO_ROOT / "dist" / "cli.js"
+
+if LOCAL_CLI.exists() and "AIMOCK_CLI_PATH" not in os.environ:
+    os.environ["AIMOCK_CLI_PATH"] = str(LOCAL_CLI)

aimock_pytest-0.1.0/tests/fixtures/hello.json

@@ -0,0 +1,8 @@
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "hello" },
+      "response": { "content": "Hello from aimock!" }
+    }
+  ]
+}

aimock_pytest-0.1.0/tests/test_basic.py

@@ -0,0 +1,69 @@
+import requests
+
+# ── Session-scoped fixture tests ──────────────────────────────────────────
+# These two tests share a single aimock_session instance, verifying that the
+# session-scoped fixture persists state across test functions.
+
+_session_url: str | None = None
+
+
+def test_session_fixture_starts(aimock_session):
+    """aimock_session starts and its URL persists across tests."""
+    global _session_url
+    r = requests.get(f"{aimock_session.base_url}/__aimock/health")
+    assert r.status_code == 200
+    _session_url = aimock_session.base_url
+
+
+def test_session_fixture_persists(aimock_session):
+    """aimock_session is the same server instance as the previous test."""
+    # The base_url should be identical — same process, same port.
+    assert aimock_session.base_url == _session_url
+
+    # Fixtures added in a previous test would still be present (session scope
+    # does NOT auto-reset between tests).  Verify the server is still alive.
+    r = requests.get(f"{aimock_session.base_url}/__aimock/health")
+    assert r.status_code == 200
+
+
+# ── Function-scoped fixture tests ────────────────────────────────────────
+
+
+def test_server_starts(aimock):
+    """Server starts and health check works."""
+    r = requests.get(f"{aimock.base_url}/__aimock/health")
+    assert r.status_code == 200
+    assert r.json()["status"] == "ok"
+
+
+def test_add_fixture_and_match(aimock):
+    """Add a fixture via control API, then hit it."""
+    aimock.on_message("hello", {"content": "Hi there!"})
+
+    r = requests.post(
+        f"{aimock.base_url}/v1/chat/completions",
+        json={
+            "model": "gpt-4",
+            "messages": [{"role": "user", "content": "hello"}],
+        },
+    )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["choices"][0]["message"]["content"] == "Hi there!"
+
+
+def test_reset_clears_fixtures(aimock):
+    """Reset clears fixtures and journal."""
+    aimock.on_message("test", {"content": "response"})
+    aimock.reset()
+
+    r = requests.post(
+        f"{aimock.base_url}/v1/chat/completions",
+        json={
+            "model": "gpt-4",
+            "messages": [{"role": "user", "content": "test"}],
+        },
+    )
+    # aimock returns 404 when no fixture matches the request, confirming
+    # that the previously-registered fixture was cleared by reset().
+    assert r.status_code == 404

aimock_pytest-0.1.0/tests/test_fixtures.py

@@ -0,0 +1,60 @@
+import os
+
+import requests
+
+
+def test_load_fixture_file(aimock):
+    """Load fixtures from a JSON file."""
+    fixture_path = os.path.join(os.path.dirname(__file__), "fixtures", "hello.json")
+    aimock.load_fixtures(fixture_path)
+
+    r = requests.post(
+        f"{aimock.base_url}/v1/chat/completions",
+        json={
+            "model": "gpt-4",
+            "messages": [{"role": "user", "content": "hello"}],
+        },
+    )
+    assert r.status_code == 200
+    assert "Hello from aimock" in r.json()["choices"][0]["message"]["content"]
+
+
+def test_journal_records_requests(aimock):
+    """Journal captures all requests."""
+    aimock.on_message("journal-test", {"content": "ok"})
+
+    requests.post(
+        f"{aimock.base_url}/v1/chat/completions",
+        json={
+            "model": "gpt-4",
+            "messages": [{"role": "user", "content": "journal-test"}],
+        },
+    )
+
+    journal = aimock.get_journal()
+    assert len(journal) >= 1
+
+
+def test_one_shot_error(aimock):
+    """Queue a one-shot error."""
+    aimock.on_message("error-test", {"content": "ok"})
+    aimock.next_error(429, {"message": "Rate limited", "type": "rate_limit_error"})
+
+    r1 = requests.post(
+        f"{aimock.base_url}/v1/chat/completions",
+        json={
+            "model": "gpt-4",
+            "messages": [{"role": "user", "content": "error-test"}],
+        },
+    )
+    assert r1.status_code == 429
+
+    # Second request should succeed
+    r2 = requests.post(
+        f"{aimock.base_url}/v1/chat/completions",
+        json={
+            "model": "gpt-4",
+            "messages": [{"role": "user", "content": "error-test"}],
+        },
+    )
+    assert r2.status_code == 200