Testing

Relevant source files

• guides/testing/dogfood-fixture-matrix.md
• src/__tests__/tools.test.ts
• tests/audit-dogfood-account.ts
• tests/mcp-client-dogfood.ts

This page provides an overview of the testing strategy for the Help Scout MCP Server. The project employs a multi-layered testing approach to ensure reliability across the Model Context Protocol (MCP) interface and the underlying Help Scout API integrations.

The testing suite is divided into automated unit/integration tests, live API validation scripts, dogfood fixture management, and containerization smoke tests.

Testing Strategy Overview

The codebase utilizes jest as the primary test runner package.json29 configured for ESM support via ts-jest. The strategy ensures that every layer of the server—from utility functions to complex tool-calling workflows—is validated.

Test Categories

Category	Target	Tools	Location
Unit Tests	Logic, Utilities, Schemas	jest	src/__tests__/*.test.ts
Integration Tests	Multi-tool workflows, API mocking	jest, nock	src/__tests__/integration.test.ts
Live API Tests	Real Help Scout API connectivity	tsx	scripts/, tests/
Dogfooding	Realistic data seeding and auditing	tsx	tests/seed-*.ts, tests/audit-*.ts
Tool Surface Evals	Gateway routing and LLM accuracy	mjs	evals/
Docker Smoke Tests	Container runtime and entrypoints	node	test-docker.cjs

Code Entity Mapping

The following diagrams illustrate how natural language testing requirements map to specific code entities and files.

Gateway and Registry Testing Architecture

This diagram shows how a user request to the gateway tools is routed to the internal registry operations and validated during testing.

Sources: tests/mcp-client-dogfood.ts128-150 src/__tests__/tools.test.ts44-105

Fixture and Data Validation

This diagram maps the dogfooding system used to ensure the server handles real Help Scout account data.

Sources: guides/testing/dogfood-fixture-matrix.md1-38 tests/audit-dogfood-account.ts1-11

Unit and Integration Tests

The core of the test suite resides in src/__tests__/. These tests run in a controlled environment where the Help Scout API is simulated using nock src/__tests__/tools.test.ts22-33

• Tool Registry: The ToolHandler is tested for 55+ internal registry operations, ensuring correct schema definitions and parameter mapping src/__tests__/tools.test.ts44-106
• Gateway Routing: Tests in gateway.test.ts verify the v2.0 architecture where four advertised tools (search_help_scout, describe_help_scout, read_help_scout, write_help_scout) route to the underlying registry tests/mcp-client-dogfood.ts130-131
• Read-Only Annotations: Every tool is verified to advertise readOnlyHint: true to allow clients to auto-approve reads src/__tests__/tools.test.ts120-131
• Pagination Logic: Specific tests ensure that v2 tools correctly expose page-based pagination src/__tests__/tools.test.ts147-169

For details on mocking strategies and running the Jest suite, see Unit and Integration Tests.

Live API and Docker Tests

The project includes scripts to verify the server against the actual Help Scout production or sandbox API.

• Dogfood Harness: tests/mcp-client-dogfood.ts spawns the server and uses the official MCP SDK to validate every tool through the same protocol path used by real MCP hosts tests/mcp-client-dogfood.ts3-16
• Write Lifecycle Matrix: The dogfood harness drives Tier-1 write operations (e.g., createNote, updateConversationStatus) to verify the mutation-class logic tests/mcp-client-dogfood.ts134-147
• Docker Smoke Tests: test-docker.cjs and test-docker-ci.cjs verify that the multi-platform Docker images correctly initialize and respond to MCP protocol handshakes.

For details on running live tests and Docker verification, see Live API and Docker Tests.

Dogfood Fixture Management

To ensure the LLM behaves correctly with realistic data, the project maintains a "dogfood" Help Scout account.

• Seeding: Scripts like seed-test-data.ts, seed-org-customers.ts, and seed-integration-data.ts populate the account with diverse scenarios including attachments, tags, and report-rich data guides/testing/dogfood-fixture-matrix.md88-95
• Auditing: audit-dogfood-account.ts identifies "fixture gaps"—account-level states that the API cannot create, such as Team membership or Satisfaction ratings tests/audit-dogfood-account.ts106-122
• No Hardcoded IDs: The system relies on MCP_DOGFOOD_* environment variables to pin specific records, ensuring the codebase remains ID-agnostic tests/mcp-client-dogfood.ts33-65

For details on seeding and auditing the dogfood environment, see Dogfood Fixture Management.

Tool Surface Evaluations

The evals/ directory contains a framework for validating the v2.0 gateway architecture decision.

• Discriminator Framework: Runs LLM-based evaluations to determine if the model correctly selects between the four gateway tools vs. the previous 55-tool flat surface evals/run-tool-surface-discriminator.mjs
• Candidate Validation: Compares different architecture candidates (e.g., registry-3 vs hybrid-10) to optimize for context window usage and routing accuracy.

For details on the evaluation framework, see Tool Surface Evaluations.

Test Execution Commands

Command	Description
npm test	Runs the full Jest test suite package.json29
npm run dogfood:seed	Populates the Help Scout test account with fixtures guides/testing/dogfood-fixture-matrix.md17
npm run dogfood:audit	Identifies missing fixtures in the test account guides/testing/dogfood-fixture-matrix.md36
node tests/mcp-client-dogfood.ts	Runs the full MCP client dogfood harness tests/mcp-client-dogfood.ts11

Sources: package.json21-35 src/__tests__/tools.test.ts1-42 tests/mcp-client-dogfood.ts1-20 guides/testing/dogfood-fixture-matrix.md1-38