Snapshot Testing

Capture and validate complex server responses with snapshot testing. Perfect for detecting unintended changes.

What is Snapshot Testing?

Snapshot testing captures the output of your MCP server and stores it as a "snapshot" file. Future test runs compare new output against these stored snapshots, alerting you to any changes.

💡 When to Use Snapshots

• Testing complex API responses with many fields
• Validating generated content (HTML, markdown, code)
• Ensuring UI components render consistently
• Detecting unexpected changes in server behavior
• Regression testing for large data structures

Basic Snapshot Test

Create a snapshot test by setting snapshot: true:

{
  "name": "Complete user profile snapshot",
  "type": "tool",
  "tool": "get-user-profile",
  "arguments": {
    "userId": "test-user-123"
  },
  "snapshot": true
}

On first run, MCP Jest creates a snapshot file:

__snapshots__/
└── my-test.json.snap
    └── Complete user profile snapshot.json

Snapshot File Contents

The generated snapshot file contains the exact server response:

{
  "content": [
    {
      "type": "text",
      "text": "User Profile:\n\nName: John Doe\nEmail: john@example.com\nJoined: 2024-01-15\nStatus: Active\nPreferences:\n- Theme: dark\n- Language: en\n- Notifications: enabled"
    }
  ],
  "metadata": {
    "timestamp": "2024-01-20T10:30:00Z",
    "version": "1.2.3"
  }
}

Selective Snapshots

Snapshot only specific parts of the response using include/exclude patterns:

{
  "name": "User data without timestamps",
  "type": "tool",
  "tool": "get-user",
  "arguments": { "id": "123" },
  "snapshot": {
    "include": ["content", "user"],
    "exclude": ["timestamp", "lastModified", "sessionId"]
  }
}

Dynamic Data Handling

Handle dynamic data that changes between test runs:

{
  "name": "Generated report with dynamic content",
  "type": "tool",
  "tool": "generate-report",
  "arguments": { "type": "monthly" },
  "snapshot": {
    "exclude": ["generatedAt", "reportId"],
    "replacements": [
      {
        "pattern": "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z",
        "replacement": "TIMESTAMP"
      },
      {
        "pattern": "ID: [a-f0-9-]{36}",
        "replacement": "ID: UUID"
      }
    ]
  }
}

Updating Snapshots

When your server behavior legitimately changes, update snapshots:

mcp-jest my-test.json --update-snapshots

Or update specific tests:

mcp-jest my-test.json --update-snapshots="Complete user profile snapshot"

Snapshot Failure Output

When snapshots don't match, MCP Jest shows a detailed diff:

✗ Complete user profile snapshot (234ms)

Snapshot comparison failed!

Expected (snapshot):
{
  "content": [
    {
      "type": "text",
-     "text": "User Profile:\n\nName: John Doe\nEmail: john@example.com\nStatus: Active"
+     "text": "User Profile:\n\nName: John Doe\nEmail: john@example.com\nStatus: Premium"
    }
  ]
}

Received (current):
{
  "content": [
    {
      "type": "text", 
      "text": "User Profile:\n\nName: John Doe\nEmail: john@example.com\nStatus: Premium"
    }
  ]
}

To update this snapshot, run:
  mcp-jest my-test.json --update-snapshots="Complete user profile snapshot"

Snapshot Configuration

Configure snapshots globally in your test file:

{
  "name": "My Test Suite",
  "server": { ... },
  "snapshots": {
    "updateSnapshots": false,
    "snapshotDir": "__snapshots__",
    "snapshotFormat": "json",
    "prettify": true,
    "sortKeys": true,
    "globalExcludes": [
      "timestamp",
      "generatedAt",
      "requestId"
    ],
    "globalReplacements": [
      {
        "pattern": "\\b\\d{13}\\b",
        "replacement": "TIMESTAMP_MS"
      }
    ]
  },
  "tests": [ ... ]
}

Advanced Snapshot Patterns

Inline Snapshots

Store snapshots directly in test files for small responses:

{
  "name": "Simple status check",
  "type": "tool",
  "tool": "status",
  "snapshot": {
    "inline": true,
    "expected": {
      "status": "healthy",
      "uptime": "UPTIME_SECONDS",
      "version": "1.0.0"
    }
  }
}

Multi-Format Snapshots

Snapshot different output formats:

{
  "name": "Document generation in multiple formats",
  "type": "tool",
  "tool": "generate-document",
  "arguments": {
    "format": "html",
    "template": "report"
  },
  "snapshot": {
    "formats": {
      "html": {
        "exclude": ["generated-at"],
        "prettify": true
      },
      "json": {
        "sortKeys": true
      }
    }
  }
}

Conditional Snapshots

Create snapshots based on conditions:

{
  "name": "Environment-specific output",
  "type": "tool",
  "tool": "environment-info",
  "snapshot": {
    "condition": {
      "env": "NODE_ENV",
      "value": "test"
    },
    "name": "test-environment-snapshot"
  }
}

Snapshot Best Practices

✅ Best Practices

• Review snapshot changes carefully before updating
• Exclude dynamic data like timestamps and IDs
• Use descriptive test names for snapshot files
• Keep snapshots focused on relevant data
• Commit snapshot files to version control
• Use replacements for predictable dynamic patterns

❌ Avoid

• Blindly updating snapshots without review
• Including highly volatile data in snapshots
• Creating massive snapshots for complex objects
• Using snapshots for simple value assertions
• Ignoring snapshot failures

Combining Snapshots with Expectations

Use snapshots alongside regular expectations for comprehensive testing:

{
  "name": "User profile with validation and snapshot",
  "type": "tool",
  "tool": "get-user-profile",
  "arguments": { "userId": "123" },
  "expect": {
    "user": {
      "id": "123",
      "status": { "type": "string" }
    }
  },
  "snapshot": {
    "exclude": ["lastAccessed", "sessionId"]
  }
}

📸 Snapshot Mastery

Snapshot testing is powerful for catching regressions and validating complex outputs. Use it wisely to build confidence in your MCP server.

Learn About Configuration →