sunpeak 0.19.1 → 0.19.4

package/README.md

@@ -107,10 +107,13 @@ sunpeak new
 | Command                               | Description                                 |
 | ------------------------------------- | ------------------------------------------- |
 | `sunpeak inspect --server <url\|cmd>` | Inspect any MCP server in the inspector     |
-| `sunpeak test`                        | Run e2e tests against the inspector         |
-| `sunpeak test init`                   | Scaffold test infrastructure into a project |
-| `sunpeak test --unit`                 | Run unit tests (Vitest)                     |
+| `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 hosts           |
+| `sunpeak test init`                   | Scaffold test infrastructure into a project |
 
 **App framework** (for sunpeak projects):
 

package/bin/commands/new.mjs

@@ -176,7 +176,9 @@ export async function init(projectName, resourcesArg, deps = defaultDeps) {
       }
 
       // Skip framework-internal test files (dev overlay tests are for sunpeak development, not user projects)
-      if ((src.includes('/tests/e2e/') || src.includes('/tests/live/')) && name.startsWith('dev-')) {
+      // Skip visual.spec.ts — it references specific resources and serves as a template/example.
+      // Users should write their own visual tests for their selected resources.
+      if ((src.includes('/tests/e2e/') || src.includes('/tests/live/')) && (name.startsWith('dev-') || name === 'visual.spec.ts')) {
         return false;
       }
 

package/bin/commands/test.mjs

@@ -5,11 +5,18 @@ import { join } from 'path';
 /**
  * sunpeak test — Run MCP server tests.
  *
- * sunpeak test              Run e2e tests (Playwright)
- * sunpeak test init         Scaffold test infrastructure
- * sunpeak test --unit       Run unit tests (vitest)
- * sunpeak test --live       Run live tests against real hosts
- * sunpeak test [pattern]    Pass through to Playwright
+ * No flags:                    Run unit + e2e tests
+ * sunpeak test init            Scaffold test infrastructure
+ * sunpeak test --unit          Run unit tests (vitest)
+ * sunpeak test --e2e           Run e2e tests (Playwright)
+ * sunpeak test --live          Run live tests against real hosts
+ * sunpeak test --visual        Run e2e tests with visual regression comparison
+ * sunpeak test --visual --update  Update visual regression baselines
+ * sunpeak test [pattern]       Pass through to the relevant runner
+ *
+ * Flags are additive: --unit --e2e --live runs all three.
+ * --visual implies --e2e and enables screenshot comparison.
+ * --update implies --visual.
  */
 export async function runTest(args) {
   // Handle `sunpeak test init` subcommand
@@ -20,58 +27,112 @@ export async function runTest(args) {
   }
 
   const isUnit = args.includes('--unit');
+  const isE2e = args.includes('--e2e');
   const isLive = args.includes('--live');
-  const filteredArgs = args.filter((a) => a !== '--unit' && a !== '--live');
+  let isVisual = args.includes('--visual');
+  const isUpdate = args.includes('--update');
+  const filteredArgs = args.filter(
+    (a) => !['--unit', '--e2e', '--live', '--visual', '--update'].includes(a)
+  );
 
-  if (isUnit) {
-    // Run vitest
-    const child = spawn('pnpm', ['exec', 'vitest', 'run', ...filteredArgs], {
-      stdio: 'inherit',
-      env: { ...process.env },
+  // --update implies --visual (no point updating without enabling visual)
+  if (isUpdate) isVisual = true;
+
+  const hasAnyScope = isUnit || isE2e || isLive || isVisual;
+
+  // When extra args are present (file patterns, etc.) and no scope flags given,
+  // default to e2e only — passing Playwright file patterns to vitest would fail.
+  const hasExtraArgs = filteredArgs.length > 0;
+
+  // Determine which suites to run.
+  // No scope flags → unit + e2e (unless extra args narrow to e2e).
+  // --visual implies e2e.
+  const runUnit = hasAnyScope ? isUnit : !hasExtraArgs;
+  const runE2e = hasAnyScope ? (isE2e || isVisual) : true;
+  const runLive = isLive;
+
+  const results = [];
+
+  if (runUnit) {
+    const code = await runChild('pnpm', ['exec', 'vitest', 'run', ...filteredArgs]);
+    results.push({ suite: 'unit', code });
+  }
+
+  if (runE2e) {
+    const code = await runPlaywright(filteredArgs, {
+      configCandidates: [
+        'playwright.config.ts',
+        'playwright.config.js',
+        'sunpeak.config.ts',
+        'sunpeak.config.js',
+      ],
+      visual: isVisual,
+      updateSnapshots: isVisual && isUpdate,
     });
-    child.on('exit', (code) => process.exit(code ?? 1));
-    return;
+    results.push({ suite: 'e2e', code });
   }
 
-  // Find the appropriate Playwright config
-  let configArgs = [];
-  if (isLive) {
-    const liveConfig = findConfig([
-      'tests/live/playwright.config.ts',
-      'tests/live/playwright.config.js',
-    ]);
-    if (liveConfig) {
-      configArgs = ['--config', liveConfig];
-    } else {
-      console.error('No live test config found at tests/live/playwright.config.ts');
-      process.exit(1);
-    }
-  } else {
-    // Default: e2e tests — look for config in standard locations
-    const e2eConfig = findConfig([
-      'playwright.config.ts',
-      'playwright.config.js',
-      'sunpeak.config.ts',
-      'sunpeak.config.js',
-    ]);
-    if (e2eConfig) {
-      configArgs = ['--config', e2eConfig];
-    }
-    // If no config found, let Playwright use its defaults
+  if (runLive) {
+    const code = await runPlaywright(filteredArgs, {
+      configCandidates: [
+        'tests/live/playwright.config.ts',
+        'tests/live/playwright.config.js',
+      ],
+      configRequired: true,
+      configErrorMessage: 'No live test config found at tests/live/playwright.config.ts',
+    });
+    results.push({ suite: 'live', code });
+  }
+
+  // Exit with the first non-zero code, or 0 if all passed
+  const failed = results.find((r) => r.code !== 0);
+  process.exit(failed ? failed.code : 0);
+}
+
+/**
+ * Spawn a child process and return its exit code.
+ */
+function runChild(command, args, env) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      stdio: 'inherit',
+      env: { ...process.env, ...env },
+    });
+    child.on('error', () => resolve(1));
+    child.on('exit', (code) => resolve(code ?? 1));
+  });
+}
+
+/**
+ * Run Playwright and return the exit code.
+ */
+function runPlaywright(args, options = {}) {
+  const {
+    configCandidates = [],
+    configRequired = false,
+    configErrorMessage,
+    visual = false,
+    updateSnapshots = false,
+  } = options;
+
+  const config = findConfig(configCandidates);
+
+  if (!config && configRequired) {
+    console.error(configErrorMessage);
+    return Promise.resolve(1);
   }
 
-  const child = spawn(
+  const configArgs = config ? ['--config', config] : [];
+  const extraArgs = updateSnapshots ? ['--update-snapshots'] : [];
+
+  return runChild(
     'pnpm',
-    ['exec', 'playwright', 'test', ...configArgs, ...filteredArgs],
+    ['exec', 'playwright', 'test', ...configArgs, ...extraArgs, ...args],
     {
-      stdio: 'inherit',
-      env: {
-        ...process.env,
-        SUNPEAK_DEV_OVERLAY: process.env.SUNPEAK_DEV_OVERLAY ?? 'false',
-      },
+      SUNPEAK_DEV_OVERLAY: process.env.SUNPEAK_DEV_OVERLAY ?? 'false',
+      ...(visual ? { SUNPEAK_VISUAL: 'true' } : {}),
     }
   );
-  child.on('exit', (code) => process.exit(code ?? 1));
 }
 
 function findConfig(candidates) {

package/bin/lib/inspect/inspect-config.d.mts

@@ -1,3 +1,5 @@
+import type { VisualConfig } from '../test/test-config.d.mts';
+
 export interface InspectConfigOptions {
   /** MCP server URL or stdio command string (required) */
   server: string;
@@ -11,6 +13,8 @@ export interface InspectConfigOptions {
   name?: string;
   /** Additional Playwright `use` options */
   use?: Record<string, unknown>;
+  /** Visual regression testing configuration */
+  visual?: VisualConfig;
 }
 
 /**

package/bin/lib/inspect/inspect-config.mjs

@@ -36,6 +36,7 @@ export function defineInspectConfig(options) {
     hosts = ['chatgpt', 'claude'],
     name,
     use: userUse,
+    visual,
   } = options;
 
   if (!server) {
@@ -60,6 +61,7 @@ export function defineInspectConfig(options) {
     testDir,
     port,
     use: userUse,
+    visual,
     webServer: {
       command,
       healthUrl: `http://localhost:${port}/health`,

