@frontmcp/testing 0.5.0

package/src/matchers/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file index.ts
+ * @description Barrel exports for MCP Jest matchers
+ */
+export { mcpMatchers } from './mcp-matchers';
+export type { McpMatchers } from './matcher-types';
+import './matcher-types';

package/src/matchers/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * @file index.ts
+ * @description Barrel exports for MCP Jest matchers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpMatchers = void 0;
+var mcp_matchers_1 = require("./mcp-matchers");
+Object.defineProperty(exports, "mcpMatchers", { enumerable: true, get: function () { return mcp_matchers_1.mcpMatchers; } });
+// Import the type augmentation to make TypeScript aware of the matchers
+require("./matcher-types");
+//# sourceMappingURL=index.js.map

package/src/matchers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/matchers/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AAKpB,wEAAwE;AACxE,2BAAyB","sourcesContent":["/**\n * @file index.ts\n * @description Barrel exports for MCP Jest matchers\n */\n\nexport { mcpMatchers } from './mcp-matchers';\n\n// Re-export types for convenience\nexport type { McpMatchers } from './matcher-types';\n\n// Import the type augmentation to make TypeScript aware of the matchers\nimport './matcher-types';\n"]}

package/src/matchers/matcher-types.d.ts

@@ -0,0 +1,266 @@
+/**
+ * @file matcher-types.ts
+ * @description TypeScript declarations for custom MCP Jest matchers
+ *
+ * This file extends Jest's expect interface with MCP-specific matchers.
+ * Import this file or ensure it's included in your tsconfig to get type checking.
+ */
+/**
+ * Custom MCP matchers for Jest
+ */
+export interface McpMatchers<R = unknown> {
+    /**
+     * Check if tools array contains a tool with the given name
+     * @param toolName - The name of the tool to find
+     *
+     * @example
+     * ```typescript
+     * const tools = await mcp.tools.list();
+     * expect(tools).toContainTool('my-tool');
+     * ```
+     */
+    toContainTool(toolName: string): R;
+    /**
+     * Check if result is successful (not an error)
+     *
+     * @example
+     * ```typescript
+     * const result = await mcp.tools.call('my-tool', {});
+     * expect(result).toBeSuccessful();
+     * ```
+     */
+    toBeSuccessful(): R;
+    /**
+     * Check if result is an error, optionally with a specific error code
+     * @param expectedCode - Optional specific MCP error code to match
+     *
+     * @example
+     * ```typescript
+     * const result = await mcp.tools.call('unknown-tool', {});
+     * expect(result).toBeError();
+     * expect(result).toBeError(-32601); // Method not found
+     * ```
+     */
+    toBeError(expectedCode?: number): R;
+    /**
+     * Check if tool result has text content, optionally containing specific text
+     * @param expectedText - Optional text that should be contained in the result
+     *
+     * @example
+     * ```typescript
+     * const result = await mcp.tools.call('my-tool', {});
+     * expect(result).toHaveTextContent();
+     * expect(result).toHaveTextContent('success');
+     * ```
+     */
+    toHaveTextContent(expectedText?: string): R;
+    /**
+     * Check if tool result has image content
+     *
+     * @example
+     * ```typescript
+     * const result = await mcp.tools.call('generate-image', {});
+     * expect(result).toHaveImageContent();
+     * ```
+     */
+    toHaveImageContent(): R;
+    /**
+     * Check if tool result has resource content
+     *
+     * @example
+     * ```typescript
+     * const result = await mcp.tools.call('create-file', {});
+     * expect(result).toHaveResourceContent();
+     * ```
+     */
+    toHaveResourceContent(): R;
+    /**
+     * Check if resources array contains a resource with the given URI
+     * @param uri - The URI of the resource to find
+     *
+     * @example
+     * ```typescript
+     * const resources = await mcp.resources.list();
+     * expect(resources).toContainResource('notes://all');
+     * ```
+     */
+    toContainResource(uri: string): R;
+    /**
+     * Check if resource templates array contains a template with the given URI template
+     * @param uriTemplate - The URI template to find
+     *
+     * @example
+     * ```typescript
+     * const templates = await mcp.resources.listTemplates();
+     * expect(templates).toContainResourceTemplate('notes://note/{id}');
+     * ```
+     */
+    toContainResourceTemplate(uriTemplate: string): R;
+    /**
+     * Check if resource content has a specific MIME type
+     * @param mimeType - The expected MIME type
+     *
+     * @example
+     * ```typescript
+     * const content = await mcp.resources.read('notes://all');
+     * expect(content).toHaveMimeType('application/json');
+     * ```
+     */
+    toHaveMimeType(mimeType: string): R;
+    /**
+     * Check if prompts array contains a prompt with the given name
+     * @param name - The name of the prompt to find
+     *
+     * @example
+     * ```typescript
+     * const prompts = await mcp.prompts.list();
+     * expect(prompts).toContainPrompt('summarize');
+     * ```
+     */
+    toContainPrompt(name: string): R;
+    /**
+     * Check if prompt result has a specific number of messages
+     * @param count - The expected number of messages
+     *
+     * @example
+     * ```typescript
+     * const result = await mcp.prompts.get('summarize', {});
+     * expect(result).toHaveMessages(2);
+     * ```
+     */
+    toHaveMessages(count: number): R;
+    /**
+     * Check if response is valid JSON-RPC 2.0
+     *
+     * @example
+     * ```typescript
+     * const response = await mcp.raw.request({ ... });
+     * expect(response).toBeValidJsonRpc();
+     * ```
+     */
+    toBeValidJsonRpc(): R;
+    /**
+     * Check if JSON-RPC response has a result
+     *
+     * @example
+     * ```typescript
+     * const response = await mcp.raw.request({ ... });
+     * expect(response).toHaveResult();
+     * ```
+     */
+    toHaveResult(): R;
+    /**
+     * Check if JSON-RPC response has an error
+     *
+     * @example
+     * ```typescript
+     * const response = await mcp.raw.request({ method: 'unknown' });
+     * expect(response).toHaveError();
+     * ```
+     */
+    toHaveError(): R;
+    /**
+     * Check if JSON-RPC response has a specific error code
+     * @param code - The expected JSON-RPC error code
+     *
+     * @example
+     * ```typescript
+     * const response = await mcp.raw.request({ method: 'unknown' });
+     * expect(response).toHaveErrorCode(-32601);
+     * ```
+     */
+    toHaveErrorCode(code: number): R;
+    /**
+     * Check if tool result has rendered HTML in _meta['ui/html'].
+     * Fails if the HTML is the mdx-fallback (escaped raw content).
+     *
+     * @example
+     * ```typescript
+     * const result = await mcp.tools.call('get_weather', { location: 'London' });
+     * expect(result).toHaveRenderedHtml();
+     * ```
+     */
+    toHaveRenderedHtml(): R;
+    /**
+     * Check if HTML contains a specific HTML element tag.
+     * @param tag - The HTML tag name to look for (e.g., 'div', 'h1', 'span')
+     *
+     * @example
+     * ```typescript
+     * expect(result).toContainHtmlElement('div');
+     * expect(result).toContainHtmlElement('h1');
+     * ```
+     */
+    toContainHtmlElement(tag: string): R;
+    /**
+     * Check if a bound value from tool output appears in the rendered HTML.
+     * @param value - The value to look for (string or number)
+     *
+     * @example
+     * ```typescript
+     * const output = result.json();
+     * expect(result).toContainBoundValue(output.location);
+     * expect(result).toContainBoundValue(output.temperature);
+     * ```
+     */
+    toContainBoundValue(value: string | number): R;
+    /**
+     * Check if HTML is XSS-safe (no script tags, event handlers, or javascript: URIs).
+     *
+     * @example
+     * ```typescript
+     * expect(result).toBeXssSafe();
+     * ```
+     */
+    toBeXssSafe(): R;
+    /**
+     * Check if tool result has widget metadata (ui/resourceUri).
+     *
+     * @example
+     * ```typescript
+     * expect(result).toHaveWidgetMetadata();
+     * ```
+     */
+    toHaveWidgetMetadata(): R;
+    /**
+     * Check if HTML has a specific CSS class.
+     * @param className - The CSS class name to look for
+     *
+     * @example
+     * ```typescript
+     * expect(result).toHaveCssClass('weather-card');
+     * ```
+     */
+    toHaveCssClass(className: string): R;
+    /**
+     * Check that HTML does NOT contain specific content (useful for fallback checks).
+     * @param content - The content that should NOT be in the HTML
+     *
+     * @example
+     * ```typescript
+     * expect(result).toNotContainRawContent('mdx-fallback');
+     * expect(result).toNotContainRawContent('<Alert'); // Custom component should be rendered
+     * ```
+     */
+    toNotContainRawContent(content: string): R;
+    /**
+     * Check if HTML has proper structure (not just escaped text).
+     *
+     * @example
+     * ```typescript
+     * expect(result).toHaveProperHtmlStructure();
+     * ```
+     */
+    toHaveProperHtmlStructure(): R;
+}
+declare global {
+    namespace jest {
+        interface Matchers<R> extends McpMatchers<R> {
+        }
+        interface Expect extends McpMatchers<void> {
+        }
+        interface InverseAsymmetricMatchers extends McpMatchers<void> {
+        }
+    }
+}
+export {};

