✨ Add --dry-run option to preview page discovery

- Add --dry-run flag to print discovered pages without capturing screenshots
- Shows pages grouped by source (sitemap vs HTML scan)
- Displays task count, viewports, and concurrency settings
- Useful for debugging page discovery and include/exclude patterns

Also includes tests for:
- Sitemap XML parsing (standard and index formats)
- Config schema validation and smart concurrency defaults
- Dry-run mode behavior with various options

Author: Robdel12

clients/static-site/README.md

@@ -77,7 +77,8 @@ export default {
       omitBackground: false,
     },
 
-    concurrency: 3,
+    // Concurrency auto-detected from CPU cores (min 2, max 8)
+    // concurrency: 4,
 
     // Page filtering
     include: 'blog/**',
@@ -134,12 +135,13 @@ Configuration is merged in this order (later overrides earlier):
 ## CLI Options
 
 - `--viewports <list>` - Comma-separated viewport definitions (format: `name:WxH`)
-- `--concurrency <n>` - Number of parallel pages to process (default: 3)
+- `--concurrency <n>` - Number of parallel browser tabs (default: auto-detected based on CPU cores, min 2, max 8)
 - `--include <pattern>` - Include page pattern (glob)
 - `--exclude <pattern>` - Exclude page pattern (glob)
 - `--browser-args <args>` - Additional Puppeteer browser arguments
 - `--headless` - Run browser in headless mode (default: true)
 - `--full-page` - Capture full page screenshots (default: false)
+- `--dry-run` - Print discovered pages and task count without capturing screenshots
 - `--use-sitemap` - Use sitemap.xml for page discovery (default: true)
 - `--sitemap-path <path>` - Path to sitemap.xml relative to build directory
 
@@ -382,6 +384,13 @@ jobs:
 
 ### Pages not found
 
