testing

name	Testing
description	This skill should be used when the user asks to "run tests", "run the test suite", "check test results", "why are tests failing", "debug test failures", "add a test", "write a test", "update EXPECTED_TOOL_COUNT", "run protocol tests", "run integration tests", "test against InfluxDB", or needs to run, analyze, extend, or troubleshoot the MCP server test suite.
version	0.1.0

Testing the InfluxDB MCP Server

Two-layer test suite using vitest. Protocol tests run without InfluxDB. Integration tests require a live instance and are gated behind an env var.

Prerequisites

Build before testing — tests spawn the compiled build/index.js, not source:

npm run build

Running Tests

Protocol tests (no InfluxDB needed)

npm test

Runs tests/protocol.test.ts only. Integration tests are skipped automatically. Expected runtime: <1 second.

These tests spawn the real server as a child process using the MCP SDK's StdioClientTransport, perform the initialize handshake, and assert on protocol responses. No InfluxDB connection is made — protocol requests (tools/list, resources/list, prompts/list, ping) are answered entirely from the server's in-memory registrations.

Integration tests (live InfluxDB)

Start InfluxDB 3 Core via the provided Docker Compose file:

npm run test:infra:up

This starts an ephemeral Core container on port 8181 using a static admin token from tests/fixtures/admin-token.json (Docker secrets pattern, --object-store memory — no persistent state).

Run integration tests against it:

source env.test.example && npm run test:integration

Tear down when done:

npm run test:infra:down

For a custom InfluxDB instance (different port, Enterprise, etc.), set the env vars directly instead of sourcing the example file:

INFLUX_TEST_ENABLED=true \
INFLUX_DB_INSTANCE_URL=http://localhost:8281/ \
INFLUX_DB_TOKEN=<your_token> \
INFLUX_DB_PRODUCT_TYPE=enterprise \
npm run test:integration

Tests call health_check, list_databases, and execute_query through the MCP protocol.

Watch mode

npm run test:watch

Reruns on file changes. Useful during development.

What the Tests Cover

Test	What it verifies
Initialize handshake	Server starts, SDK handshake succeeds, capabilities reported
Server version	Name is "influxdb-mcp-server", version is defined
Tool count	tools/list returns exactly EXPECTED_TOOL_COUNT tools
Tool structure	Each tool has name, description, inputSchema with type: "object"
Core tool names	Spot-checks health_check, execute_query, write_line_protocol, list_databases, create_admin_token
Resource URIs	4 resources with correct influx:// URIs
Resource structure	Each resource has name, uri, description
Prompt names	3 prompts: list-databases, check-health, load-context
Ping	Server responds to ping
Unknown tool error	Calling nonexistent tool throws McpError

Analyzing Failures

EXPECTED_TOOL_COUNT mismatch

The most common failure after code changes. The constant in tests/protocol.test.ts (line 7) must match the actual tool count.

After adding or removing a tool, update the constant and comment in tests/protocol.test.ts (the source of truth). Then update the breakdown below for documentation.

To find the current count, start the server briefly and check stderr:

npm run build && INFLUX_DB_INSTANCE_URL=http://localhost:19999/ \
INFLUX_DB_TOKEN=fake INFLUX_DB_PRODUCT_TYPE=core \
node build/index.js &
sleep 1 && kill $!

Look for: [MCP] Server initialized with N tools, N resources, N prompts

The tool count breakdown by category file:

• help.tools.ts (2) + write.tools.ts (1) + database.tools.ts (4)
• query.tools.ts (3) + token.tools.ts (6) + cloud-token.tools.ts (5)
• health.tools.ts (1) = 22 total
• schema.tools.ts (4 tools, currently disabled — commented out in src/tools/index.ts)

"build/index.js not found"

Run npm run build first. The tests/setup.ts guard fails fast with this message if the build artifact is missing.

Initialize handshake timeout

The server process failed to start. Common causes:

• Build is stale after source changes — rebuild with npm run build
• Missing or invalid env vars — protocol tests use a fake config internally, so this usually means createTestClient was called with bad overrides

Integration test: "HEALTHY" not found

InfluxDB instance is unreachable or unhealthy. Verify:

1. Instance is running: curl http://localhost:8181/ping
2. Token is valid
3. INFLUX_DB_PRODUCT_TYPE matches the actual instance type

Two error paths in the server

When diagnosing tool call failures, note the server has two distinct error paths (defined in src/server/index.ts):

• Unknown tool name → throw new Error(...) → SDK converts to McpError → client sees a rejected promise
• Known tool, handler failure → caught in try/catch → returns { content: [{ type: "text", text: "Error: ..." }], isError: true }

Protocol tests assert the thrown error path. Integration tests assert the content-based error path.

Adding New Tests

New protocol test

Add to tests/protocol.test.ts inside the describe("MCP protocol compliance") block. Protocol tests use the shared testClient from beforeAll. No InfluxDB is contacted — only test MCP protocol-level behavior.

New integration test

Add to tests/integration.test.ts inside the describe.skipIf(!RUN)("live InfluxDB integration") block. Call tools via testClient.client.callTool({ name: "...", arguments: {...} }) and assert on the response content[0].text.

Test helper

The createTestClient(env?) factory in tests/helpers/mcp-client.ts spawns a real server process and returns a connected MCP Client. Override env vars by passing a partial record. Always call close() in afterAll.

Reviewing data-plane and admin changes

When a change adds or modifies a tool that talks to an InfluxDB endpoint (writes, queries, database/token management), verify the actual API contract and exercise it against a real instance. Tool descriptions, CHANGELOG entries, and code comments are not authoritative on their own — confirm them.

Verify the API contract first

Confirm the HTTP method, path, and request/response shape against both the InfluxData docs knowledge source and the influxdata/influxdb source (influxdb3_server/src/http.rs routing, influxdb3_types/src/http.rs structs).

Gotchas that have already bitten this repo:

• Core/Enterprise update_database retention is PUT /api/v3/configure/database with retention_period as a duration string ("60d") — not PATCH, not retention_period_ns.
• Core can update retention since v3.2.0 (static docs wrongly say it's immutable).
• /ping and /health use Token auth even for core/enterprise (v1/v2 compat); the admin client uses Bearer. Both are intentional.

Exercise it against a real instance

Admin endpoints (/api/v3/configure/*) need an admin token; health_check does not, so a passing health_check does not prove the token works. Run a self-contained Core for an admin-path test on a free port:

docker run -d --name mcp-it-core -p 8383:8181 \
  -v "$PWD/tests/fixtures/admin-token.json":/admin-token.json:ro \
  influxdb:3-core influxdb3 serve \
  --node-id local-test --object-store memory \
  --admin-token-file /admin-token.json

INFLUX_TEST_ENABLED=true INFLUX_DB_INSTANCE_URL=http://localhost:8383/ \
INFLUX_DB_TOKEN=apiv3_test INFLUX_DB_PRODUCT_TYPE=core \
npx vitest run tests/integration.test.ts

docker rm -f mcp-it-core

This uses the offline preconfigured admin token in tests/fixtures/admin-token.json (token apiv3_test) — the docker-compose.test.yml pattern, but on a port you choose so it does not collide with other local instances.

Token gotcha

v3 tokens are base64 and can contain +, /, and =. Do not extract one with grep -oE 'apiv3_[A-Za-z0-9_-]+' — it truncates at the first base64 character and yields an invalid token (the server returns 401 "the request was not authenticated").

Additional Resources

Reference Files

• .claude/skills/testing/references/test-architecture.md — Detailed test architecture, design decisions, and how protocol tests work without InfluxDB