Testing

This document explains the testing strategy, test organization, execution methods, and requirements for the simap-mcp server. Testing is a core requirement for all contributions to ensure the reliability of tool schemas, API parameter mapping, and response formatting.

---

Testing Strategy

The simap-mcp project enforces mandatory testing for all new features and tools. The strategy is built around four pillars:

1. Schema Validation: Ensuring zod schemas correctly accept valid inputs and reject malformed ones, such as enforcing string lengths, UUID formats, or regex patterns tests/tools/get-tender-details.test.ts41-84
2. Query Parameter Building: Verifying that tool inputs are correctly mapped to SIMAP API query parameters, including handling array serialization and scalar values tests/api/client.test.ts38-66
3. Response Formatting: Confirming that API data is transformed into readable Markdown for the MCP client, using fixtures to simulate real API payloads tests/tools/get-tender-details.test.ts86-120 tests/utils/formatting.test.ts128-191
4. Logic & Utility Verification: Testing core infrastructure like rate limiting and error handling to ensure system stability tests/api/rate-limiter.test.ts8-22

Natural Language to Code Mapping: Testing Entities

The following diagram bridges the conceptual testing requirements to the specific code entities and files used in the testing suite.

Title: Mapping Requirements to Code Entities

Sources: tests/tools/search-cpv-codes.test.ts8-9 tests/api/rate-limiter.test.ts6 tests/api/client.test.ts8-10 tests/utils/formatting.test.ts9-15

---

Test Organization

Directory Structure

Test files mirror the src/ directory structure to maintain a clear 1:1 relationship between implementation and verification tests/tools/get-tender-details.test.ts9-12

Source File	Test File
src/tools/codes/search-cpv-codes.ts	tests/tools/search-cpv-codes.test.ts
src/tools/get-tender-details.ts	tests/tools/get-tender-details.test.ts
src/api/rate-limiter.ts	tests/api/rate-limiter.test.ts
src/api/client.ts	tests/api/client.test.ts
src/utils/formatting.ts	tests/utils/formatting.test.ts

Code Flow: Test Execution Path

Title: Internal Test Logic Flow

Sources: tests/tools/search-cpv-codes.test.ts11-42 tests/api/client.test.ts38-42 tests/utils/formatting.test.ts87-126 tests/utils/formatting.test.ts128-132

---

Tool Test Requirements

1. Schema Validation

Tests must verify that the zod schema defined for each tool enforces constraints like string length, UUID formats, and language defaults.

• Search Queries: Tools like search_cpv_codes must reject empty queries or those exceeding maximum length (e.g., 500 characters) tests/tools/search-cpv-codes.test.ts28-41
• UUIDs: Parameters like projectId and publicationId must be valid UUIDs tests/tools/get-tender-details.test.ts50-56
• Language Defaults: Input schemas should default to en and only accept valid SIMAP languages (de, fr, it, en) tests/tools/search-cpv-codes.test.ts44-61
• Booleans: Optional flags like fullRaw must be strictly boolean tests/tools/get-tender-details.test.ts76-83
• Date Formats: Parameters like publicationFrom must follow the YYYY-MM-DD regex tests/tools/search-tenders.test.ts28-39

2. Query Parameter Building

Tests verify that the SimapClient and tool handlers correctly serialize data for the SIMAP API.

• Parameter Mapping: Verification that tool inputs map to the correct API keys (e.g., lang mapping to language) tests/tools/search-cpv-codes.test.ts68-84
• Repeated Keys: Array values in parameters are emitted as repeated keys in the query string (e.g., cantons=VD&cantons=GE) tests/api/client.test.ts44-49
• Normalization: The buildUrl helper normalizes trailing slashes on the base URL tests/api/client.test.ts62-65

3. Response Formatting

Tests ensure that the data returned to the user is transformed into high-quality Markdown.

• Fixture-Driven Tests: Tests use JSON fixtures from tests/fixtures/ to simulate complex API responses. These fixtures are validated against the PublicationDetailsSchema to ensure they remain current tests/utils/formatting.test.ts21-31
• Section Rendering: Tests verify the presence of specific Markdown headers like ## Publication Details, ### CPV, and ### Deadlines tests/utils/formatting.test.ts132-153
• CommonMark Compliance: As of v1.2.3, search-cpv-codes.test.ts imports the real formatInlineCode from src/utils/formatting.ts to verify that backticks in queries are correctly fenced (e.g., testinjection becomes ```testinjection```) tests/tools/search-cpv-codes.test.ts9-10 tests/tools/search-cpv-codes.test.ts168-174
• Raw Data Handling: The get_tender_details tool includes tests for the fullRaw parameter, ensuring the complete untruncated JSON is appended when requested tests/tools/get-tender-details.test.ts142-160

4. Infrastructure and Utility Testing

• Formatting Utilities: As of v1.2.3, formatting.test.ts provides direct unit coverage for escapeInlineCode, ensuring that backslashes and backticks are escaped to prevent Markdown breakage (e.g., \ becomes \\\\\\ to preserve the escape in Markdown) tests/utils/formatting.test.ts57-85
• Rate Limiting: The SlidingWindowRateLimiter is tested using fake timers to ensure it correctly handles concurrent acquires and serves them in FIFO order tests/api/rate-limiter.test.ts54-72
• Network Resilience: SimapClient tests mock fetch to verify behavior during 404/500 errors and request timeouts tests/api/client.test.ts110-158
• Debug Logging: Tests verify that verbose logging (using → and ← markers) is triggered only when SIMAP_MCP_DEBUG is set tests/api/client.test.ts191-206

---

Running Tests

The project uses vitest as the primary test runner.

Command	Action
npm test	Runs all tests once.
npm run test:watch	Runs tests in watch mode for active development.
npm run typecheck	Validates TypeScript types across the entire project including test files.

Sources: tests/tools/search-cpv-codes.test.ts5 tests/api/rate-limiter.test.ts5 tests/api/client.test.ts6