sunpeak 0.18.14 → 0.19.2

package/bin/lib/test/test-fixtures.mjs

@@ -0,0 +1,232 @@
+/**
+ * MCP-first Playwright fixtures for testing MCP servers.
+ *
+ * Provides an `mcp` fixture that abstracts the inspector, double-iframe
+ * traversal, URL construction, and host selection. Tests read like MCP
+ * operations, not browser automation.
+ *
+ * Usage:
+ *   import { test, expect } from 'sunpeak/test';
+ *
+ *   test('weather tool', async ({ mcp }) => {
+ *     const result = await mcp.callTool('get-weather', { city: 'SF' });
+ *     expect(result).not.toBeError();
+ *     expect(result).toHaveTextContent('temperature');
+ *
+ *     const app = result.app();
+ *     await expect(app.getByText('San Francisco')).toBeVisible();
+ *   });
+ */
+import { resolvePlaywrightESM } from '../live/utils.mjs';
+import { registerMatchers } from './matchers.mjs';
+
+const projectRoot = process.env.SUNPEAK_PROJECT_ROOT || process.cwd();
+const { test: base, expect } = await resolvePlaywrightESM(projectRoot);
+
+// Register MCP-native matchers
+registerMatchers(expect);
+
+/**
+ * Build an inspector URL path with query parameters.
+ * Inlined to avoid importing from dist (which pulls in React).
+ */
+function buildInspectorUrl(params) {
+  const sp = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null) {
+      sp.set(key, String(value));
+    }
+  }
+  // Always disable dev overlay in tests
+  sp.set('devOverlay', 'false');
+  const qs = sp.toString();
+  return qs ? `/?${qs}` : '/';
+}
+
+/**
+ * Resolve the host ID from the Playwright project name.
+ */
+function resolveHostId(projectName) {
+  if (!projectName) return 'chatgpt';
+  if (projectName.startsWith('chatgpt')) return 'chatgpt';
+  if (projectName.startsWith('claude')) return 'claude';
+  return projectName;
+}
+
+/**
+ * Create a ToolResult wrapper around the inspector's rendered state.
+ */
+function createToolResult(page, resultData) {
+  return {
+    content: resultData?.content || [],
+    structuredContent: resultData?.structuredContent,
+    isError: resultData?.isError || false,
+
+    /**
+     * Get a FrameLocator for the rendered resource UI.
+     * Handles the double-iframe traversal (outer sandbox proxy + inner app).
+     * Returns the locator regardless — Playwright will throw with a clear
+     * error if no iframe exists when you interact with it.
+     */
+    app() {
+      return page.frameLocator('iframe').frameLocator('iframe');
+    },
+  };
+}
+
+const test = base.extend({
+  mcp: async ({ page }, use, testInfo) => {
+    const host = resolveHostId(testInfo.project.name);
+
+    const fixture = {
+      page,
+      host,
+
+      /**
+       * Call a tool and get the rendered result.
+       *
+       * For sunpeak projects: navigates to the matching simulation (simulation
+       * fixture data including toolInput is served by sunpeak dev).
+       * For external servers: navigates to the matching simulation created by
+       * inspectServer from discovered tools.
+       *
+       * Note: The `input` parameter is accepted for API consistency and future
+       * use but is not currently passed to the inspector. Simulation fixture
+       * data provides the tool input for rendering.
+       *
+       * @param {string} name - Tool/simulation name (e.g., 'show-albums')
+       * @param {Record<string, unknown>} [_input] - Reserved for future use
+       * @param {Object} [options] - Display options
+       * @returns {Promise<ToolResult>}
+       */
+      async callTool(name, _input, options = {}) {
+        const { theme, displayMode, ...rest } = options;
+
+        const params = {
+          simulation: name,
+          host,
+          ...(theme && { theme }),
+          ...(displayMode && { displayMode }),
+          ...rest,
+        };
+
+        await page.goto(buildInspectorUrl(params));
+
+        // Wait for the resource iframe to have content
+        try {
+          const frame = page.frameLocator('iframe').frameLocator('iframe');
+          await frame.locator('body').waitFor({ state: 'attached', timeout: 15_000 });
+        } catch {
+          // Tool may not have a resource (no UI)
+        }
+
+        return createToolResult(page, {
+          content: [],
+          structuredContent: undefined,
+          isError: false,
+        });
+      },
+
+      /**
+       * Navigate to a tool with no mock data ("Press Run" state).
+       * Use for testing the empty/loading state before a tool is executed.
+       */
+      async openTool(name, options = {}) {
+        const { theme, ...rest } = options;
+        const params = {
+          tool: name,
+          host,
+          ...(theme && { theme }),
+          ...rest,
+        };
+        await page.goto(buildInspectorUrl(params));
+        await page.locator('#root').waitFor({ state: 'attached' });
+      },
+
+      /**
+       * Click the Run button and wait for the resource to render.
+       * Use after openTool() in Prod Tools mode.
+       */
+      async runTool() {
+        await page.locator('button:has-text("Run")').click();
+        await page.locator('iframe').waitFor({ state: 'attached', timeout: 30_000 });
+        return createToolResult(page, {
+          content: [],
+          structuredContent: undefined,
+          isError: false,
+        });
+      },
+
+      /**
+       * Change the theme via the sidebar toggle.
+       */
+      async setTheme(theme) {
+        const label = theme === 'light' ? 'Light' : 'Dark';
+        const button = page.locator(`button:has-text("${label}")`);
+        if (await button.isVisible().catch(() => false)) {
+          await button.click();
+          // Wait for theme to propagate to the iframe
+          await page.waitForTimeout(300);
+        }
+      },
+
+      /**
+       * Change the display mode via the sidebar buttons.
+       */
+      async setDisplayMode(mode) {
+        const labels = { inline: 'Inline', pip: 'PiP', fullscreen: 'Full' };
+        const label = labels[mode] || mode;
+        await page.locator(`button:has-text("${label}")`).click();
+        // Wait for display mode transition
+        await page.waitForTimeout(500);
+      },
+
+      /**
+       * Take a screenshot and compare against a baseline.
+       * Only performs the comparison when visual testing is enabled
+       * (`sunpeak test --visual`). Silently skips otherwise, so tests
+       * that include screenshot() calls still pass during normal runs.
+       *
+       * Accepts all Playwright toHaveScreenshot() options (threshold,
+       * maxDiffPixelRatio, maxDiffPixels, mask, animations, caret,
+       * fullPage, clip, scale, stylePath, etc.) and passes them through.
+       *
+       * @param {string} [name] - Snapshot name (auto-generated from test title if omitted)
+       * @param {Object} [options] - Screenshot and comparison options
+       * @param {'app' | 'page'} [options.target='app'] - What to screenshot
+       * @param {import('@playwright/test').Locator} [options.element] - Specific locator to screenshot
+       */
+      async screenshot(name, options = {}) {
+        if (process.env.SUNPEAK_VISUAL !== 'true') return;
+
+        // Support screenshot(options) without a name
+        if (typeof name === 'object' && name !== null) {
+          options = name;
+          name = undefined;
+        }
+
+        const { target = 'app', element, ...playwrightOptions } = options;
+
+        let locator;
+        if (element) {
+          locator = element;
+        } else if (target === 'page') {
+          locator = page.locator('#root');
+        } else {
+          locator = page.frameLocator('iframe').frameLocator('iframe').locator('body');
+        }
+
+        const fullName = name && !name.endsWith('.png') ? `${name}.png` : name;
+        const args = fullName
+          ? [fullName, playwrightOptions]
+          : [playwrightOptions];
+
+        await expect(locator).toHaveScreenshot(...args);
+      },
+    };
+
+    await use(fixture);
+  },
+});
+
+export { test, expect };

