✨ Add configurable browser type for static-site and storybook (#197)

## Summary

- Adds `browser.type` config option supporting `chromium`, `firefox`,
and `webkit`
- Adds `--browser <type>` CLI flag for both `vizzly static-site` and
`vizzly storybook`
- Improves error messages when Playwright browsers aren't installed with
helpful CI setup instructions

## Motivation

When running in CI, users were getting a confusing Playwright error when
browsers weren't installed. Now they get a clear message with exactly
what command to run:

```
Browser "chromium" is not installed.

To fix this, run:
  npx playwright install chromium

For CI environments, add this step before running Vizzly:
  npx playwright install chromium --with-deps

You can cache the browser installation in CI for faster builds.
See: https://playwright.dev/docs/ci
```

This also gives users control over:
- Which browser to use for visual testing
- Caching browser installations in CI
- Browser version management

## Usage

**Config file:**
```js
export default {
  staticSite: {
    browser: {
      type: 'firefox', // chromium (default), firefox, or webkit
    }
  }
}
```

**CLI:**
```bash
npx vizzly static-site ./dist --browser firefox
```

## Test plan

- [x] All existing static-site tests pass (178 tests)
- [x] All existing storybook tests pass (157 tests)
- [x] Added tests for browser type validation
- [x] Added tests for CLI option parsing

Author: Robdel12

clients/static-site/src/browser.js

@@ -3,64 +3,105 @@
  * Core functions for launching and managing browsers
  */
 
-import { chromium } from 'playwright-core';
+import { chromium, firefox, webkit } from 'playwright-core';
+
+let browsers = { chromium, firefox, webkit };
 
 /**
  * Launch a Playwright browser instance
  * @param {Object} options - Browser launch options
+ * @param {'chromium' | 'firefox' | 'webkit'} [options.type='chromium'] - Browser type
  * @param {boolean} [options.headless=true] - Run in headless mode
  * @param {Array<string>} [options.args=[]] - Additional browser arguments
  * @returns {Promise<Object>} Browser instance
  */
 export async function launchBrowser(options = {}) {
-  let { headless = true, args = [] } = options;
-
-  let browser = await chromium.launch({
-    headless,
-    args: [
-      // Required for running in containers/CI
-      '--no-sandbox',
-      '--disable-setuid-sandbox',
-
-      // Reduce memory usage
-      '--disable-dev-shm-usage',
-
-      // Disable unnecessary features
-      '--disable-extensions',
-      '--disable-background-networking',
-      '--disable-background-timer-throttling',
-      '--disable-backgrounding-occluded-windows',
-      '--disable-breakpad',
-      '--disable-component-update',
-      '--disable-default-apps',
-      '--disable-hang-monitor',
-      '--disable-ipc-flooding-protection',
-      '--disable-popup-blocking',
-      '--disable-prompt-on-repost',
-      '--disable-renderer-backgrounding',
-      '--disable-sync',
-
-      // Disable features via --disable-features (modern approach)
-      '--disable-features=Translate,OptimizationHints,MediaRouter',
-
-      // Reduce resource usage
-      '--metrics-recording-only',
-      '--no-first-run',
-
-      // Screenshot consistency
-      '--hide-scrollbars',
-      '--mute-audio',
-      '--force-color-profile=srgb',
-
-      // Memory optimizations
-      '--js-flags=--max-old-space-size=512',
-
-      // User-provided args
-      ...args,
-    ],
-  });
-
-  return browser;
+  let { type = 'chromium', headless = true, args = [] } = options;
+
+  let browserType = browsers[type];
+  if (!browserType) {
+    throw new Error(
+      `Unknown browser type: ${type}. Supported browsers: chromium, firefox, webkit`
+    );
+  }
+
+  // Chromium-specific args for CI/containers and screenshot consistency
+  let launchArgs =
+    type === 'chromium'
+      ? [
+          // Required for running in containers/CI
+          '--no-sandbox',
+          '--disable-setuid-sandbox',
+
+          // Reduce memory usage
+          '--disable-dev-shm-usage',
+
+          // Disable unnecessary features
+          '--disable-extensions',
+          '--disable-background-networking',
+          '--disable-background-timer-throttling',
+          '--disable-backgrounding-occluded-windows',
+          '--disable-breakpad',
+          '--disable-component-update',
+          '--disable-default-apps',
+          '--disable-hang-monitor',
+          '--disable-ipc-flooding-protection',
+          '--disable-popup-blocking',
+          '--disable-prompt-on-repost',
+          '--disable-renderer-backgrounding',
+          '--disable-sync',
+
+          // Disable features via --disable-features (modern approach)
+          '--disable-features=Translate,OptimizationHints,MediaRouter',
+
+          // Reduce resource usage
+          '--metrics-recording-only',
+          '--no-first-run',
+
+          // Screenshot consistency
+          '--hide-scrollbars',
+          '--mute-audio',
+          '--force-color-profile=srgb',
+
+          // Memory optimizations
+          '--js-flags=--max-old-space-size=512',
+
+          // User-provided args
+          ...args,
+        ]
+      : args;
+
+  try {
+    let browser = await browserType.launch({
+      headless,
+      args: launchArgs,
+    });
+
+    return browser;
+  } catch (error) {
+    // Check if this is a missing browser error
+    if (
+      error.message.includes("Executable doesn't exist") ||
+      error.message.includes('browserType.launch')
+    ) {
+      let installCmd =
+        type === 'chromium'
+          ? 'npx playwright install chromium'
+          : `npx playwright install ${type}`;
+
+      throw new Error(
+        `Browser "${type}" is not installed.\n\n` +
+          `To fix this, run:\n` +
+          `  ${installCmd}\n\n` +
+          `For CI environments, add this step before running Vizzly:\n` +
+          `  ${installCmd} --with-deps\n\n` +
+          `You can cache the browser installation in CI for faster builds.\n` +
+          `See: https://playwright.dev/docs/ci`
+      );
+    }
+
+    throw error;
+  }
 }
 
 /**

clients/static-site/src/config-schema.js

@@ -34,6 +34,7 @@ let viewportSchema = z.object({
  * Browser configuration schema
  */
 let browserSchema = z.object({
+  type: z.enum(['chromium', 'firefox', 'webkit']).default('chromium'),
   headless: z.boolean().default(true),
   args: z.array(z.string()).default([]),
 });
@@ -90,6 +91,7 @@ export let staticSiteConfigSchema = z
       .array(viewportSchema)
       .default([{ name: 'default', width: 1920, height: 1080 }]),
     browser: browserSchema.default({
+      type: 'chromium',
       headless: true,
       args: [],
     }),
@@ -111,7 +113,7 @@ export let staticSiteConfigSchema = z
   })
   .default({
     viewports: [{ name: 'default', width: 1920, height: 1080 }],
-    browser: { headless: true, args: [] },
+    browser: { type: 'chromium', headless: true, args: [] },
     screenshot: { fullPage: false, omitBackground: false, timeout: 45_000 },
     concurrency: getDefaultConcurrency(),
     pageDiscovery: {

clients/static-site/src/config.js

@@ -15,6 +15,7 @@ export let defaultConfig = {
   buildPath: null,
   viewports: [{ name: 'default', width: 1920, height: 1080 }],
   browser: {
+    type: 'chromium',
     headless: true,
     args: [],
   },
@@ -60,6 +61,10 @@ export function parseCliOptions(options) {
     config.exclude = options.exclude;
   }
 
+  if (options.browser) {
+    config.browser = { ...config.browser, type: options.browser };
+  }
+
   if (options.headless !== undefined) {
     config.browser = { ...config.browser, headless: options.headless };
   }

clients/static-site/src/plugin.js

@@ -20,6 +20,7 @@ export default {
         { name: 'desktop', width: 1920, height: 1080 },
       ],
       browser: {
+        type: 'chromium',
         headless: true,
         args: [],
       },
@@ -63,7 +64,11 @@ export default {
       )
       .option('--include <pattern>', 'Include page pattern (glob)')
       .option('--exclude <pattern>', 'Exclude page pattern (glob)')
-      .option('--browser-args <args>', 'Additional Puppeteer browser arguments')
+      .option(
+        '--browser <type>',
+        'Browser to use: chromium, firefox, webkit (default: chromium)'
+      )
+      .option('--browser-args <args>', 'Additional browser arguments')
       .option('--headless', 'Run browser in headless mode')
       .option('--full-page', 'Capture full page screenshots')
       .option(

clients/static-site/tests/config-schema.test.js

@@ -106,6 +106,36 @@ describe('config-schema', () => {
       assert.deepStrictEqual(validated.browser.args, ['--no-sandbox']);
     });
 
+    it('validates browser type', () => {
+      let config = {
+        browser: {
+          type: 'firefox',
+        },
+      };
+
+      let validated = validateStaticSiteConfig(config);
+
+      assert.strictEqual(validated.browser.type, 'firefox');
+    });
+
+    it('defaults browser type to chromium', () => {
+      let config = {};
+
+      let validated = validateStaticSiteConfig(config);
+
+      assert.strictEqual(validated.browser.type, 'chromium');
+    });
+
+    it('rejects invalid browser type', () => {
+      let config = {
+        browser: {
+          type: 'invalid-browser',
+        },
+      };
+
+      assert.throws(() => validateStaticSiteConfig(config));
+    });
+
     it('validates screenshot config', () => {
       let config = {
         screenshot: {

clients/static-site/tests/config.test.js

@@ -54,6 +54,13 @@ describe('config', () => {
       ]);
     });
 
+    it('parses browser type option', () => {
+      let options = { browser: 'firefox' };
+      let config = parseCliOptions(options);
+
+      assert.strictEqual(config.browser.type, 'firefox');
+    });
+
     it('parses screenshot options', () => {
       let options = { fullPage: true };
       let config = parseCliOptions(options);