From 295f7bd4686a350ba4b16723adba91952b2cf4cc Mon Sep 17 00:00:00 2001
From: Larry-Osakwe <larryosak@gmail.com>
Date: Fri, 6 Feb 2026 16:15:54 -0800
Subject: [PATCH] docs(mcp): add test infrastructure documentation

---
 packages/mcp/tests/README.md | 47 ++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 packages/mcp/tests/README.md

diff --git a/packages/mcp/tests/README.md b/packages/mcp/tests/README.md
new file mode 100644
index 0000000..c725c63
--- /dev/null
+++ b/packages/mcp/tests/README.md
@@ -0,0 +1,47 @@
+# Test Infrastructure
+
+## Running Tests
+
+### Default Tests (Mocked)
+
+Run all tests without any environment variables:
+
+```bash
+uv run pytest packages/mcp/tests -v
+```
+
+These tests use mock fixtures and don't require real Keycard infrastructure.
+
+### Interactive Tests (Real Infrastructure)
+
+Tests in `integration/interactive/` require a real Keycard zone:
+
+```bash
+export KEYCARD_ZONE_URL="https://your-zone.keycard.cloud"
+export OPENAI_API_KEY="sk-..."  # Optional, for agent tests
+export RUN_INTERACTIVE_TESTS=1
+
+uv run pytest packages/mcp/tests/integration/interactive/ -v -s
+```
+
+## Test Organization
+
+| Directory | Purpose | Infrastructure |
+|-----------|---------|----------------|
+| `keycardai/` | Unit tests | Mocked |
+| `integration/e2e/` | End-to-end flows | Mocked |
+| `integration/interactive/` | Manual OAuth flows | Real Keycard |
+
+## Environment Variables
+
+| Variable | Required For | Description |
+|----------|--------------|-------------|
+| `RUN_INTERACTIVE_TESTS` | Interactive tests | Set to `1` to enable |
+| `KEYCARD_ZONE_URL` | Interactive tests | Real Keycard zone URL |
+| `OPENAI_API_KEY` | Agent integration tests | OpenAI API key |
+| `MCP_TEST_PORT` | Interactive tests | Custom port (default: 8765) |
+
+## Mocking Patterns
+
+Tests use dependency injection of mock clients via `client_factory` parameter.
+See `fixtures/auth_provider.py` for reusable mock fixtures.