package/bin/sunpeak.js

@@ -37,7 +37,7 @@ function getVersion() {
   }
 
   // Commands that don't require a package.json
-  const standaloneCommands = ['new', 'upgrade', 'inspect', 'help', undefined];
+  const standaloneCommands = ['new', 'upgrade', 'inspect', 'test', 'help', undefined];
 
   if (command && !standaloneCommands.includes(command)) {
     checkPackageJson();
@@ -79,6 +79,13 @@ function getVersion() {
       }
       break;
 
+    case 'test':
+      {
+        const { runTest } = await import(join(COMMANDS_DIR, 'test.mjs'));
+        await runTest(args);
+      }
+      break;
+
     case 'upgrade':
       {
         const { upgrade } = await import(join(COMMANDS_DIR, 'upgrade.mjs'));
@@ -100,16 +107,22 @@ function getVersion() {
 Install:
   pnpm add -g sunpeak
 
-Usage:
+Testing (works with any MCP server):
+  sunpeak inspect          Inspect any MCP server in the inspector
+    --server, -s <url|cmd> MCP server URL or stdio command (required)
+    --simulations <dir>    Simulation JSON directory
+  sunpeak test             Run e2e tests against the inspector
+    init                   Scaffold test infrastructure into a project
+    --unit                 Run unit tests (vitest)
+    --live                 Run live tests against real hosts
+
+App framework (for sunpeak projects):
   sunpeak new [name] [resources]  Create a new project
   sunpeak dev              Start dev server + inspector + MCP endpoint
     --no-begging           Suppress GitHub star message
   sunpeak build            Build resources + tools for production
   sunpeak start            Start production MCP server
     --port, -p             Server port (default: 8000, or PORT env)
-  sunpeak inspect          Inspect any MCP server in the inspector
-    --server, -s <url|cmd> MCP server URL or stdio command (required)
-    --simulations <dir>    Simulation JSON directory
   sunpeak upgrade          Upgrade sunpeak to latest version
   sunpeak --version        Show version number
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sunpeak",
-  "version": "0.18.14",
+  "version": "0.19.2",
   "description": "Inspector, testing framework, and app framework for MCP Apps.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -55,24 +55,36 @@
       }
     },
     "./test": {
+      "import": {
+        "types": "./bin/lib/test/test-fixtures.d.mts",
+        "default": "./bin/lib/test/test-fixtures.mjs"
+      }
+    },
+    "./test/config": {
+      "import": {
+        "types": "./bin/lib/test/test-config.d.mts",
+        "default": "./bin/lib/test/test-config.mjs"
+      }
+    },
+    "./test/live": {
       "import": {
         "types": "./bin/lib/live/live-fixtures.d.mts",
         "default": "./bin/lib/live/live-fixtures.mjs"
       }
     },
-    "./test/config": {
+    "./test/live/config": {
       "import": {
         "types": "./bin/lib/live/test-config.d.mts",
         "default": "./bin/lib/live/test-config.mjs"
       }
     },
-    "./test/chatgpt": {
+    "./test/live/chatgpt": {
       "import": {
         "types": "./bin/lib/live/chatgpt-fixtures.d.mts",
         "default": "./bin/lib/live/chatgpt-fixtures.mjs"
       }
     },
-    "./test/chatgpt/config": {
+    "./test/live/chatgpt/config": {
       "import": {
         "types": "./bin/lib/live/chatgpt-config.d.mts",
         "default": "./bin/lib/live/chatgpt-config.mjs"
@@ -122,7 +134,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@clack/prompts": "^1.1.0",
+    "@clack/prompts": "^1.2.0",
     "@modelcontextprotocol/ext-apps": "^1.3.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@vitejs/plugin-react": "^6.0.1",
@@ -137,16 +149,16 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@typescript-eslint/eslint-plugin": "^8.57.2",
-    "@typescript-eslint/parser": "^8.57.2",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
-    "jsdom": "^29.0.1",
+    "happy-dom": "^18.0.1",
     "prettier": "^3.8.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
@@ -155,7 +167,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vite-plugin-dts": "^4.5.4",
-    "@playwright/test": "^1.52.0",
+    "@playwright/test": "^1.59.1",
     "vitest": "^4.1.2"
   },
   "repository": {

package/template/README.md

@@ -14,17 +14,27 @@ That's it! Edit the resource files in [./src/resources/](./src/resources/) to bu
 
 ## Commands
 
+**Testing:**
+
+```bash
+sunpeak test                      # Run unit + e2e tests.
+sunpeak test --unit               # Run unit tests only (Vitest).
+sunpeak test --e2e                # Run e2e tests only (Playwright).
+sunpeak test --visual             # Run e2e tests with visual regression.
+sunpeak test --visual --update    # Update visual regression baselines.
+sunpeak test --live               # Run live tests against real ChatGPT.
+```
+
+**Development and production:**
+
 ```bash
-pnpm test              # Run tests with Vitest.
-pnpm test:e2e          # Run end-to-end tests with Playwright.
-pnpm test:live         # Run live tests against real ChatGPT.
-sunpeak dev            # Start dev server + MCP endpoint.
-sunpeak build          # Build resources and compile tools for production.
-sunpeak start          # Start the production MCP server.
-sunpeak upgrade        # Upgrade sunpeak to latest version.
+sunpeak dev               # Start dev server + MCP endpoint.
+sunpeak build             # Build resources and compile tools for production.
+sunpeak start             # Start the production MCP server.
+sunpeak upgrade           # Upgrade sunpeak to latest version.
 ```
 
-The template includes a minimal test setup with Vitest. You can add additional tooling (linting, formatting, type-checking) as needed for your project.
+E2e tests use the `mcp` fixture from `sunpeak/test` to call tools and assert against rendered UI across ChatGPT and Claude hosts. Unit tests use Vitest with happy-dom. You can add additional tooling (linting, formatting, type-checking) as needed for your project.
 
 ## Project Structure
 

package/template/dist/albums/albums.json

@@ -12,5 +12,5 @@
     }
   },
   "name": "albums",
-  "uri": "ui://albums-mnhsyu53"
+  "uri": "ui://albums-mnnqsot1"
 }

package/template/dist/carousel/carousel.json

@@ -12,5 +12,5 @@
     }
   },
   "name": "carousel",
-  "uri": "ui://carousel-mnhsyu53"
+  "uri": "ui://carousel-mnnqsot1"
 }