testing-conventions

Testing Conventions & Techniques

Overview

• Test runner: Vitest (pnpm test, pnpm test:run, pnpm coverage).
• Test files: **/*.spec.ts or **/*.test.ts colocated with code or under server/test.
• Style: Given/When/Then sections with comments. Behavior-oriented test names.

Structure and Patterns

• Unit tests: Target pure logic in services and tool callbacks. Avoid real Strapi.
• MCP tools: Build tool via its builder with a mock strapi, call callback(args, ctx).
• Controllers: Keep minimal; test they delegate and shape responses correctly.
• Services: Assert inputs/outputs; use dependency injection for collaborators.

Strapi Mocking

• Prefer lightweight fakes over deep mocks. Use server/test/strapi.mock.ts for content types/components.
• For specialized cases, create ad-hoc mocks with only required surface:

const strapi = {
  config: { get: vi.fn(() => 'value') },
  services: { 'api::blog.post': {}, 'plugin::mcp.services': {} },
} as unknown as Strapi;

MCP Tool Testing Recipe

1. Build tool: const tool = getXTool(strapi);
2. Validate metadata: name, description, argsSchema (Zod parse with valid/invalid payloads).
3. Invoke: const res = await tool.callback(args as any, {} as any);
4. Extract payload: const text = (res.content?.[0] as any)?.text; const json = JSON.parse(text ?? '{}');
5. Assert json shape: success/isSuccess, data fields, and error messages for negative paths.

Example:

it('returns services list', async () => {
  // Given
  const strapi = { services: { 'api::blog.post': {}, 'plugin::mcp.services': {} } } as any;
  const tool = getServicesTool(strapi);

  // When
  const res = await tool.callback({}, {} as any);

  // Then
  const payload = JSON.parse((res.content?.[0] as any).text ?? '{}');
  expect(payload.success).toBe(true);
  expect(payload.services).toEqual(
    expect.arrayContaining([
      expect.objectContaining({ fullQualifiedName: 'api::blog.post', type: 'internal', name: 'post' }),
      expect.objectContaining({ fullQualifiedName: 'plugin::mcp.services', type: 'plugin', name: 'services', plugin: 'mcp' }),
    ])
  );
});