package/src/matchers/matcher-types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * @file matcher-types.ts
+ * @description TypeScript declarations for custom MCP Jest matchers
+ *
+ * This file extends Jest's expect interface with MCP-specific matchers.
+ * Import this file or ensure it's included in your tsconfig to get type checking.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=matcher-types.js.map

package/src/matchers/matcher-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher-types.js","sourceRoot":"","sources":["../../../src/matchers/matcher-types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG","sourcesContent":["/**\n * @file matcher-types.ts\n * @description TypeScript declarations for custom MCP Jest matchers\n *\n * This file extends Jest's expect interface with MCP-specific matchers.\n * Import this file or ensure it's included in your tsconfig to get type checking.\n */\n\n// Note: These imports are used for documentation/JSDoc purposes in the interface comments\n// The actual runtime types are in mcp-matchers.ts\n\n/**\n * Custom MCP matchers for Jest\n */\nexport interface McpMatchers<R = unknown> {\n  // ═══════════════════════════════════════════════════════════════════\n  // TOOL MATCHERS\n  // ═══════════════════════════════════════════════════════════════════\n\n  /**\n   * Check if tools array contains a tool with the given name\n   * @param toolName - The name of the tool to find\n   *\n   * @example\n   * ```typescript\n   * const tools = await mcp.tools.list();\n   * expect(tools).toContainTool('my-tool');\n   * ```\n   */\n  toContainTool(toolName: string): R;\n\n  /**\n   * Check if result is successful (not an error)\n   *\n   * @example\n   * ```typescript\n   * const result = await mcp.tools.call('my-tool', {});\n   * expect(result).toBeSuccessful();\n   * ```\n   */\n  toBeSuccessful(): R;\n\n  /**\n   * Check if result is an error, optionally with a specific error code\n   * @param expectedCode - Optional specific MCP error code to match\n   *\n   * @example\n   * ```typescript\n   * const result = await mcp.tools.call('unknown-tool', {});\n   * expect(result).toBeError();\n   * expect(result).toBeError(-32601); // Method not found\n   * ```\n   */\n  toBeError(expectedCode?: number): R;\n\n  /**\n   * Check if tool result has text content, optionally containing specific text\n   * @param expectedText - Optional text that should be contained in the result\n   *\n   * @example\n   * ```typescript\n   * const result = await mcp.tools.call('my-tool', {});\n   * expect(result).toHaveTextContent();\n   * expect(result).toHaveTextContent('success');\n   * ```\n   */\n  toHaveTextContent(expectedText?: string): R;\n\n  /**\n   * Check if tool result has image content\n   *\n   * @example\n   * ```typescript\n   * const result = await mcp.tools.call('generate-image', {});\n   * expect(result).toHaveImageContent();\n   * ```\n   */\n  toHaveImageContent(): R;\n\n  /**\n   * Check if tool result has resource content\n   *\n   * @example\n   * ```typescript\n   * const result = await mcp.tools.call('create-file', {});\n   * expect(result).toHaveResourceContent();\n   * ```\n   */\n  toHaveResourceContent(): R;\n\n  // ═══════════════════════════════════════════════════════════════════\n  // RESOURCE MATCHERS\n  // ═══════════════════════════════════════════════════════════════════\n\n  /**\n   * Check if resources array contains a resource with the given URI\n   * @param uri - The URI of the resource to find\n   *\n   * @example\n   * ```typescript\n   * const resources = await mcp.resources.list();\n   * expect(resources).toContainResource('notes://all');\n   * ```\n   */\n  toContainResource(uri: string): R;\n\n  /**\n   * Check if resource templates array contains a template with the given URI template\n   * @param uriTemplate - The URI template to find\n   *\n   * @example\n   * ```typescript\n   * const templates = await mcp.resources.listTemplates();\n   * expect(templates).toContainResourceTemplate('notes://note/{id}');\n   * ```\n   */\n  toContainResourceTemplate(uriTemplate: string): R;\n\n  /**\n   * Check if resource content has a specific MIME type\n   * @param mimeType - The expected MIME type\n   *\n   * @example\n   * ```typescript\n   * const content = await mcp.resources.read('notes://all');\n   * expect(content).toHaveMimeType('application/json');\n   * ```\n   */\n  toHaveMimeType(mimeType: string): R;\n\n  // ═══════════════════════════════════════════════════════════════════\n  // PROMPT MATCHERS\n  // ═══════════════════════════════════════════════════════════════════\n\n  /**\n   * Check if prompts array contains a prompt with the given name\n   * @param name - The name of the prompt to find\n   *\n   * @example\n   * ```typescript\n   * const prompts = await mcp.prompts.list();\n   * expect(prompts).toContainPrompt('summarize');\n   * ```\n   */\n  toContainPrompt(name: string): R;\n\n  /**\n   * Check if prompt result has a specific number of messages\n   * @param count - The expected number of messages\n   *\n   * @example\n   * ```typescript\n   * const result = await mcp.prompts.get('summarize', {});\n   * expect(result).toHaveMessages(2);\n   * ```\n   */\n  toHaveMessages(count: number): R;\n\n  // ═══════════════════════════════════════════════════════════════════\n  // PROTOCOL MATCHERS\n  // ═══════════════════════════════════════════════════════════════════\n\n  /**\n   * Check if response is valid JSON-RPC 2.0\n   *\n   * @example\n   * ```typescript\n   * const response = await mcp.raw.request({ ... });\n   * expect(response).toBeValidJsonRpc();\n   * ```\n   */\n  toBeValidJsonRpc(): R;\n\n  /**\n   * Check if JSON-RPC response has a result\n   *\n   * @example\n   * ```typescript\n   * const response = await mcp.raw.request({ ... });\n   * expect(response).toHaveResult();\n   * ```\n   */\n  toHaveResult(): R;\n\n  /**\n   * Check if JSON-RPC response has an error\n   *\n   * @example\n   * ```typescript\n   * const response = await mcp.raw.request({ method: 'unknown' });\n   * expect(response).toHaveError();\n   * ```\n   */\n  toHaveError(): R;\n\n  /**\n   * Check if JSON-RPC response has a specific error code\n   * @param code - The expected JSON-RPC error code\n   *\n   * @example\n   * ```typescript\n   * const response = await mcp.raw.request({ method: 'unknown' });\n   * expect(response).toHaveErrorCode(-32601);\n   * ```\n   */\n  toHaveErrorCode(code: number): R;\n\n  // ═══════════════════════════════════════════════════════════════════\n  // UI MATCHERS\n  // ═══════════════════════════════════════════════════════════════════\n\n  /**\n   * Check if tool result has rendered HTML in _meta['ui/html'].\n   * Fails if the HTML is the mdx-fallback (escaped raw content).\n   *\n   * @example\n   * ```typescript\n   * const result = await mcp.tools.call('get_weather', { location: 'London' });\n   * expect(result).toHaveRenderedHtml();\n   * ```\n   */\n  toHaveRenderedHtml(): R;\n\n  /**\n   * Check if HTML contains a specific HTML element tag.\n   * @param tag - The HTML tag name to look for (e.g., 'div', 'h1', 'span')\n   *\n   * @example\n   * ```typescript\n   * expect(result).toContainHtmlElement('div');\n   * expect(result).toContainHtmlElement('h1');\n   * ```\n   */\n  toContainHtmlElement(tag: string): R;\n\n  /**\n   * Check if a bound value from tool output appears in the rendered HTML.\n   * @param value - The value to look for (string or number)\n   *\n   * @example\n   * ```typescript\n   * const output = result.json();\n   * expect(result).toContainBoundValue(output.location);\n   * expect(result).toContainBoundValue(output.temperature);\n   * ```\n   */\n  toContainBoundValue(value: string | number): R;\n\n  /**\n   * Check if HTML is XSS-safe (no script tags, event handlers, or javascript: URIs).\n   *\n   * @example\n   * ```typescript\n   * expect(result).toBeXssSafe();\n   * ```\n   */\n  toBeXssSafe(): R;\n\n  /**\n   * Check if tool result has widget metadata (ui/resourceUri).\n   *\n   * @example\n   * ```typescript\n   * expect(result).toHaveWidgetMetadata();\n   * ```\n   */\n  toHaveWidgetMetadata(): R;\n\n  /**\n   * Check if HTML has a specific CSS class.\n   * @param className - The CSS class name to look for\n   *\n   * @example\n   * ```typescript\n   * expect(result).toHaveCssClass('weather-card');\n   * ```\n   */\n  toHaveCssClass(className: string): R;\n\n  /**\n   * Check that HTML does NOT contain specific content (useful for fallback checks).\n   * @param content - The content that should NOT be in the HTML\n   *\n   * @example\n   * ```typescript\n   * expect(result).toNotContainRawContent('mdx-fallback');\n   * expect(result).toNotContainRawContent('<Alert'); // Custom component should be rendered\n   * ```\n   */\n  toNotContainRawContent(content: string): R;\n\n  /**\n   * Check if HTML has proper structure (not just escaped text).\n   *\n   * @example\n   * ```typescript\n   * expect(result).toHaveProperHtmlStructure();\n   * ```\n   */\n  toHaveProperHtmlStructure(): R;\n}\n\n// ═══════════════════════════════════════════════════════════════════\n// JEST TYPE AUGMENTATION\n// ═══════════════════════════════════════════════════════════════════\n\n/* eslint-disable @typescript-eslint/no-namespace */\n/* eslint-disable @typescript-eslint/no-empty-object-type */\ndeclare global {\n  namespace jest {\n    // Extend expect matchers\n    interface Matchers<R> extends McpMatchers<R> {}\n\n    // Extend asymmetric matchers (for expect.toContainTool etc.)\n    interface Expect extends McpMatchers<void> {}\n\n    // Extend inverse matchers (for expect.not.toContainTool etc.)\n    interface InverseAsymmetricMatchers extends McpMatchers<void> {}\n  }\n}\n/* eslint-enable @typescript-eslint/no-namespace */\n/* eslint-enable @typescript-eslint/no-empty-object-type */\n\n// This export is needed to make this a module\nexport {};\n"]}

