Mock any API for integration tests with your OpenAPI spec

Install APIGhost

APIGhost is a Python CLI tool. Install it into your project's virtualenv or globally:

pip install git+https://github.com/Coding-Dev-Tools/apighost.git

Verify the install:

apighost --version

Point it at your OpenAPI spec

Start a mock server from any OpenAPI 3.x spec file or URL:

# From a local file
apighost serve api/openapi.yaml

# From a URL
apighost serve https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml

The server starts on port 8080 by default. Every endpoint defined in the spec is immediately available, returning realistic fake data generated from your schema property names.

Test error paths with scenario switching

Edge-case testing usually means either mocking at the unit level or using a staging environment that may not support injecting errors. APIGhost's scenario system handles this without touching your test code:

# Start in the built-in "error" scenario
apighost serve api/openapi.yaml --scenario error

# Create a custom scenario for rate limiting
apighost scenario create rate-limited -d "Simulate 429 responses"
apighost scenario edit rate-limited "GET /users" --status 429 --body '{"error":"rate_limit_exceeded"}'

# Run with the custom scenario
apighost serve api/openapi.yaml --scenario rate-limited

Record once, replay forever (VCR mode)

If you have a real API available during setup, record its responses once and replay them in every subsequent test run. Responses are identical on every replay — no flakiness from network variance or rate limits:

# Record a session against the real API
apighost record api/openapi.yaml --output my-api-cassette

# Replay the cassette in CI — no network access needed
apighost replay my-api-cassette -p 8080

Cassettes are stored in ~/.apighost/cassettes/ as JSON and can be committed to version control alongside your test suite.

Wire it into GitHub Actions

Start the mock server as a background service before your test step. A short sleep lets the server bind before requests arrive:

name: Integration tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install git+https://github.com/Coding-Dev-Tools/apighost.git

      - name: Start mock API server
        run: |
          apighost serve api/openapi.yaml -p 8080 &
          sleep 2

      - name: Run integration tests
        run: pytest tests/integration/
        env:
          API_BASE_URL: http://localhost:8080

For deterministic runs (zero network access after the first setup), use apighost replay instead of apighost serve and commit the cassette to the repo.

Point your test client at localhost:8080

Configure your test suite's HTTP client to use the mock server URL instead of the real API. Most frameworks support this via an environment variable:

# pytest (Python)
import os
import httpx

BASE_URL = os.getenv("API_BASE_URL", "http://localhost:8080")

def test_list_users():
    resp = httpx.get(f"{BASE_URL}/users")
    assert resp.status_code == 200
    data = resp.json()
    assert isinstance(data, list)

// Jest (Node.js / TypeScript)
const BASE_URL = process.env.API_BASE_URL ?? "http://localhost:8080";

test("GET /users returns array", async () => {
  const res = await fetch(`${BASE_URL}/users`);
  expect(res.status).toBe(200);
  const data = await res.json();
  expect(Array.isArray(data)).toBe(true);
});