add-test

Context

Tests use Vitest and createMockContext from @cyanheads/mcp-ts-core/testing. Test files are colocated with their source: foo.tool.ts gets foo.tool.test.ts in the same directory.

For the full createMockContext API and testing patterns, read:

skills/api-testing/SKILL.md

Steps

1. Identify the target — which tool, resource, or service needs tests
2. Read the source file — understand the handler's logic, input/output schemas, error paths, and which ctx features it uses
3. Create the test file colocated with the source
4. Write test cases covering happy path, error paths, and edge cases
5. Run npm test to verify
6. Run bun run devcheck to verify types

Determining What to Test

Read the handler and identify:

Aspect	Test Strategy
Happy path	Valid input → expected output. Always include at least one.
Input variations	Optional fields omitted, defaults applied, boundary values
Error paths	Invalid state, missing resources, service failures → correct error thrown
ctx.state usage	Use createMockContext({ tenantId: 'test' }) to enable storage
ctx.elicit / ctx.sample	Mock with vi.fn(), also test the absent case (undefined)
ctx.progress	Use createMockContext({ progress: true }) for task tools
format function	Test separately if defined — it's pure, no ctx needed
Auth scopes	Not tested at handler level (framework enforces) — skip

Templates

Tool test

/**
 * @fileoverview Tests for {{TOOL_NAME}} tool.
 * @module mcp-server/tools/definitions/{{TOOL_NAME}}.test
 */

import { describe, expect, it } from 'vitest';
import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
import { {{TOOL_EXPORT}} } from './{{tool-name}}.tool.js';

describe('{{TOOL_EXPORT}}', () => {
  it('returns expected output for valid input', async () => {
    const ctx = createMockContext();
    const input = {{TOOL_EXPORT}}.input.parse({
      // valid input matching the Zod schema
    });
    const result = await {{TOOL_EXPORT}}.handler(input, ctx);
    expect(result).toMatchObject({
      // expected output shape
    });
  });

  it('throws on invalid state', async () => {
    const ctx = createMockContext();
    const input = {{TOOL_EXPORT}}.input.parse({
      // input that triggers an error path
    });
    await expect({{TOOL_EXPORT}}.handler(input, ctx)).rejects.toThrow();
  });

  it('formats output correctly', () => {
    const output = { /* mock output matching the output schema */ };
    const blocks = {{TOOL_EXPORT}}.format!(output);
    expect(blocks).toHaveLength(1);
    expect(blocks[0].type).toBe('text');
  });
});