package/src/matchers/mcp-matchers.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file mcp-matchers.ts
+ * @description Custom Jest matchers for MCP testing
+ *
+ * @example
+ * ```typescript
+ * import { test, expect } from '@frontmcp/testing';
+ *
+ * test('tools work', async ({ mcp }) => {
+ *   const tools = await mcp.tools.list();
+ *   expect(tools).toContainTool('my-tool');
+ *
+ *   const result = await mcp.tools.call('my-tool', {});
+ *   expect(result).toBeSuccessful();
+ *   expect(result).toHaveTextContent();
+ * });
+ * ```
+ */
+import type { MatcherFunction } from 'expect';
+/**
+ * All MCP matchers as an object for expect.extend()
+ */
+export declare const mcpMatchers: {
+    toHaveRenderedHtml: MatcherFunction<[]>;
+    toContainHtmlElement: MatcherFunction<[tag: string]>;
+    toContainBoundValue: MatcherFunction<[value: string | number]>;
+    toBeXssSafe: MatcherFunction<[]>;
+    toHaveWidgetMetadata: MatcherFunction<[]>;
+    toHaveCssClass: MatcherFunction<[className: string]>;
+    toNotContainRawContent: MatcherFunction<[content: string]>;
+    toHaveProperHtmlStructure: MatcherFunction<[]>;
+    toContainTool: MatcherFunction<[toolName: string]>;
+    toBeSuccessful: MatcherFunction<[]>;
+    toBeError: MatcherFunction<[expectedCode?: number | undefined]>;
+    toHaveTextContent: MatcherFunction<[expectedText?: string | undefined]>;
+    toHaveImageContent: MatcherFunction<[]>;
+    toHaveResourceContent: MatcherFunction<[]>;
+    toContainResource: MatcherFunction<[uri: string]>;
+    toContainResourceTemplate: MatcherFunction<[uriTemplate: string]>;
+    toHaveMimeType: MatcherFunction<[mimeType: string]>;
+    toContainPrompt: MatcherFunction<[name: string]>;
+    toHaveMessages: MatcherFunction<[count: number]>;
+    toBeValidJsonRpc: MatcherFunction<[]>;
+    toHaveResult: MatcherFunction<[]>;
+    toHaveError: MatcherFunction<[]>;
+    toHaveErrorCode: MatcherFunction<[code: number]>;
+};