Testing Strategy

Relevant source files

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

• vitest.config.ts
• tests/unit/schemas.test.ts
• tests/unit/position.test.ts
• tests/unit/uri.test.ts
• CLAUDE.md
• package.json

The testing strategy for the lsp-mcp-server project is designed to ensure the reliability of the bridge between Model Context Protocol (MCP) clients and Language Server Protocol (LSP) servers. The strategy prioritizes technical accuracy in position conversions, URI handling, and input validation, which are critical for maintaining semantic integrity during code intelligence operations.

Testing is primarily executed using the Vitest framework, following a clear separation between unit tests and integration tests. The suite is configured to support ECMAScript Modules (ESM) and provides comprehensive coverage reporting to monitor code health.
Sources: CLAUDE.md:120-125, vitest.config.ts:31-41, package.json:44-48

Test Infrastructure and Execution

The project utilizes vitest as its primary test runner. Configuration is managed through vitest.config.ts, which sets the test environment to node and enables global variables to simplify test authoring by removing the need to import describe, it, and expect in every file.

Execution Commands

The following scripts in package.json define the entry points for testing:

Command	Purpose
npm test	Runs the full unit test suite once using Vitest.
npm run test:watch	Starts Vitest in interactive watch mode for development.
npm run test:integration	Executes integration tests using a separate configuration.
npm run typecheck	Validates TypeScript types across the project without emitting files.

Sources: package.json:44-48, vitest.config.ts:31-41, CLAUDE.md:23-28

Test Organization

Tests are logically separated into distinct directories to reflect their scope:

• Unit Tests (tests/unit/): Focus on individual utilities, schema validations, and isolated logic.
• Integration Tests: Focused on end-to-end flows, requiring a separate vitest.integration.config.ts.
  Sources: vitest.config.ts:35, CLAUDE.md:120-121

Unit Testing Areas

Schema Validation

A significant portion of the testing strategy involves validating the Zod schemas used for MCP tool inputs. These tests ensure that the server rejects malformed requests before they reach the LSP clients.

The diagram shows the validation flow where input data is filtered through Zod schemas to ensure constraints like absolute paths and 1-indexed positions are met.
Sources: tests/unit/schemas.test.ts:31-135

Position and URI Utilities

Because LSP uses 0-indexed UTF-16 positions while the MCP server exposes 1-indexed positions, the conversion utilities are heavily tested to prevent off-by-one errors and ensure correct handling of multi-byte characters (e.g., emojis).

• Position Tests: Verify conversions between 1-indexed and 0-indexed formats and handle UTF-16 code units.
• URI Tests: Ensure paths are correctly converted to file:// URIs, including encoding for special characters and normalization of path separators.
  Sources: tests/unit/position.test.ts:33-85, tests/unit/uri.test.ts:33-77

Code Coverage and Quality

The testing strategy includes automated quality checks and coverage tracking to maintain high standards.

Coverage Reporting

Vitest is configured to use the v8 provider for coverage analysis.

• Reporters: Generates both text (for terminal output) and html (for detailed browser-based inspection).
• Exclusions: Files in node_modules, dist, and the tests directory itself are excluded from coverage metrics to provide an accurate representation of source code health.
  Sources: vitest.config.ts:36-40

Linting and Type Checking

In addition to runtime tests, the project enforces code quality through static analysis:

• ESLint: Used for linting source files (npm run lint).
• TypeScript: The typecheck command ensures that all module resolutions (using NodeNext) and strict type checks are satisfied.
  Sources: package.json:49-51, CLAUDE.md:29-30

Interactive Testing

For manual verification of MCP tool behavior, the strategy recommends using the MCP Inspector. This allows developers to interactively call tools and inspect the JSON-RPC traffic between the server and the inspector.

npx @modelcontextprotocol/inspector node dist/index.js

Sources: CLAUDE.md:36-38

Summary

The Testing Strategy of lsp-mcp-server centers on ensuring that the critical translation layer between MCP and LSP remains robust. By combining strict schema validation, precise utility testing for coordinates and URIs, and automated coverage reporting, the project maintains a reliable environment for semantic code intelligence.