Add Test

framework-skills/api-testing/SKILL.md

/**
 * @fileoverview Tests for {{TOOL_NAME}} tool.
 * @module tests/tools/{{TOOL_NAME}}.tool.test
 */

import { describe, expect, it } from 'vitest';
import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
import { {{TOOL_EXPORT}} } from '@/mcp-server/tools/definitions/{{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();
  });

  // Only when the tool declares `errors: [...]`. Drop this block otherwise.
  it('throws ctx.fail("{{REASON}}") for the declared failure mode', async () => {
    const ctx = createMockContext({ errors: {{TOOL_EXPORT}}.errors });
    const input = {{TOOL_EXPORT}}.input.parse({
      // input that triggers the declared failure mode
    });
    await expect({{TOOL_EXPORT}}.handler(input, ctx)).rejects.toMatchObject({
      data: { reason: '{{REASON}}' },
    });
  });

  it('formats output completely', () => {
    const output = { /* mock output matching the output schema */ };
    const blocks = {{TOOL_EXPORT}}.format!(output);
    expect(blocks.some((block) => block.type === 'text')).toBe(true);
    // Assert the rendered text includes the IDs/fields the LLM needs to act on.
  });
});

/**
 * @fileoverview Tests for {{RESOURCE_NAME}} resource.
 * @module tests/resources/{{RESOURCE_NAME}}.resource.test
 */

import { describe, expect, it } from 'vitest';
import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
import { {{RESOURCE_EXPORT}} } from '@/mcp-server/resources/definitions/{{resource-name}}.resource.js';

describe('{{RESOURCE_EXPORT}}', () => {
  it('returns data for valid params', async () => {
    const ctx = createMockContext({ tenantId: 'test-tenant' });
    const params = {{RESOURCE_EXPORT}}.params.parse({
      // valid params matching the Zod schema
    });
    const result = await {{RESOURCE_EXPORT}}.handler(params, ctx);
    expect(result).toBeDefined();
  });

  it('throws when resource not found', async () => {
    const ctx = createMockContext({ tenantId: 'test-tenant' });
    const params = {{RESOURCE_EXPORT}}.params.parse({
      // params for a non-existent resource
    });
    await expect({{RESOURCE_EXPORT}}.handler(params, ctx)).rejects.toThrow();
  });

  // For resources that declare an `errors: [...]` contract, pass the contract via
  // `createMockContext` so the typed `ctx.fail` is wired automatically:
  //   const ctx = createMockContext({ errors: {{RESOURCE_EXPORT}}.errors });
  //   const err = await {{RESOURCE_EXPORT}}.handler(params, ctx).catch((e) => e);
  //   expect(err.code).toBe(JsonRpcErrorCode.NotFound);
  //   expect(err.data.reason).toBe('no_match');

  // Include this block only when the resource definition exports a `list` function.
  // Check the source — `list` is optional on resource definitions.
  it('lists available resources', async () => {
    const listing = await {{RESOURCE_EXPORT}}.list!();
    expect(listing.resources).toBeInstanceOf(Array);
    expect(listing.resources.length).toBeGreaterThan(0);
    for (const r of listing.resources) {
      expect(r).toHaveProperty('uri');
      expect(r).toHaveProperty('name');
    }
  });
});

/**
 * @fileoverview Tests for {{SERVICE_NAME}} service.
 * @module tests/services/{{domain}}/{{domain}}-service.test
 */

import { beforeEach, describe, expect, it } from 'vitest';
import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
import { StorageService } from '@cyanheads/mcp-ts-core/storage';
import { get{{ServiceClass}}, init{{ServiceClass}} } from '@/services/{{domain}}/{{domain}}-service.js';

// Derive the minimal mock config from src/config/server-config.ts — read
// the server's Zod schema to see which fields init{{ServiceClass}}() needs.
const mockConfig = { /* fields from server config schema */ } as AppConfig;

describe('{{ServiceClass}}', () => {
  beforeEach(async () => {
    const mockStorage = await StorageService.create({ type: 'in-memory' });
    init{{ServiceClass}}(mockConfig, mockStorage);
  });

  it('performs the expected operation', async () => {
    const ctx = createMockContext({ tenantId: 'test-tenant' });
    const service = get{{ServiceClass}}();
    const result = await service.doWork('input', ctx);
    expect(result).toBeDefined();
  });
});

import { isInputRequiredSignal } from '@cyanheads/mcp-ts-core';
import { createMockContext } from '@cyanheads/mcp-ts-core/testing';

it('requests the missing input on the first round', async () => {
  const ctx = createMockContext();
  const input = {{TOOL_EXPORT}}.input.parse({ path: '/tmp/x' });

  try {
    await {{TOOL_EXPORT}}.handler(input, ctx);
    throw new Error('Expected the handler to request input.');
  } catch (error) {
    if (!isInputRequiredSignal(error)) throw error;
    expect(Object.keys(error.result.inputRequests ?? {})).toEqual(['confirm']);
  }
});

it('completes once the response is supplied', async () => {
  const ctx = createMockContext({
    inputResponses: { confirm: { action: 'accept', content: { confirm: true } } },
  });
  const input = {{TOOL_EXPORT}}.input.parse({ path: '/tmp/x' });

  await expect({{TOOL_EXPORT}}.handler(input, ctx)).resolves.toMatchObject({ deleted: '/tmp/x' });
});

it('does not re-ask after a decline', async () => {
  const ctx = createMockContext({ inputResponses: { confirm: { action: 'decline' } } });
  const input = {{TOOL_EXPORT}}.input.parse({ path: '/tmp/x' });

  // Terminal, not another round — re-asking would burn the round budget.
  await expect({{TOOL_EXPORT}}.handler(input, ctx)).rejects.toThrow(McpError);
});