@frontmcp/testing 0.5.0

package/src/ui/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ui/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,6CAA2C;AAAlC,yGAAA,UAAU,OAAA;AACnB,iDAA+C;AAAtC,6GAAA,YAAY,OAAA","sourcesContent":["/**\n * @file index.ts\n * @description Barrel exports for UI testing utilities\n *\n * @example\n * ```typescript\n * import { uiMatchers, UIAssertions } from '@frontmcp/testing';\n *\n * // Use matchers with expect.extend\n * expect.extend(uiMatchers);\n *\n * // Or use assertion helpers directly\n * const html = UIAssertions.assertRenderedUI(result);\n * ```\n */\n\nexport { uiMatchers } from './ui-matchers';\nexport { UIAssertions } from './ui-assertions';\n"]}

package/src/ui/ui-assertions.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @file ui-assertions.ts
+ * @description UI-specific assertion helpers for testing tool UI responses
+ *
+ * The metadata keys used in these assertions align with the UIMetadata interface
+ * from @frontmcp/ui/adapters. Key fields include:
+ * - `ui/html`: Inline rendered HTML (universal)
+ * - `ui/mimeType`: MIME type for the HTML content
+ * - `openai/outputTemplate`: Resource URI for widget template (OpenAI)
+ * - `openai/widgetAccessible`: Whether widget can invoke tools (OpenAI)
+ *
+ * @see {@link https://docs.agentfront.dev/docs/servers/tools#tool-ui | Tool UI Documentation}
+ *
+ * @example
+ * ```typescript
+ * import { UIAssertions } from '@frontmcp/testing';
+ *
+ * const result = await client.tools.call('my-tool', {});
+ * const html = UIAssertions.assertRenderedUI(result);
+ * UIAssertions.assertXssSafe(html);
+ * UIAssertions.assertDataBinding(html, result.json(), ['location', 'temperature']);
+ * ```
+ */
+import type { ToolResultWrapper } from '../client/mcp-test-client.types';
+/**
+ * UI-specific assertion helpers.
+ * Use these for imperative-style assertions with detailed error messages.
+ */
+export declare const UIAssertions: {
+    /**
+     * Assert tool result has valid rendered UI HTML.
+     * @param result - The tool result wrapper
+     * @returns The rendered HTML string
+     * @throws Error if no UI HTML found or if mdx-fallback detected
+     */
+    assertRenderedUI(result: ToolResultWrapper): string;
+    /**
+     * Assert HTML contains all expected bound values from tool output.
+     * @param html - The rendered HTML string
+     * @param output - The tool output object
+     * @param keys - Array of keys whose values should appear in the HTML
+     * @throws Error if any expected value is missing from the HTML
+     */
+    assertDataBinding(html: string, output: Record<string, unknown>, keys: string[]): void;
+    /**
+     * Assert HTML is XSS-safe (no scripts, event handlers, or javascript: URIs).
+     * @param html - The rendered HTML string
+     * @throws Error if potential XSS vulnerabilities are detected
+     */
+    assertXssSafe(html: string): void;
+    /**
+     * Assert HTML has proper structure (not escaped raw content).
+     * @param html - The rendered HTML string
+     * @throws Error if HTML appears to be raw/unrendered content
+     */
+    assertProperHtmlStructure(html: string): void;
+    /**
+     * Assert HTML contains a specific element.
+     * @param html - The rendered HTML string
+     * @param tag - The HTML tag name to look for
+     * @throws Error if the element is not found
+     */
+    assertContainsElement(html: string, tag: string): void;
+    /**
+     * Assert HTML contains a specific CSS class.
+     * @param html - The rendered HTML string
+     * @param className - The CSS class name to look for
+     * @throws Error if the class is not found
+     */
+    assertHasCssClass(html: string, className: string): void;
+    /**
+     * Assert HTML does NOT contain specific content.
+     * Useful for verifying custom components were rendered, not left as raw tags.
+     * @param html - The rendered HTML string
+     * @param content - The content that should NOT appear
+     * @throws Error if the content is found
+     */
+    assertNotContainsRaw(html: string, content: string): void;
+    /**
+     * Assert that widget metadata is present in the result.
+     * Checks for ui/html, openai/outputTemplate, or ui/mimeType.
+     * @param result - The tool result wrapper
+     * @throws Error if widget metadata is missing
+     */
+    assertWidgetMetadata(result: ToolResultWrapper): void;
+    /**
+     * Comprehensive UI validation that runs all checks.
+     * @param result - The tool result wrapper
+     * @param boundKeys - Optional array of output keys to check for data binding
+     * @returns The rendered HTML string
+     * @throws Error if any validation fails
+     */
+    assertValidUI(result: ToolResultWrapper, boundKeys?: string[]): string;
+};

package/src/ui/ui-assertions.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * @file ui-assertions.ts
+ * @description UI-specific assertion helpers for testing tool UI responses
+ *
+ * The metadata keys used in these assertions align with the UIMetadata interface
+ * from @frontmcp/ui/adapters. Key fields include:
+ * - `ui/html`: Inline rendered HTML (universal)
+ * - `ui/mimeType`: MIME type for the HTML content
+ * - `openai/outputTemplate`: Resource URI for widget template (OpenAI)
+ * - `openai/widgetAccessible`: Whether widget can invoke tools (OpenAI)
+ *
+ * @see {@link https://docs.agentfront.dev/docs/servers/tools#tool-ui | Tool UI Documentation}
+ *
+ * @example
+ * ```typescript
+ * import { UIAssertions } from '@frontmcp/testing';
+ *
+ * const result = await client.tools.call('my-tool', {});
+ * const html = UIAssertions.assertRenderedUI(result);
+ * UIAssertions.assertXssSafe(html);
+ * UIAssertions.assertDataBinding(html, result.json(), ['location', 'temperature']);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UIAssertions = void 0;
+// Type-only reference: Metadata keys used below align with UIMetadata from @frontmcp/ui/adapters
+// This is an optional peer dependency, so we don't import it directly
+// ═══════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Escape special regex metacharacters in a string.
+ * This prevents user-provided tag/class names from being interpreted as regex patterns.
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ═══════════════════════════════════════════════════════════════════
+// UI ASSERTIONS
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * UI-specific assertion helpers.
+ * Use these for imperative-style assertions with detailed error messages.
+ */
+exports.UIAssertions = {
+    /**
+     * Assert tool result has valid rendered UI HTML.
+     * @param result - The tool result wrapper
+     * @returns The rendered HTML string
+     * @throws Error if no UI HTML found or if mdx-fallback detected
+     */
+    assertRenderedUI(result) {
+        const meta = result.raw._meta;
+        if (!meta) {
+            throw new Error('Expected tool result to have _meta, but _meta is undefined');
+        }
+        const html = meta['ui/html'];
+        if (!html) {
+            throw new Error('Expected tool result to have ui/html in _meta, but it is missing');
+        }
+        if (typeof html !== 'string') {
+            throw new Error(`Expected ui/html to be a string, but got ${typeof html}`);
+        }
+        if (html.includes('mdx-fallback')) {
+            throw new Error('Got mdx-fallback instead of rendered HTML - MDX/React rendering failed. ' +
+                'Check that @mdx-js/mdx is installed and the template syntax is valid.');
+        }
+        return html;
+    },
+    /**
+     * Assert HTML contains all expected bound values from tool output.
+     * @param html - The rendered HTML string
+     * @param output - The tool output object
+     * @param keys - Array of keys whose values should appear in the HTML
+     * @throws Error if any expected value is missing from the HTML
+     */
+    assertDataBinding(html, output, keys) {
+        const missingKeys = [];
+        for (const key of keys) {
+            const value = output[key];
+            if (value === undefined || value === null) {
+                continue; // Skip undefined/null values
+            }
+            const stringValue = String(value);
+            if (!html.includes(stringValue)) {
+                missingKeys.push(`${key}="${stringValue}"`);
+            }
+        }
+        if (missingKeys.length > 0) {
+            throw new Error(`Expected HTML to contain bound values for: ${missingKeys.join(', ')}. ` + 'Data binding may have failed.');
+        }
+    },
+    /**
+     * Assert HTML is XSS-safe (no scripts, event handlers, or javascript: URIs).
+     * @param html - The rendered HTML string
+     * @throws Error if potential XSS vulnerabilities are detected
+     */
+    assertXssSafe(html) {
+        const vulnerabilities = [];
+        if (/<script[\s>]/i.test(html)) {
+            vulnerabilities.push('<script> tag detected');
+        }
+        if (/\son\w+\s*=/i.test(html)) {
+            vulnerabilities.push('inline event handler detected (onclick, onerror, etc.)');
+        }
+        if (/javascript:/i.test(html)) {
+            vulnerabilities.push('javascript: URI detected');
+        }
+        if (vulnerabilities.length > 0) {
+            throw new Error(`Potential XSS vulnerabilities found: ${vulnerabilities.join('; ')}`);
+        }
+    },
+    /**
+     * Assert HTML has proper structure (not escaped raw content).
+     * @param html - The rendered HTML string
+     * @throws Error if HTML appears to be raw/unrendered content
+     */
+    assertProperHtmlStructure(html) {
+        // Check for escaped HTML entities that suggest content wasn't rendered
+        if (html.includes('&lt;') && html.includes('&gt;')) {
+            throw new Error('HTML contains escaped HTML entities (&lt;, &gt;) - content was likely not rendered. ' +
+                'Check that the template is being processed correctly.');
+        }
+        // Check that there's at least one HTML tag
+        if (!/<[a-z]/i.test(html)) {
+            throw new Error('HTML contains no HTML tags - content may be plain text or rendering failed.');
+        }
+    },
+    /**
+     * Assert HTML contains a specific element.
+     * @param html - The rendered HTML string
+     * @param tag - The HTML tag name to look for
+     * @throws Error if the element is not found
+     */
+    assertContainsElement(html, tag) {
+        // Escape regex metacharacters to prevent user input from breaking the regex
+        const regex = new RegExp(`<${escapeRegex(tag)}[\\s>]`, 'i');
+        if (!regex.test(html)) {
+            throw new Error(`Expected HTML to contain <${tag}> element`);
+        }
+    },
+    /**
+     * Assert HTML contains a specific CSS class.
+     * @param html - The rendered HTML string
+     * @param className - The CSS class name to look for
+     * @throws Error if the class is not found
+     */
+    assertHasCssClass(html, className) {
+        // Escape regex metacharacters to prevent user input from breaking the regex
+        const classRegex = new RegExp(`class(?:Name)?\\s*=\\s*["'][^"']*\\b${escapeRegex(className)}\\b[^"']*["']`, 'i');
+        if (!classRegex.test(html)) {
+            throw new Error(`Expected HTML to have CSS class "${className}"`);
+        }
+    },
+    /**
+     * Assert HTML does NOT contain specific content.
+     * Useful for verifying custom components were rendered, not left as raw tags.
+     * @param html - The rendered HTML string
+     * @param content - The content that should NOT appear
+     * @throws Error if the content is found
+     */
+    assertNotContainsRaw(html, content) {
+        if (html.includes(content)) {
+            throw new Error(`HTML contains raw content "${content}" - this component may not have been rendered. ` +
+                'Check that all custom components are properly passed to the renderer.');
+        }
+    },
+    /**
+     * Assert that widget metadata is present in the result.
+     * Checks for ui/html, openai/outputTemplate, or ui/mimeType.
+     * @param result - The tool result wrapper
+     * @throws Error if widget metadata is missing
+     */
+    assertWidgetMetadata(result) {
+        const meta = result.raw._meta;
+        if (!meta) {
+            throw new Error('Expected tool result to have _meta with widget metadata');
+        }
+        // Check for any widget-related metadata fields (aligned with toHaveWidgetMetadata matcher)
+        const hasUiHtml = Boolean(meta['ui/html']);
+        const hasOutputTemplate = Boolean(meta['openai/outputTemplate']);
+        const hasMimeType = Boolean(meta['ui/mimeType']);
+        if (!hasUiHtml && !hasOutputTemplate && !hasMimeType) {
+            throw new Error('Expected _meta to have widget metadata (ui/html, openai/outputTemplate, or ui/mimeType)');
+        }
+    },
+    /**
+     * Comprehensive UI validation that runs all checks.
+     * @param result - The tool result wrapper
+     * @param boundKeys - Optional array of output keys to check for data binding
+     * @returns The rendered HTML string
+     * @throws Error if any validation fails
+     */
+    assertValidUI(result, boundKeys) {
+        // 1. Get and validate HTML exists
+        const html = exports.UIAssertions.assertRenderedUI(result);
+        // 2. Check HTML structure
+        exports.UIAssertions.assertProperHtmlStructure(html);
+        // 3. Check XSS safety
+        exports.UIAssertions.assertXssSafe(html);
+        // 4. Check data binding if keys provided
+        if (boundKeys && boundKeys.length > 0) {
+            try {
+                const output = JSON.parse(result.text() || '{}');
+                exports.UIAssertions.assertDataBinding(html, output, boundKeys);
+            }
+            catch {
+                // If we can't parse output, skip data binding check
+            }
+        }
+        return html;
+    },
+};
+//# sourceMappingURL=ui-assertions.js.map

package/src/ui/ui-assertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-assertions.js","sourceRoot":"","sources":["../../../src/ui/ui-assertions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @file ui-assertions.ts\n * @description UI-specific assertion helpers for testing tool UI responses\n *\n * The metadata keys used in these assertions align with the UIMetadata interface\n * from @frontmcp/ui/adapters. Key fields include:\n * - `ui/html`: Inline rendered HTML (universal)\n * - `ui/mimeType`: MIME type for the HTML content\n * - `openai/outputTemplate`: Resource URI for widget template (OpenAI)\n * - `openai/widgetAccessible`: Whether widget can invoke tools (OpenAI)\n *\n * @see {@link https://docs.agentfront.dev/docs/servers/tools#tool-ui | Tool UI Documentation}\n *\n * @example\n * ```typescript\n * import { UIAssertions } from '@frontmcp/testing';\n *\n * const result = await client.tools.call('my-tool', {});\n * const html = UIAssertions.assertRenderedUI(result);\n * UIAssertions.assertXssSafe(html);\n * UIAssertions.assertDataBinding(html, result.json(), ['location', 'temperature']);\n * ```\n */\n\nimport type { ToolResultWrapper } from '../client/mcp-test-client.types';\n\n// Type-only reference: Metadata keys used below align with UIMetadata from @frontmcp/ui/adapters\n// This is an optional peer dependency, so we don't import it directly\n\n// ═══════════════════════════════════════════════════════════════════\n// HELPER FUNCTIONS\n// ═══════════════════════════════════════════════════════════════════\n\n/**\n * Escape special regex metacharacters in a string.\n * This prevents user-provided tag/class names from being interpreted as regex patterns.\n */\nfunction escapeRegex(str: string): string {\n  return str.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n// ═══════════════════════════════════════════════════════════════════\n// UI ASSERTIONS\n// ═══════════════════════════════════════════════════════════════════\n\n/**\n * UI-specific assertion helpers.\n * Use these for imperative-style assertions with detailed error messages.\n */\nexport const UIAssertions = {\n  /**\n   * Assert tool result has valid rendered UI HTML.\n   * @param result - The tool result wrapper\n   * @returns The rendered HTML string\n   * @throws Error if no UI HTML found or if mdx-fallback detected\n   */\n  assertRenderedUI(result: ToolResultWrapper): string {\n    const meta = result.raw._meta as Record<string, unknown> | undefined;\n\n    if (!meta) {\n      throw new Error('Expected tool result to have _meta, but _meta is undefined');\n    }\n\n    const html = meta['ui/html'];\n\n    if (!html) {\n      throw new Error('Expected tool result to have ui/html in _meta, but it is missing');\n    }\n\n    if (typeof html !== 'string') {\n      throw new Error(`Expected ui/html to be a string, but got ${typeof html}`);\n    }\n\n    if (html.includes('mdx-fallback')) {\n      throw new Error(\n        'Got mdx-fallback instead of rendered HTML - MDX/React rendering failed. ' +\n          'Check that @mdx-js/mdx is installed and the template syntax is valid.',\n      );\n    }\n\n    return html;\n  },\n\n  /**\n   * Assert HTML contains all expected bound values from tool output.\n   * @param html - The rendered HTML string\n   * @param output - The tool output object\n   * @param keys - Array of keys whose values should appear in the HTML\n   * @throws Error if any expected value is missing from the HTML\n   */\n  assertDataBinding(html: string, output: Record<string, unknown>, keys: string[]): void {\n    const missingKeys: string[] = [];\n\n    for (const key of keys) {\n      const value = output[key];\n      if (value === undefined || value === null) {\n        continue; // Skip undefined/null values\n      }\n\n      const stringValue = String(value);\n      if (!html.includes(stringValue)) {\n        missingKeys.push(`${key}=\"${stringValue}\"`);\n      }\n    }\n\n    if (missingKeys.length > 0) {\n      throw new Error(\n        `Expected HTML to contain bound values for: ${missingKeys.join(', ')}. ` + 'Data binding may have failed.',\n      );\n    }\n  },\n\n  /**\n   * Assert HTML is XSS-safe (no scripts, event handlers, or javascript: URIs).\n   * @param html - The rendered HTML string\n   * @throws Error if potential XSS vulnerabilities are detected\n   */\n  assertXssSafe(html: string): void {\n    const vulnerabilities: string[] = [];\n\n    if (/<script[\\s>]/i.test(html)) {\n      vulnerabilities.push('<script> tag detected');\n    }\n\n    if (/\\son\\w+\\s*=/i.test(html)) {\n      vulnerabilities.push('inline event handler detected (onclick, onerror, etc.)');\n    }\n\n    if (/javascript:/i.test(html)) {\n      vulnerabilities.push('javascript: URI detected');\n    }\n\n    if (vulnerabilities.length > 0) {\n      throw new Error(`Potential XSS vulnerabilities found: ${vulnerabilities.join('; ')}`);\n    }\n  },\n\n  /**\n   * Assert HTML has proper structure (not escaped raw content).\n   * @param html - The rendered HTML string\n   * @throws Error if HTML appears to be raw/unrendered content\n   */\n  assertProperHtmlStructure(html: string): void {\n    // Check for escaped HTML entities that suggest content wasn't rendered\n    if (html.includes('&lt;') && html.includes('&gt;')) {\n      throw new Error(\n        'HTML contains escaped HTML entities (&lt;, &gt;) - content was likely not rendered. ' +\n          'Check that the template is being processed correctly.',\n      );\n    }\n\n    // Check that there's at least one HTML tag\n    if (!/<[a-z]/i.test(html)) {\n      throw new Error('HTML contains no HTML tags - content may be plain text or rendering failed.');\n    }\n  },\n\n  /**\n   * Assert HTML contains a specific element.\n   * @param html - The rendered HTML string\n   * @param tag - The HTML tag name to look for\n   * @throws Error if the element is not found\n   */\n  assertContainsElement(html: string, tag: string): void {\n    // Escape regex metacharacters to prevent user input from breaking the regex\n    const regex = new RegExp(`<${escapeRegex(tag)}[\\\\s>]`, 'i');\n    if (!regex.test(html)) {\n      throw new Error(`Expected HTML to contain <${tag}> element`);\n    }\n  },\n\n  /**\n   * Assert HTML contains a specific CSS class.\n   * @param html - The rendered HTML string\n   * @param className - The CSS class name to look for\n   * @throws Error if the class is not found\n   */\n  assertHasCssClass(html: string, className: string): void {\n    // Escape regex metacharacters to prevent user input from breaking the regex\n    const classRegex = new RegExp(`class(?:Name)?\\\\s*=\\\\s*[\"'][^\"']*\\\\b${escapeRegex(className)}\\\\b[^\"']*[\"']`, 'i');\n    if (!classRegex.test(html)) {\n      throw new Error(`Expected HTML to have CSS class \"${className}\"`);\n    }\n  },\n\n  /**\n   * Assert HTML does NOT contain specific content.\n   * Useful for verifying custom components were rendered, not left as raw tags.\n   * @param html - The rendered HTML string\n   * @param content - The content that should NOT appear\n   * @throws Error if the content is found\n   */\n  assertNotContainsRaw(html: string, content: string): void {\n    if (html.includes(content)) {\n      throw new Error(\n        `HTML contains raw content \"${content}\" - this component may not have been rendered. ` +\n          'Check that all custom components are properly passed to the renderer.',\n      );\n    }\n  },\n\n  /**\n   * Assert that widget metadata is present in the result.\n   * Checks for ui/html, openai/outputTemplate, or ui/mimeType.\n   * @param result - The tool result wrapper\n   * @throws Error if widget metadata is missing\n   */\n  assertWidgetMetadata(result: ToolResultWrapper): void {\n    const meta = result.raw._meta as Record<string, unknown> | undefined;\n\n    if (!meta) {\n      throw new Error('Expected tool result to have _meta with widget metadata');\n    }\n\n    // Check for any widget-related metadata fields (aligned with toHaveWidgetMetadata matcher)\n    const hasUiHtml = Boolean(meta['ui/html']);\n    const hasOutputTemplate = Boolean(meta['openai/outputTemplate']);\n    const hasMimeType = Boolean(meta['ui/mimeType']);\n\n    if (!hasUiHtml && !hasOutputTemplate && !hasMimeType) {\n      throw new Error('Expected _meta to have widget metadata (ui/html, openai/outputTemplate, or ui/mimeType)');\n    }\n  },\n\n  /**\n   * Comprehensive UI validation that runs all checks.\n   * @param result - The tool result wrapper\n   * @param boundKeys - Optional array of output keys to check for data binding\n   * @returns The rendered HTML string\n   * @throws Error if any validation fails\n   */\n  assertValidUI(result: ToolResultWrapper, boundKeys?: string[]): string {\n    // 1. Get and validate HTML exists\n    const html = UIAssertions.assertRenderedUI(result);\n\n    // 2. Check HTML structure\n    UIAssertions.assertProperHtmlStructure(html);\n\n    // 3. Check XSS safety\n    UIAssertions.assertXssSafe(html);\n\n    // 4. Check data binding if keys provided\n    if (boundKeys && boundKeys.length > 0) {\n      try {\n        const output = JSON.parse(result.text() || '{}');\n        UIAssertions.assertDataBinding(html, output, boundKeys);\n      } catch {\n        // If we can't parse output, skip data binding check\n      }\n    }\n\n    return html;\n  },\n};\n"]}

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

@@ -0,0 +1,39 @@
+/**
+ * @file ui-matchers.ts
+ * @description UI-specific Jest matchers for validating tool UI responses
+ *
+ * The metadata keys used in these matchers align with the UIMetadata interface
+ * from @frontmcp/ui/adapters. Key fields include:
+ * - `ui/html`: Inline rendered HTML (universal)
+ * - `ui/mimeType`: MIME type for the HTML content
+ * - `openai/outputTemplate`: Resource URI for widget template (OpenAI)
+ * - `openai/widgetAccessible`: Whether widget can invoke tools (OpenAI)
+ *
+ * @see {@link https://docs.agentfront.dev/docs/servers/tools#tool-ui | Tool UI Documentation}
+ *
+ * @example
+ * ```typescript
+ * import { test, expect } from '@frontmcp/testing';
+ *
+ * test('tool has rendered UI', async ({ mcp }) => {
+ *   const result = await mcp.tools.call('my-tool', {});
+ *   expect(result).toHaveRenderedHtml();
+ *   expect(result).toBeXssSafe();
+ *   expect(result).toContainBoundValue('expected-value');
+ * });
+ * ```
+ */
+import type { MatcherFunction } from 'expect';
+/**
+ * All UI matchers as an object for expect.extend()
+ */
+export declare const uiMatchers: {
+    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<[]>;
+};

package/src/ui/ui-matchers.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * @file ui-matchers.ts
+ * @description UI-specific Jest matchers for validating tool UI responses
+ *
+ * The metadata keys used in these matchers align with the UIMetadata interface
+ * from @frontmcp/ui/adapters. Key fields include:
+ * - `ui/html`: Inline rendered HTML (universal)
+ * - `ui/mimeType`: MIME type for the HTML content
+ * - `openai/outputTemplate`: Resource URI for widget template (OpenAI)
+ * - `openai/widgetAccessible`: Whether widget can invoke tools (OpenAI)
+ *
+ * @see {@link https://docs.agentfront.dev/docs/servers/tools#tool-ui | Tool UI Documentation}
+ *
+ * @example
+ * ```typescript
+ * import { test, expect } from '@frontmcp/testing';
+ *
+ * test('tool has rendered UI', async ({ mcp }) => {
+ *   const result = await mcp.tools.call('my-tool', {});
+ *   expect(result).toHaveRenderedHtml();
+ *   expect(result).toBeXssSafe();
+ *   expect(result).toContainBoundValue('expected-value');
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uiMatchers = void 0;
+// Type-only reference: Metadata keys used below align with UIMetadata from @frontmcp/ui/adapters
+// This is an optional peer dependency, so we don't import it directly
+// ═══════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Escape special regex metacharacters in a string.
+ * This prevents user-provided tag/class names from being interpreted as regex patterns.
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Extract UI HTML from a tool result wrapper or raw result.
+ */
+function extractUiHtml(received) {
+    if (typeof received === 'string') {
+        return received;
+    }
+    // ToolResultWrapper has raw._meta
+    const wrapper = received;
+    const meta = wrapper?.raw?._meta || wrapper?._meta;
+    if (meta && typeof meta === 'object') {
+        const uiHtml = meta['ui/html'];
+        if (typeof uiHtml === 'string') {
+            return uiHtml;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract _meta object from a tool result wrapper.
+ */
+function extractMeta(received) {
+    const wrapper = received;
+    const meta = wrapper?.raw?._meta || wrapper?._meta;
+    if (meta && typeof meta === 'object') {
+        return meta;
+    }
+    return undefined;
+}
+// ═══════════════════════════════════════════════════════════════════
+// UI MATCHERS
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Check if tool result has rendered HTML in _meta['ui/html'].
+ * Fails if the HTML is the mdx-fallback (escaped raw content).
+ */
+const toHaveRenderedHtml = function (received) {
+    const html = extractUiHtml(received);
+    const hasHtml = html !== undefined && html.length > 0;
+    const isFallback = hasHtml && html.includes('mdx-fallback');
+    const pass = hasHtml && !isFallback;
+    return {
+        pass,
+        message: () => {
+            if (isFallback) {
+                return 'Expected rendered HTML but got mdx-fallback (raw escaped content). MDX rendering may have failed.';
+            }
+            if (!hasHtml) {
+                return 'Expected _meta to have ui/html property with rendered HTML';
+            }
+            return 'Expected result not to have rendered HTML';
+        },
+    };
+};
+/**
+ * Check if HTML contains a specific HTML element tag.
+ * @param tag - The HTML tag name to look for (e.g., 'div', 'h1', 'span')
+ */
+const toContainHtmlElement = function (received, tag) {
+    const html = extractUiHtml(received);
+    if (!html) {
+        return {
+            pass: false,
+            message: () => `Expected to find <${tag}> element, but no HTML content found`,
+        };
+    }
+    // Match opening tags: <tag> or <tag attributes>
+    // Escape regex metacharacters to prevent user input from breaking the regex
+    const regex = new RegExp(`<${escapeRegex(tag)}[\\s>]`, 'i');
+    const pass = regex.test(html);
+    return {
+        pass,
+        message: () => pass ? `Expected HTML not to contain <${tag}> element` : `Expected HTML to contain <${tag}> element`,
+    };
+};
+/**
+ * Check if a bound value from tool output appears in the rendered HTML.
+ * @param value - The value to look for (string or number)
+ */
+const toContainBoundValue = function (received, value) {
+    const html = extractUiHtml(received);
+    if (!html) {
+        return {
+            pass: false,
+            message: () => `Expected HTML to contain bound value "${value}", but no HTML content found`,
+        };
+    }
+    const stringValue = String(value);
+    const pass = html.includes(stringValue);
+    return {
+        pass,
+        message: () => pass
+            ? `Expected HTML not to contain bound value "${stringValue}"`
+            : `Expected HTML to contain bound value "${stringValue}"`,
+    };
+};
+/**
+ * Check if HTML is XSS-safe (no script tags, event handlers, or javascript: URIs).
+ */
+const toBeXssSafe = function (received) {
+    const html = extractUiHtml(received);
+    if (!html) {
+        // No HTML means nothing to exploit
+        return {
+            pass: true,
+            message: () => 'Expected HTML to be XSS unsafe (no HTML found)',
+        };
+    }
+    const hasScript = /<script[\s>]/i.test(html);
+    const hasOnHandler = /\son\w+\s*=/i.test(html);
+    const hasJavascriptUri = /javascript:/i.test(html);
+    const issues = [];
+    if (hasScript)
+        issues.push('<script> tag');
+    if (hasOnHandler)
+        issues.push('inline event handler (onclick, etc.)');
+    if (hasJavascriptUri)
+        issues.push('javascript: URI');
+    const pass = !hasScript && !hasOnHandler && !hasJavascriptUri;
+    return {
+        pass,
+        message: () => pass ? 'Expected HTML not to be XSS safe' : `Expected HTML to be XSS safe, but found: ${issues.join(', ')}`,
+    };
+};
+/**
+ * Check if tool result has widget metadata.
+ * Checks for ui/html (universal), openai/outputTemplate, or ui/mimeType.
+ */
+const toHaveWidgetMetadata = function (received) {
+    const meta = extractMeta(received);
+    if (!meta) {
+        return {
+            pass: false,
+            message: () => 'Expected _meta to have widget metadata, but no _meta found',
+        };
+    }
+    // Check for any widget-related metadata fields
+    const hasUiHtml = Boolean(meta['ui/html']);
+    const hasOutputTemplate = Boolean(meta['openai/outputTemplate']);
+    const hasMimeType = Boolean(meta['ui/mimeType']);
+    const pass = hasUiHtml || hasOutputTemplate || hasMimeType;
+    return {
+        pass,
+        message: () => pass
+            ? 'Expected result not to have widget metadata'
+            : 'Expected _meta to have widget metadata (ui/html, openai/outputTemplate, or ui/mimeType)',
+    };
+};
+/**
+ * Check if HTML has CSS classes (for styling validation).
+ * @param className - The CSS class name to look for
+ */
+const toHaveCssClass = function (received, className) {
+    const html = extractUiHtml(received);
+    if (!html) {
+        return {
+            pass: false,
+            message: () => `Expected HTML to have CSS class "${className}", but no HTML content found`,
+        };
+    }
+    // Match class="... className ..." or className="... className ..."
+    // Escape regex metacharacters to prevent user input from breaking the regex
+    const classRegex = new RegExp(`class(?:Name)?\\s*=\\s*["'][^"']*\\b${escapeRegex(className)}\\b[^"']*["']`, 'i');
+    const pass = classRegex.test(html);
+    return {
+        pass,
+        message: () => pass ? `Expected HTML not to have CSS class "${className}"` : `Expected HTML to have CSS class "${className}"`,
+    };
+};
+/**
+ * Check that HTML does NOT contain specific content (useful for fallback checks).
+ * @param content - The content that should NOT be in the HTML
+ */
+const toNotContainRawContent = function (received, content) {
+    const html = extractUiHtml(received);
+    if (!html) {
+        return {
+            pass: true,
+            message: () => `Expected HTML to contain raw content "${content}", but no HTML found`,
+        };
+    }
+    const pass = !html.includes(content);
+    return {
+        pass,
+        message: () => pass
+            ? `Expected HTML to contain raw content "${content}"`
+            : `Expected HTML not to contain raw content "${content}" (may indicate rendering failure)`,
+    };
+};
+/**
+ * Check if HTML has proper structure (not just escaped text).
+ */
+const toHaveProperHtmlStructure = function (received) {
+    const html = extractUiHtml(received);
+    if (!html) {
+        return {
+            pass: false,
+            message: () => 'Expected proper HTML structure, but no HTML content found',
+        };
+    }
+    // Check for escaped HTML entities that suggest content wasn't rendered
+    const hasEscapedTags = html.includes('&lt;') && html.includes('&gt;');
+    // Check that there's at least one HTML tag
+    const hasHtmlTags = /<[a-z]/i.test(html);
+    const pass = hasHtmlTags && !hasEscapedTags;
+    return {
+        pass,
+        message: () => {
+            if (hasEscapedTags) {
+                return 'Expected proper HTML structure, but found escaped HTML entities - content may not have been rendered';
+            }
+            if (!hasHtmlTags) {
+                return 'Expected proper HTML structure, but found no HTML tags';
+            }
+            return 'Expected result not to have proper HTML structure';
+        },
+    };
+};
+// ═══════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * All UI matchers as an object for expect.extend()
+ */
+exports.uiMatchers = {
+    toHaveRenderedHtml,
+    toContainHtmlElement,
+    toContainBoundValue,
+    toBeXssSafe,
+    toHaveWidgetMetadata,
+    toHaveCssClass,
+    toNotContainRawContent,
+    toHaveProperHtmlStructure,
+};
+//# sourceMappingURL=ui-matchers.js.map