Testing Strategy & Mock Server
Relevant source files
The following files were used as context for generating this wiki page:
The StackOne AI SDK employs a testing strategy centered on high-fidelity simulation of server behavior. This approach ensures that the SDK handles real-world API constraints, such as mandatory account scoping and specific parameter shapes, before deployment. The strategy combines unit tests using property-based testing, integration tests against a specialized mock server, and a validation suite for external consumers.
Sources: CLAUDE.md:83-88, scripts/validate.sh:15-18
Test Double Philosophy
The SDK follows a strict "fail-fast" philosophy for test doubles. Fakes and mocks must model what the server demands rather than what the client currently sends. This design prevents bugs where the SDK might omit required headers that a permissive mock would otherwise ignore. For instance, the mock server intentionally returns a 400 Bad Request for unscoped /mcp or /actions/rpc requests to ensure the SDK always provides a valid x-account-id.
Sources: CLAUDE.md:83-88, tests/mocks/mcp-server.ts:67-73, tests/mocks/serve.ts:67-72
Mock Server Architecture
The mock server is a standalone Node.js application built with Hono. It provides a local environment to test both Model Context Protocol (MCP) tool fetching and Remote Procedure Call (RPC) execution.
Components and Flow
The server operates three primary endpoints:
/mcp: Handles protocol requests to list and call tools using the@modelcontextprotocol/sdk./actions/rpc: Executes tools via a flat-prefixed argument shape./accounts: Returns a list of active and error-state accounts for discovery testing.
The diagram shows how the Python SDK interacts with the Hono-based mock server through three distinct API paths.
Sources: tests/mocks/serve.ts:39-60, tests/mocks/mcp-server.ts:63-66
Server Endpoints Summary
| Endpoint | Method | Purpose |
|---|---|---|
/health | GET | Verification of server availability. |
/accounts | GET | Discovery of linked accounts (returns id, provider, status). |
/mcp | ALL | MCP tool catalog and execution endpoint. |
/actions/rpc | POST | Unified RPC execution for flat-prefixed parameters. |
Sources: tests/mocks/serve.ts:46-60, tests/mocks/serve.ts:133-136
Integration Testing Flow
Integration tests leverage a session-scoped pytest fixture that spawns the mock server process. The server requires pnpm install to provide tsx and necessary Node dependencies.
The sequence diagram illustrates the lifecycle of the mock server during a test session, including port discovery and cleanup.
Sources: tests/conftest.py:46-86
Validation Suite
The scripts/validate.sh utility performs deterministic checks against the SDK and its consumers. It ensures wire contract conformance without requiring live API credentials.
Validation Tiers
- Examples: proved via static imports and type-checking using
ty check. - Conformance: validates the wire contract and ensures strict JSON Schema pass-through.
- Consumer Smoke Tests: installs the SDK into representative environments (Pydantic AI, Google ADK) to verify compatibility.
Sources: scripts/validate.sh:31-60, scripts/validate.sh:79-88
Key Implementation Details
MCP Mock Configuration
The mock server simulates specific account-based tool visibility. It defines unique tool sets for accounts like acc1, acc2, and mixed to verify that filtering and account context are preserved during SDK operations.
Sources: tests/mocks/mcp-server.ts:153-195, tests/test_fetch_tools.py:108-112
RPC Execution Validation
The server validates the Authorization header (Basic Auth) and ensures the x-account-id is present. It also echoes back parameters for specific test actions like test_account_id_header.
Sources: tests/mocks/serve.ts:63-75, tests/mocks/serve.ts:91-97
Manual Execution
To start the mock server manually for local debugging:
pnpm mock-server [port]
Sources: tests/mocks/serve.ts:7-12, package.json:8-10
Testing in the StackOne AI SDK ensures that the complex interaction between Python-based toolsets and Node-based MCP protocols remains stable. By enforcing strict account scoping and wire contract validation, the suite prevents common integration failures before they reach production environments.