HKOpenAI Live Tests Template

Shared pytest fixtures and conftest.py template for the live integration tests in the hkopenai/hk-*-mcp-server family.

The live_tests/ directory in each MCP server hits real upstream APIs (HKMA, HKO, AOF, IRD, etc.). Running those tests back-to-back without any throttle trips the upstream rate-limiter and produces spurious 502/429 errors. The throttle autouse fixture in this template adds a short, configurable pause before every live test so a full pytest live_tests run stays well below typical per-second request budgets.

Usage

Each MCP server should drop a live_tests/conftest.py that mirrors the content of templates/conftest.py in this repo:

# live_tests/conftest.py
"""Shared fixtures for live integration tests.

The throttle fixture sleeps for `LIVE_TEST_THROTTLE_S` seconds (default 1.5)
before every live test to avoid tripping upstream rate limits.
"""
import os
import time
import pytest

DEFAULT_THROTTLE_SECONDS = float(os.environ.get("LIVE_TEST_THROTTLE_S", "1.5"))


@pytest.fixture(autouse=True)
def throttle():
    time.sleep(DEFAULT_THROTTLE_SECONDS)

Override the delay with an environment variable when running against tighter rate-limit windows or slower links:

LIVE_TEST_THROTTLE_S=3 pytest live_tests

Files

• templates/conftest.py — the canonical copy to drop into each live_tests/conftest.py.
• docs/why.md — background and design notes.

Adopting this template

If you maintain a hk-*-mcp-server and want to add the throttle, copy templates/conftest.py into <your-repo>/live_tests/conftest.py. No code changes are required inside the existing test files because the fixture is autouse=True.

License

MIT