+Use `--dry-run` to see which pages are discovered without capturing screenshots:
+```bash
+vizzly static-site ./dist --dry-run
+```
+
+This shows pages grouped by source (sitemap vs HTML scan), the total screenshot count, and your current configuration.
+
 Ensure your build has completed and check for sitemap.xml or HTML files:
 ```bash
 ls dist/sitemap.xml

clients/static-site/src/index.js

@@ -93,6 +93,51 @@ export async function run(buildPath, options = {}, context = {}) {
     // Load and merge configuration
     let config = await loadConfig(buildPath, options, vizzlyConfig);
 
+    // Handle dry-run mode early - just discover and print pages
+    if (options.dryRun) {
+      let pages = await discoverPages(config.buildPath, config);
+      logger.info(
+        `🔍 Dry run: Found ${pages.length} pages in ${config.buildPath}\n`
+      );
+
+      if (pages.length === 0) {
+        logger.warn('   No pages found matching your configuration.');
+        return;
+      }
+
+      // Group by source for clarity
+      let sitemapPages = pages.filter(p => p.source === 'sitemap');
+      let htmlPages = pages.filter(p => p.source === 'html');
+
+      if (sitemapPages.length > 0) {
+        logger.info(`   From sitemap (${sitemapPages.length}):`);
+        for (let page of sitemapPages) {
+          logger.info(`     ${page.path}`);
+        }
+      }
+
+      if (htmlPages.length > 0) {
+        logger.info(`   From HTML scan (${htmlPages.length}):`);
+        for (let page of htmlPages) {
+          logger.info(`     ${page.path}`);
+        }
+      }
+
+      // Show task count that would be generated
+      let taskCount = pages.length * config.viewports.length;
+      logger.info('');
+      logger.info(`📸 Would capture ${taskCount} screenshots:`);
+      logger.info(
+        `   ${pages.length} pages × ${config.viewports.length} viewports`
+      );
+      logger.info(
+        `   Viewports: ${config.viewports.map(v => `${v.name} (${v.width}×${v.height})`).join(', ')}`
+      );
+      logger.info(`   Concurrency: ${config.concurrency} tabs`);
+
+      return;
+    }
+
     // Determine mode: TDD or Run
     let debug = logger.debug?.bind(logger) || (() => {});
     let isTdd = await isTddModeAvailable(debug);
@@ -205,7 +250,9 @@ export async function run(buildPath, options = {}, context = {}) {
       logger.info('      npx vizzly static-site ./dist');
       logger.info('');
       logger.info('   2. Or set VIZZLY_TOKEN for cloud uploads:');
-      logger.info('      VIZZLY_TOKEN=your-token npx vizzly static-site ./dist');
+      logger.info(
+        '      VIZZLY_TOKEN=your-token npx vizzly static-site ./dist'
+      );
       logger.info('');
       return;
     }

clients/static-site/src/plugin.js

@@ -66,6 +66,10 @@ export default {
       .option('--browser-args <args>', 'Additional Puppeteer browser arguments')
       .option('--headless', 'Run browser in headless mode')
       .option('--full-page', 'Capture full page screenshots')
+      .option(
+        '--dry-run',
+        'Print discovered pages without capturing screenshots'
+      )
       .option('--use-sitemap', 'Use sitemap.xml for page discovery')
       .option(
         '--sitemap-path <path>',

clients/static-site/src/tasks.js

@@ -242,7 +242,9 @@ export async function processAllTasks(tasks, pool, config, logger, deps = {}) {
 
   // Log total time
   let totalTime = Date.now() - startTime;
-  logger.info(`   ✅ Completed ${total} screenshots in ${formatDuration(totalTime)}`);
+  logger.info(
+    `   ✅ Completed ${total} screenshots in ${formatDuration(totalTime)}`
+  );
 
   if (errors.length > 0) {
     logger.warn(`   ⚠️  ${errors.length} failed`);

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

@@ -0,0 +1,190 @@
+/**
+ * Tests for configuration schema validation
+ */
+
+import assert from 'node:assert';
+import { cpus } from 'node:os';
+import { describe, it } from 'node:test';
+import {
+  getDefaultConcurrency,
+  validateStaticSiteConfig,
+  validateStaticSiteConfigWithDefaults,
+} from '../src/config-schema.js';
+
+describe('config-schema', () => {
+  describe('getDefaultConcurrency', () => {
+    it('returns a positive integer', () => {
+      let concurrency = getDefaultConcurrency();
+
+      assert.ok(Number.isInteger(concurrency));
+      assert.ok(concurrency > 0);
+    });
+
+    it('returns at least 2', () => {
+      let concurrency = getDefaultConcurrency();
+
+      assert.ok(concurrency >= 2);
+    });
+
+    it('returns at most 8', () => {
+      let concurrency = getDefaultConcurrency();
+
+      assert.ok(concurrency <= 8);
+    });
+
+    it('calculates based on CPU cores', () => {
+      let cores = cpus().length;
+      let expected = Math.max(2, Math.min(8, Math.floor(cores / 2)));
+      let concurrency = getDefaultConcurrency();
+
+      assert.strictEqual(concurrency, expected);
+    });
+  });
+
+  describe('validateStaticSiteConfig', () => {
+    it('validates minimal config', () => {
+      let config = {};
+
+      let validated = validateStaticSiteConfig(config);
+
+      assert.ok(validated.viewports);
+      assert.ok(validated.browser);
+      assert.ok(validated.screenshot);
+      assert.ok(validated.pageDiscovery);
+    });
+
+    it('applies default concurrency from CPU cores', () => {
+      let config = {};
+
+      let validated = validateStaticSiteConfig(config);
+      let expected = getDefaultConcurrency();
+
+      assert.strictEqual(validated.concurrency, expected);
+    });
+
+    it('allows overriding concurrency', () => {
+      let config = { concurrency: 10 };
+
+      let validated = validateStaticSiteConfig(config);
+
+      assert.strictEqual(validated.concurrency, 10);
+    });
+
+    it('validates viewports', () => {
+      let config = {
+        viewports: [
+          { name: 'mobile', width: 375, height: 667 },
+          { name: 'desktop', width: 1920, height: 1080 },
+        ],
+      };
+
+      let validated = validateStaticSiteConfig(config);
+
+      assert.strictEqual(validated.viewports.length, 2);
+      assert.strictEqual(validated.viewports[0].name, 'mobile');
+    });
+
+    it('rejects invalid viewport', () => {
+      let config = {
+        viewports: [{ name: 'invalid', width: -100, height: 667 }],
+      };
+
+      assert.throws(() => validateStaticSiteConfig(config));
+    });
+
+    it('validates browser config', () => {
+      let config = {
+        browser: {
+          headless: false,
+          args: ['--no-sandbox'],
+        },
+      };
+
+      let validated = validateStaticSiteConfig(config);
+
+      assert.strictEqual(validated.browser.headless, false);
+      assert.deepStrictEqual(validated.browser.args, ['--no-sandbox']);
+    });
+
+    it('validates screenshot config', () => {
+      let config = {
+        screenshot: {
+          fullPage: true,
+          omitBackground: true,
+        },
+      };
+
+      let validated = validateStaticSiteConfig(config);
+
+      assert.strictEqual(validated.screenshot.fullPage, true);
+      assert.strictEqual(validated.screenshot.omitBackground, true);
+    });
+
+    it('validates page discovery config', () => {
+      let config = {
+        pageDiscovery: {
+          useSitemap: false,
+          sitemapPath: 'custom-sitemap.xml',
+          scanHtml: true,
+        },
+      };
+
+      let validated = validateStaticSiteConfig(config);
+
+      assert.strictEqual(validated.pageDiscovery.useSitemap, false);
+      assert.strictEqual(
+        validated.pageDiscovery.sitemapPath,
+        'custom-sitemap.xml'
+      );
+    });
+
+    it('validates include/exclude patterns', () => {
+      let config = {
+        include: '/blog/*',
+        exclude: '/drafts/*',
+      };
+
+      let validated = validateStaticSiteConfig(config);
+
+      assert.strictEqual(validated.include, '/blog/*');
+      assert.strictEqual(validated.exclude, '/drafts/*');
+    });
+
+    it('allows null include/exclude', () => {
+      let config = {
+        include: null,
+        exclude: null,
+      };
+
+      let validated = validateStaticSiteConfig(config);
+
+      assert.strictEqual(validated.include, null);
+      assert.strictEqual(validated.exclude, null);
+    });
+  });
+
+  describe('validateStaticSiteConfigWithDefaults', () => {
+    it('returns defaults when config is undefined', () => {
+      let validated = validateStaticSiteConfigWithDefaults(undefined);
+
+      assert.ok(validated.viewports);
+      assert.ok(validated.browser);
+      assert.ok(validated.concurrency > 0);
+    });
+
+    it('returns defaults when config is null', () => {
+      let validated = validateStaticSiteConfigWithDefaults(null);
+
+      assert.ok(validated.viewports);
+      assert.ok(validated.concurrency > 0);
+    });
+
+    it('validates provided config', () => {
+      let config = { concurrency: 5 };
+
+      let validated = validateStaticSiteConfigWithDefaults(config);
+
+      assert.strictEqual(validated.concurrency, 5);
+    });
+  });
+});

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

@@ -66,7 +66,10 @@ describe('config', () => {
       let config = parseCliOptions(options);
 
       assert.strictEqual(config.pageDiscovery.useSitemap, false);
-      assert.strictEqual(config.pageDiscovery.sitemapPath, 'custom-sitemap.xml');
+      assert.strictEqual(
+        config.pageDiscovery.sitemapPath,
+        'custom-sitemap.xml'
+      );
     });
   });
 

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

@@ -31,7 +31,10 @@ describe('crawler', () => {
     });
 
     it('normalizes separators', () => {
-      assert.strictEqual(filePathToUrlPath('blog\\post-1.html'), '/blog/post-1');
+      assert.strictEqual(
+        filePathToUrlPath('blog\\post-1.html'),
+        '/blog/post-1'
+      );
     });
 
     it('ensures leading slash', () => {