mcp-programmatic-testing

MCP Programmatic Testing Skill

Use this skill when writing or debugging *.programmatic.test.js files for Model Context Protocol servers.

When to Use Programmatic Tests

• Complex business logic requiring code execution
• Multi-step workflows with state management
• Dynamic test case generation
• Integration with existing JavaScript test suites

For basic functional testing, prefer YAML tests (see mcp-yaml-testing skill).

Basic Test Structure

import { test, describe, before, after, beforeEach } from 'node:test';
import { strict as assert } from 'node:assert';
import { connect } from 'mcp-aegis';

describe('[SERVER_NAME] Programmatic Tests', () => {
  let client;

  before(async () => {
    client = await connect('./aegis.config.docs-only.json');
  });

  after(async () => {
    if (client?.connected) {
      await client.disconnect();
    }
  });

  beforeEach(() => {
    // CRITICAL: Clear buffers to prevent test interference
    client.clearAllBuffers();
  });

  test('should list available tools', async () => {
    const tools = await client.listTools();
    assert.ok(Array.isArray(tools), 'Tools should be array');
    assert.ok(tools.length > 0, 'Should have at least one tool');
  });

  test('should execute tool successfully', async () => {
    const result = await client.callTool('[TOOL_NAME]', { param: 'value' });
    assert.ok(result.content, 'Should return content');
    assert.equal(result.isError, false, 'Should not be error');
  });
});

Critical: Buffer Management

Always include beforeEach with buffer clearing to prevent test flakiness:

beforeEach(() => {
  client.clearAllBuffers();  // Recommended - comprehensive
  // OR: client.clearStderr();  // Minimum - stderr only
});

Without this, stderr from one test can leak into subsequent tests, causing random failures.

Critical: No Concurrent Requests

Never use Promise.all() with MCP requests. MCP uses single stdio with shared buffers: