Test Structure

Understanding how to organize and structure your MCP Jest tests for maximum effectiveness.

Test File Anatomy

Every MCP Jest test file follows this basic structure:

{
  // Test suite metadata
  "name": "My Test Suite",
  "description": "Optional detailed description",
  "version": "1.0.0",
  
  // Server configuration
  "server": {
    "command": "node",
    "args": ["my-server.js"],
    "env": { "NODE_ENV": "test" },
    "cwd": "./server",
    "timeout": 30000
  },
  
  // Global settings
  "timeout": 10000,
  "retries": 2,
  "bail": false,
  
  // Test definitions
  "tests": [
    // Individual test objects...
  ],
  
  // Snapshot configuration
  "snapshots": {
    "updateSnapshots": false,
    "snapshotDir": "__snapshots__"
  }
}

Server Configuration

The server section defines how MCP Jest should start and connect to your server:

Basic Configuration

"server": {
  "command": "node",
  "args": ["server.js", "--port", "3000"],
  "env": {
    "NODE_ENV": "test",
    "LOG_LEVEL": "silent"
  }
}

Advanced Configuration

"server": {
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "cwd": "./python-server",
  "env": {
    "PYTHONPATH": "./src",
    "DEBUG": "true"
  },
  "timeout": 15000,
  "killSignal": "SIGTERM"
}

Executable Configuration

"server": {
  "command": "./my-compiled-server",
  "args": ["--config", "test.yaml"],
  "env": {
    "CONFIG_ENV": "test"
  }
}

Test Types

MCP Jest supports several types of tests, each designed for different aspects of your server:

🔍 Capabilities Test

Tests server metadata and capabilities

{
  "name": "Server should identify itself",
  "type": "capabilities",
  "expect": {
    "name": "my-server",
    "version": "1.0.0",
    "capabilities": {
      "tools": {},
      "resources": {}
    }
  }
}

🛠️ Tools Test

Tests tool listing and metadata

{
  "name": "Should list all available tools",
  "type": "tools",
  "expect": {
    "tools": [
      {
        "name": "calculate",
        "description": "Perform calculations"
      }
    ]
  }
}

⚡ Tool Execution Test

Tests individual tool calls

{
  "name": "Calculator should add numbers",
  "type": "tool",
  "tool": "calculate",
  "arguments": {
    "operation": "add",
    "a": 5,
    "b": 3
  },
  "expect": {
    "result": 8
  }
}

📄 Resources Test

Tests resource listing

{
  "name": "Should list config resources",
  "type": "resources",
  "expect": {
    "resources": [
      {
        "uri": "file://config.json",
        "name": "Configuration"
      }
    ]
  }
}

📖 Resource Read Test

Tests reading specific resources

{
  "name": "Should read config file",
  "type": "resource",
  "resource": "file://config.json",
  "expect": {
    "contents": [
      {
        "mimeType": "application/json",
        "text": "{ \"version\": \"1.0\" }"
      }
    ]
  }
}

Test Organization

Grouping Tests

You can organize related tests using descriptive names and comments:

{
  "name": "Calculator Server Test Suite",
  "tests": [
    // === Basic Functionality ===
    {
      "name": "[Setup] Server should start correctly",
      "type": "capabilities"
    },
    {
      "name": "[Setup] Tools should be available",
      "type": "tools"
    },
    
    // === Addition Tests ===
    {
      "name": "[Add] Should add positive numbers",
      "type": "tool",
      "tool": "calculate"
    },
    {
      "name": "[Add] Should add negative numbers",
      "type": "tool", 
      "tool": "calculate"
    },
    
    // === Error Handling ===
    {
      "name": "[Error] Should handle division by zero",
      "type": "tool",
      "tool": "calculate",
      "expectError": true
    }
  ]
}

Multiple Test Files

For larger projects, split tests across multiple files:

tests/
├── basic-functionality.json    # Core features
├── calculator-tests.json       # Calculator tool tests
├── file-operations.json        # File handling tests
├── error-handling.json         # Error scenarios
└── integration-tests.json      # End-to-end tests

Run all tests with glob patterns:

mcp-jest tests/*.json

Test Configuration Options

Individual Test Settings

{
  "name": "Slow operation test",
  "type": "tool",
  "tool": "slow-operation",
  "timeout": 60000,        // Override global timeout
  "retries": 3,           // Retry failed test 3 times
  "skip": false,          // Skip this test
  "only": false,          // Only run this test
  "description": "Tests a slow operation that might need retries"
}

Conditional Tests

{
  "name": "Platform-specific test",
  "type": "tool",
  "tool": "platform-tool",
  "skipIf": {
    "platform": "win32"     // Skip on Windows
  },
  "runIf": {
    "env": "NODE_ENV",      // Only run if NODE_ENV is set
    "value": "test"
  }
}

Best Practices

✅ Do

• Use descriptive test names that explain what you're testing
• Group related tests with consistent naming conventions
• Test both success and error scenarios
• Start with basic capability tests before testing tools
• Use timeouts appropriate for your server's performance

❌ Don't

• Make tests dependent on external services unless necessary
• Use overly long timeouts that slow down your test suite
• Put all tests in a single massive file
• Skip error handling tests
• Use production data in tests

📚 Next Steps

Now that you understand test structure, learn about different ways to validate responses.

Learn About Expectations →