write-mcp-test

Write MCP Server Tests

Generate Playwright tests for MCP server tools using @gleanwork/mcp-server-tester.

Before You Start

1. Confirm the project has @gleanwork/mcp-server-tester and @playwright/test installed
2. Check that playwright.config.ts has mcpConfig in at least one project's use block
3. Identify which MCP tools to test — run mcp.listTools() or check the server's tool definitions

Step 1 — Verify Playwright Config

Every test project needs an mcpConfig entry. If it doesn't exist, add one:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  projects: [
    {
      name: 'my-mcp-server',
      use: {
        mcpConfig: {
          // stdio transport — for servers started as a subprocess
          transport: 'stdio',
          command: 'node',
          args: ['./dist/server.js'],
        },
        // OR http transport — for servers already running
        // mcpConfig: {
        //   transport: 'http',
        //   url: 'http://localhost:3000/mcp',
        // },
      },
    },
  ],
});

Step 2 — Create Test File

Always import test and expect from the fixtures path:

import { test, expect } from '@gleanwork/mcp-server-tester/fixtures/mcp';

Do NOT import from @gleanwork/mcp-server-tester — that path does not include MCP matchers on expect.

Step 3 — Write Tests

Basic tool test

import { test, expect } from '@gleanwork/mcp-server-tester/fixtures/mcp';

test.describe('search tool', () => {
  test('returns results for a valid query', async ({ mcp }) => {
    const result = await mcp.callTool('search', {
      query: 'quarterly planning',
    });

    expect(result).toContainToolText('quarterly');
    expect(result).not.toBeToolError();
  });

  test('handles empty query gracefully', async ({ mcp }) => {
    const result = await mcp.callTool('search', { query: '' });

    // Assert it returns an error or empty result — not a crash
    expect(result).not.toBeToolError();
  });
});