Testing Strategy & Execution

Relevant source files

The following files were used as context for generating this wiki page:

• tests/markdowndeck/integration/test_pipeline_contracts.py
• tests/google-workspace-mcp/integration/test_docs_api.py
• tests/markdowndeck/end_to_end/test_e2e.py
• tests/weaviate-mcp/integration/test_mcp_tools_integration.py
• tests/markdowndeck/unit/parser/test_parser_diagnostics.py
• tests/markdowndeck/unit/api/test_api_generator.py
• pyproject.toml

Testing within the Arclio MCP Tooling project is structured as a multi-layered hierarchy designed to validate individual components, internal pipeline contracts, and end-to-end service integrations. The strategy focuses on ensuring data integrity as Markdown content is transformed into service-specific API requests (such as Google Slides or Weaviate operations) and verifying the reliability of external API interactions.

The project utilizes pytest as the primary testing framework, categorized into unit, integration, end-to-end, and stress tests. Integration tests are further divided between internal pipeline validation and external service integration, the latter of which often requires specific environment configurations and live API credentials.

Sources: pyproject.toml:34-45, tests/markdowndeck/integration/test_pipeline_contracts.py:1-42

Test Classification and Infrastructure

The testing suite is categorized using pytest markers to allow for granular execution. This structure ensures that fast, isolated tests can be run frequently, while slower integration or stress tests are executed in appropriate environments.

Marker	Description	Focus Area
unit	Fast, isolated tests.	Individual classes like Parser or ApiRequestGenerator.
integration	Components working together.	Pipeline contracts and Multi-tool workflows.
end_to_end	Full pipeline validation.	Markdown-to-Presentation workflows.
stress	Resource-intensive tests.	Large data sets or performance bottlenecks.

Sources: pyproject.toml:34-45, tests/markdowndeck/unit/api/test_api_generator.py:1-42

Execution Environment

The project uses uv for workspace management and a Makefile to standardize test execution. Integration tests for external services (e.g., Google Workspace) are guarded by the RUN_INTEGRATION_TESTS environment variable to prevent accidental side effects or failures in environments lacking credentials.

Sources: README.md:70-85, tests/google-workspace-mcp/integration/test_docs_api.py:16-20

Pipeline Contract Testing

A critical part of the strategy involves validating "contracts" between stages of the Markdown transformation pipeline. This ensures that data remains consistent as it moves from an unpositioned state to a finalized, renderable state.

Key pipeline validation stages include:

• Parser to Layout: Ensures the Parser produces valid Unpositioned slides where coordinates and sizes are initially None. Sources: tests/markdowndeck/integration/test_pipeline_contracts.py:44-65
• Layout to Overflow: Validates the transition to a Positioned state where coordinates are calculated, and subsequent "Finalization" where renderable_elements are populated. Sources: tests/markdowndeck/integration/test_pipeline_contracts.py:67-93
• Overflow Handling: Specifically tests if content exceeding slide boundaries results in the generation of multiple finalized slides with "(continued)" titles. Sources: tests/markdowndeck/integration/test_pipeline_contracts.py:95-122

External Service Integration Testing

Integration testing for MCP tools involves verifying interactions with live or mocked external APIs. This is particularly prevalent in the google-workspace-mcp and weaviate-mcp packages.

Google Workspace Integration

These tests verify that the DocsService, SheetsService, and SlidesService correctly handle authentication and execute complex API workflows. For example, DocsService tests cover a complete workflow: document creation, prepending text, appending content, and finally retrieving the result as Markdown.

Sources: tests/google-workspace-mcp/integration/test_docs_api.py:143-176, tests/google-workspace-mcp/integration/test_sheets_api.py:317-385

Weaviate Tool Workflows

Testing for the Weaviate MCP server focuses on the orchestration of multiple tools. A single integration test case might cover:

1. Collection creation.
2. Object insertion with property validation.
3. Vector search retrieval.
4. Collection deletion.

End-to-End (E2E) Validation

E2E tests validate the entire system from the user's perspective, typically starting with a raw Markdown string and ending with a set of API requests or a created resource ID.

• Simple Presentation: Validates that a basic title and body Markdown string successfully calls the ApiClient to return a presentationId. Sources: tests/markdowndeck/end_to_end/test_e2e.py:11-40
• Directive Translation: Ensures that visual styling directives (e.g., [color=#FF0000], [fontsize=40]) are correctly translated into the updateTextStyle or updatePageProperties payloads required by the Google Slides API. Sources: tests/markdowndeck/end_to_end/test_e2e.py:86-130
• Blank Canvas Architecture: Verifies the "Blank Canvas First" principle, ensuring all slides are created with a BLANK layout rather than predefined templates. Sources: tests/markdowndeck/end_to_end/test_e2e.py:65-84

Diagnostic and Unit Testing

Unit tests target the most granular logic, such as the Parser's ability to handle complex Markdown edge cases or the ApiRequestGenerator's statelessness.

• Parser Diagnostics: Focused tests for specific parsing issues, such as ensuring complex inline formatting results in TextFormat objects rather than booleans, and validating directive scoping (Rule 1 vs Rule 2). Sources: tests/markdowndeck/unit/parser/test_parser_diagnostics.py:27-42, tests/markdowndeck/unit/parser/test_parser_diagnostics.py:180-205
• API Generator Tests: Validates that the generator only reads from renderable_elements and does not modify the input Deck object during request generation. Sources: tests/markdowndeck/unit/api/test_api_generator.py:53-77

Summary

The Arclio MCP Tooling testing strategy provides a robust framework for development, combining rapid unit tests with thorough integration and E2E checks. By enforcing strict pipeline contracts and verifying multi-tool workflows, the project ensures that AI assistants can reliably interact with enterprise data across various Model Context Protocol implementations.