sunpeak 0.19.1 → 0.19.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sunpeak",
-  "version": "0.19.1",
+  "version": "0.19.2",
   "description": "Inspector, testing framework, and app framework for MCP Apps.",
   "type": "module",
   "main": "./dist/index.cjs",

package/template/README.md

@@ -17,9 +17,12 @@ That's it! Edit the resource files in [./src/resources/](./src/resources/) to bu
 **Testing:**
 
 ```bash
-sunpeak test              # Run e2e tests against the inspector.
-sunpeak test --unit       # Run unit tests with Vitest.
-sunpeak test --live       # Run live tests against real ChatGPT.
+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:**

package/template/dist/albums/albums.json

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

package/template/dist/carousel/carousel.json

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

package/template/dist/map/map.json

@@ -18,5 +18,5 @@
     }
   },
   "name": "map",
-  "uri": "ui://map-mnnh0y9o"
+  "uri": "ui://map-mnnqsot1"
 }

package/template/dist/review/review.json

@@ -12,5 +12,5 @@
     }
   },
   "name": "review",
-  "uri": "ui://review-mnnh0y9o"
+  "uri": "ui://review-mnnqsot1"
 }

package/template/package.json

@@ -7,9 +7,11 @@
     "dev": "sunpeak dev",
     "build": "sunpeak build",
     "start": "sunpeak start",
-    "test": "vitest run",
-    "test:e2e": "playwright test",
-    "test:live": "playwright test --config tests/live/playwright.config.ts"
+    "test": "sunpeak test",
+    "test:unit": "sunpeak test --unit",
+    "test:e2e": "sunpeak test --e2e",
+    "test:visual": "sunpeak test --visual",
+    "test:live": "sunpeak test --live"
   },
   "dependencies": {
     "clsx": "^2.1.1",

package/template/test-results/.last-run.json

@@ -0,0 +1,4 @@
+{
+  "status": "passed",
+  "failedTests": []
+}

package/template/tests/e2e/visual.spec.ts

@@ -0,0 +1,36 @@
+import { test, expect } from 'sunpeak/test';
+
+// Visual regression tests. Screenshot comparisons only run with `sunpeak test --visual`.
+// Update baselines with `sunpeak test --visual --update`.
+
+test('albums renders correctly in light mode', async ({ mcp }) => {
+  const result = await mcp.callTool('show-albums', {}, { theme: 'light' });
+  const app = result.app();
+  await expect(app.locator('button:has-text("Summer Slice")')).toBeVisible();
+
+  await mcp.screenshot('albums-light');
+});
+
+test('albums renders correctly in dark mode', async ({ mcp }) => {
+  const result = await mcp.callTool('show-albums', {}, { theme: 'dark' });
+  const app = result.app();
+  await expect(app.locator('button:has-text("Summer Slice")')).toBeVisible();
+
+  await mcp.screenshot('albums-dark');
+});
+
+test('albums renders correctly in fullscreen', async ({ mcp }) => {
+  const result = await mcp.callTool('show-albums', {}, { displayMode: 'fullscreen' });
+  const app = result.app();
+  await expect(app.locator('button:has-text("Summer Slice")')).toBeVisible();
+
+  await mcp.screenshot('albums-fullscreen');
+});
+
+test('full page renders correctly', async ({ mcp }) => {
+  const result = await mcp.callTool('show-albums', {}, { theme: 'light' });
+  const app = result.app();
+  await expect(app.locator('button:has-text("Summer Slice")')).toBeVisible();
+
+  await mcp.screenshot('albums-page-light', { target: 'page', maxDiffPixelRatio: 0.02 });
+});