package/bin/lib/test/base-config.mjs

@@ -17,7 +17,10 @@ import { getPortSync } from '../get-port.mjs';
  * @param {string} [options.globalSetup] - Global setup file path
  * @returns {import('@playwright/test').PlaywrightTestConfig}
  */
-export function createBaseConfig({ hosts, testDir, webServer, port, use, globalSetup }) {
+export function createBaseConfig({ hosts, testDir, webServer, port, use, globalSetup, visual }) {
+  // Separate snapshot path from other visual options passed to expect.toHaveScreenshot
+  const { snapshotPathTemplate, ...toHaveScreenshotDefaults } = visual ?? {};
+
   return {
     ...(globalSetup ? { globalSetup } : {}),
     testDir,
@@ -27,6 +30,18 @@ export function createBaseConfig({ hosts, testDir, webServer, port, use, globalS
     // Limit workers to avoid overwhelming the double-iframe sandbox proxy.
     workers: process.env.CI ? 1 : 2,
     reporter: 'list',
+    // Only override snapshot path when visual config is provided, to avoid
+    // changing Playwright's default for projects that don't use visual testing.
+    ...(visual
+      ? {
+          snapshotPathTemplate:
+            snapshotPathTemplate ??
+            '{testDir}/__screenshots__/{projectName}/{testFilePath}/{arg}{ext}',
+        }
+      : {}),
+    ...(Object.keys(toHaveScreenshotDefaults).length > 0
+      ? { expect: { toHaveScreenshot: toHaveScreenshotDefaults } }
+      : {}),
     use: {
       baseURL: `http://localhost:${port}`,
       trace: 'on-first-retry',

package/bin/lib/test/test-config.d.mts

@@ -14,6 +14,26 @@ export interface ServerConfig {
   env?: Record<string, string>;
 }
 
+/**
+ * Visual regression testing configuration.
+ *
+ * All fields except `snapshotPathTemplate` are forwarded to Playwright's
+ * `expect.toHaveScreenshot` config. See Playwright docs for the full set
+ * of options (threshold, maxDiffPixelRatio, maxDiffPixels, animations, etc.).
+ */
+export interface VisualConfig {
+  /** Snapshot directory path template. Default: '{testDir}/__screenshots__/{projectName}/{testFilePath}/{arg}{ext}'. */
+  snapshotPathTemplate?: string;
+  /** Pixel comparison threshold (0-1). */
+  threshold?: number;
+  /** Maximum allowed ratio of differing pixels (0-1). */
+  maxDiffPixelRatio?: number;
+  /** Absolute count of allowed different pixels. */
+  maxDiffPixels?: number;
+  /** Any other Playwright toHaveScreenshot options applied as project-wide defaults. */
+  [key: string]: unknown;
+}
+
 /**
  * Configuration options for sunpeak test config.
  */
@@ -33,6 +53,8 @@ export interface TestConfigOptions {
   globalSetup?: string;
   /** Additional Playwright `use` options. */
   use?: Record<string, unknown>;
+  /** Visual regression testing configuration. */
+  visual?: VisualConfig;
 }
 
 /**

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

@@ -41,6 +41,7 @@ export function defineConfig(options = {}) {
     simulationsDir,
     globalSetup,
     use: userUse,
+    visual,
   } = options;
 
   const { port, sandboxPort } = resolvePorts();
@@ -67,6 +68,7 @@ export function defineConfig(options = {}) {
     port,
     use: userUse,
     globalSetup,
+    visual,
     webServer: {
       command,
       healthUrl: `http://localhost:${port}/health`,

package/bin/lib/test/test-fixtures.d.mts

@@ -1,4 +1,11 @@
-import type { Page, FrameLocator, TestType, Expect } from '@playwright/test';
+import type {
+  Page,
+  FrameLocator,
+  Locator,
+  TestType,
+  Expect,
+  PageAssertionsToHaveScreenshotOptions,
+} from '@playwright/test';
 
 /**
  * Result from calling an MCP tool via the inspector.
@@ -31,6 +38,22 @@ export interface CallToolOptions {
   [key: string]: unknown;
 }
 
+/**
+ * Options for screenshot().
+ *
+ * Extends Playwright's toHaveScreenshot() options with sunpeak-specific
+ * `target` and `element` fields. All standard Playwright options (threshold,
+ * maxDiffPixelRatio, maxDiffPixels, mask, maskColor, animations, caret,
+ * fullPage, clip, scale, stylePath, omitBackground, timeout, etc.)
+ * are passed through directly.
+ */
+export interface ScreenshotOptions extends PageAssertionsToHaveScreenshotOptions {
+  /** What to screenshot: 'app' (inner iframe content) or 'page' (full inspector). Default: 'app'. */
+  target?: 'app' | 'page';
+  /** Specific locator to screenshot instead of the default target. */
+  element?: Locator;
+}
+
 /**
  * MCP test fixture for testing MCP servers via the inspector.
  */
@@ -66,6 +89,16 @@ export interface McpFixture {
 
   /** Change the display mode via the sidebar buttons. */
   setDisplayMode(mode: 'inline' | 'pip' | 'fullscreen'): Promise<void>;
+
+  /**
+   * Take a screenshot and compare against a baseline.
+   * Only performs the comparison when visual testing is enabled
+   * (`sunpeak test --visual`). Silently skips otherwise.
+   *
+   * @param name - Snapshot name (auto-generated from test title if omitted)
+   * @param options - Screenshot and comparison options
+   */
+  screenshot(name?: string, options?: ScreenshotOptions): Promise<void>;
 }
 
 /**

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

@@ -180,6 +180,49 @@ const test = base.extend({
         // 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);

package/dist/chatgpt/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../chunk-9hOWP6kD.cjs");
-const require_inspector = require("../inspector-8nPV2A-z.cjs");
+const require_inspector = require("../inspector-Cvq3yjNL.cjs");
 const require_inspector_url = require("../inspector-url-C3LTKgXt.cjs");
 const require_discovery = require("../discovery-Clu4uHp1.cjs");
 //#region src/chatgpt/index.ts

package/dist/chatgpt/index.js

@@ -1,5 +1,5 @@
 import { r as __exportAll } from "../chunk-D6g4UhsZ.js";
-import { _ as McpAppHost, d as ThemeProvider, f as useThemeContext, g as extractResourceCSP, h as IframeResource, n as resolveServerToolResult, t as Inspector, v as SCREEN_WIDTHS } from "../inspector-Cdo5BK2D.js";
+import { _ as McpAppHost, d as ThemeProvider, f as useThemeContext, g as extractResourceCSP, h as IframeResource, n as resolveServerToolResult, t as Inspector, v as SCREEN_WIDTHS } from "../inspector-Bp9jrHIu.js";
 import { t as createInspectorUrl } from "../inspector-url-CyQcuBI9.js";
 import { c as toPascalCase, i as findResourceKey, n as extractSimulationKey, r as findResourceDirs, s as getComponentName, t as extractResourceKey } from "../discovery-Cgoegt62.js";
 //#region src/chatgpt/index.ts

package/dist/claude/index.cjs

@@ -1,4 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../chunk-9hOWP6kD.cjs");
-const require_inspector = require("../inspector-8nPV2A-z.cjs");
+const require_inspector = require("../inspector-Cvq3yjNL.cjs");
 exports.Inspector = require_inspector.Inspector;

package/dist/claude/index.js

@@ -1,2 +1,2 @@
-import { t as Inspector } from "../inspector-Cdo5BK2D.js";
+import { t as Inspector } from "../inspector-Bp9jrHIu.js";
 export { Inspector };

package/dist/host/chatgpt/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-9hOWP6kD.cjs");
-const require_use_app = require("../../use-app-CzcYw1Kz.cjs");
+const require_use_app = require("../../use-app-DHYiev3D.cjs");
 let react = require("react");
 //#region src/host/chatgpt/openai-types.ts
 /**

package/dist/host/chatgpt/index.js

@@ -1,4 +1,4 @@
-import { t as useApp } from "../../use-app-CfP9VypY.js";
+import { t as useApp } from "../../use-app-Ck5kR1Sf.js";
 import { useCallback } from "react";
 //#region src/host/chatgpt/openai-types.ts
 /**