Testing Strategy

The Testing Strategy for the Stacklet MCP Server focuses on end-to-end tool validation using FastMCP's in-memory testing pattern. The project prioritizes high-level abstraction by mocking downstream HTTP interactions to verify tool behavior without requiring live external services.

Tests are executed using pytest with pytest-asyncio for asynchronous tool calls. The strategy ensures that tools for AssetDB, Platform GraphQL, and Documentation correctly handle input parameters, process API responses, and return structured data or appropriate error messages.

Sources: CLAUDE.md:144-147, pyproject.toml:39-41, tests/test_tools_assetdb.py:11-13

Core Testing Architecture

The testing architecture utilizes a base suite of classes and fixtures to standardize tool invocation and response assertion.

Base Test Classes

The project defines specialized base classes in tests/testing/mcp.py to handle different authentication and communication scenarios:

Sources: tests/testing/mcp.py:53-76, tests/test_tools_platform.py:54-56

Tool Execution Flow

Testing follows a structured flow where the test fixture creates a mock server instance, and the test class executes tool calls against this instance while intercepting HTTP requests.

The diagram shows the sequence from fixture initialization to final assertion of tool results.
Sources: tests/conftest.py:38-51, tests/testing/mcp.py:65-70

Mocking and Fixtures

The project relies heavily on pytest fixtures to simulate the environment and downstream services.

• Credential Mocking: The mock_stacklet_credentials fixture in tests/conftest.py provides fake StackletCredentials (endpoint, access token, and identity token) to avoid loading real configuration files.
• Settings Overrides: The override_setting fixture allows tests to dynamically toggle feature flags, such as enabling or disabling assetdb_allow_save or platform_allow_mutations.
• HTTP Interception: Tests use ExpectRequest to define expected URL, method, and data. The system asserts that the tool makes exactly these calls to the downstream Redash or Platform APIs.
• Time Management: The async_sleeps fixture mocks asyncio.sleep to test long-running operations like async job polling without actual delays.

Sources: tests/conftest.py:27-36, tests/conftest.py:54-65, tests/test_tools_assetdb.py:90-94, tests/test_tools_platform.py:165-173

Specialized Tool Testing

AssetDB SQL Testing

AssetDB tests verify SQL query execution, saved query management, and async job handling.

• Async Jobs: Tests simulate the transition of JobStatus from QUEUED to STARTED and finally FINISHED or FAILED.
• Result Routes: The strategy validates that full query results are either written to a file (when downloads_enabled is true) or returned as an MCP resource.

Sources: tests/test_tools_assetdb.py:365-373, tests/test_tools_assetdb.py:441-458

Platform GraphQL Testing

Platform tests ensure that GraphQL queries and dataset exports function correctly within the MCP framework.

• Schema Validation: The PlatformSchemaTest class mocks PlatformClient.get_schema to return a test-specific SDL, allowing local validation of fields before reaching the "server".
• Introspection: Tests verify that tools like platform_graphql_list_types and platform_graphql_get_types correctly interact with the cached schema.

Sources: tests/test_tools_platform.py:54-82, tests/test_tools_platform.py:202-210

Test Configuration and Linting

The testing environment is managed via pyproject.toml and a justfile.

The diagram illustrates the relationship between the project configuration and the development commands used for testing.
Sources: pyproject.toml:39-44, pyproject.toml:105-108, CLAUDE.md:68-73

Conclusion

The testing strategy provides a robust framework for verifying MCP tool functionality in isolation. By combining specialized base classes, comprehensive HTTP mocking, and rigorous coverage requirements, the project ensures that tools interact correctly with the Stacklet platform while maintaining a fast, reliable test suite.

Sources: pyproject.toml:105-108, CLAUDE.md:144-147