Testing Strategy

Robust testing is essential for ensuring the reliability, correctness, and security of the PDF Reader MCP Server. We employ a multi-faceted testing approach using Vitest.

Framework: Vitest

We use Vitest as our primary testing framework. Its key advantages include:

Speed: Fast execution powered by Vite.
Modern Features: Supports ES Modules, TypeScript out-of-the-box.
Compatibility: Familiar API similar to Jest.
Integrated Coverage: Built-in support for code coverage analysis using v8 or istanbul.

Goals & Approach

Our testing strategy focuses on:

High Code Coverage:
- Target: 100% statement, branch, function, and line coverage.
- Configuration: Enforced via thresholds in vitest.config.ts.
- Current Status: ~95%. The remaining uncovered lines are primarily in error handling paths that are difficult to trigger due to Zod's upfront validation or represent extreme edge cases. This level is currently accepted.
- Tool: Coverage reports generated using @vitest/coverage-v8.
Correctness & Functionality:
- Unit Tests: (Currently minimal, focus is on integration) Could test utility functions like pathUtils in isolation.
- Integration Tests: The primary focus is testing the read_pdf handler (test/handlers/readPdf.test.ts) with mocked dependencies (pdfjs-dist, fs). These tests verify:
  - Correct parsing of various input arguments (paths, URLs, page selections, flags).
  - Successful extraction of full text, specific page text, metadata, and page counts.
  - Handling of multiple sources (local and URL) within a single request.
  - Correct formatting of the JSON response.
  - Graceful error handling for invalid inputs (caught by Zod or handler logic).
  - Correct error reporting for file-not-found errors.
  - Correct error reporting for PDF loading/parsing failures (mocked).
  - Proper handling of warnings (e.g., requested pages out of bounds).
- Security: Path resolution logic (resolvePath) is tested separately (test/pathUtils.test.ts) to ensure it prevents path traversal and correctly handles relative paths within the project root.
Reliability & Consistency:
- Tests are designed to be independent and repeatable.
- Mocking is used extensively to isolate the handler logic from external factors.

Running Tests

Use the following npm scripts:

npm test: Run all tests once.
npm run test:watch: Run tests in an interactive watch mode, re-running on file changes.
npm run test:cov: Run all tests and generate a detailed coverage report in the ./coverage/ directory (view index.html in that directory for an interactive report). This command will fail if coverage thresholds are not met.

Test File Structure

Tests reside in the test/ directory, mirroring the src/ structure.
Handler tests are in test/handlers/.
Utility tests are in test/utils/.

Future Improvements

Consider adding end-to-end tests using a test MCP client/host.
Explore property-based testing for more robust input validation checks.

3.1 KiB Raw Blame History