🐛 Fix Storybook skip filtering via vizzly-skip tag (#215)

clients/storybook/README.md

@@ -94,7 +94,8 @@ Run `vizzly init` to generate a config file with sensible defaults.
 
 ### Per-Story Configuration
 
-You can configure specific stories by adding a `vizzly` parameter in your story files:
+You can configure specific stories by adding tags and `vizzly` parameters in your story files.
+Use `tags: ['vizzly-skip']` as the primary way to skip screenshot capture:
 
 ```javascript
 // Button.stories.js
@@ -114,14 +115,12 @@ export let Primary = {
 
 export let Disabled = {
   args: { label: 'Disabled', disabled: true },
-  parameters: {
-    vizzly: {
-      skip: true, // Don't screenshot this story
-    },
-  },
+  tags: ['vizzly-skip'], // Don't screenshot this story
 };
 ```
 
+`parameters.vizzly.skip` is still supported for backwards compatibility.
+
 ## Configuration Priority
 
 Configuration is merged in this order (later overrides earlier):

clients/storybook/example-storybook/src/components/Button.stories.js

@@ -33,3 +33,12 @@ export let Danger = {
     variant: 'danger',
   },
 };
+
+export let WeShouldNeverSeeThisInVizzly = {
+  name: 'WE SHOULD NEVER SEE THIS IN VIZZLY',
+  tags: ['vizzly-skip'],
+  args: {
+    label: 'WE SHOULD NEVER SEE THIS IN VIZZLY',
+    variant: 'danger',
+  },
+};

clients/storybook/examples/story-with-vizzly-config.stories.js

@@ -46,12 +46,8 @@ export let Deprecated = {
   args: {
     label: 'Old Button',
   },
-  parameters: {
-    vizzly: {
-      // Don't capture screenshots for this story
-      skip: true,
-    },
-  },
+  // Don't capture screenshots for this story
+  tags: ['vizzly-skip'],
 };
 
 // Story with full page screenshot

clients/storybook/src/crawler.js

@@ -96,20 +96,45 @@ export function extractStoryConfig(story) {
   return story.parameters?.vizzly || null;
 }
 
+/**
+ * Check whether a story is tagged to skip Vizzly capture
+ * @param {Object} story - Story object with tags
+ * @returns {boolean}
+ */
+function hasVizzlySkipTag(story) {
+  return Array.isArray(story.tags) && story.tags.includes('vizzly-skip');
+}
+
 /**
  * Filter stories based on include/exclude patterns and skip config
  * @param {Array<Object>} stories - Array of story objects
  * @param {Object} config - Configuration object
  * @returns {Array<Object>} Filtered stories
  */
 export function filterStories(stories, config) {
+  let verbose = process.env.VIZZLY_LOG_LEVEL === 'debug';
+
   // First filter by include/exclude patterns
   let filtered = filterByPattern(stories, config.include, config.exclude);
 
   // Then filter out stories marked to skip
   filtered = filtered.filter(story => {
+    if (hasVizzlySkipTag(story)) {
+      if (verbose) {
+        console.error(`  [filter] Skipping ${story.id} (tag: vizzly-skip)`);
+      }
+      return false;
+    }
+
     let storyConfig = extractStoryConfig(story);
-    return !storyConfig?.skip;
+    if (storyConfig?.skip) {
+      if (verbose) {
+        console.error(`  [filter] Skipping ${story.id} (parameters.vizzly.skip)`);
+      }
+      return false;
+    }
+
+    return true;
   });
 
   return filtered;

clients/storybook/tests/crawler.test.js

@@ -134,6 +134,11 @@ describe('filterStories', () => {
       title: 'Card',
       parameters: { vizzly: { skip: true } },
     },
+    {
+      id: 'button--tag-skipped',
+      title: 'Button',
+      tags: ['vizzly-skip'],
+    },
   ];
 
   it('should filter by include pattern', () => {
@@ -163,6 +168,32 @@ describe('filterStories', () => {
     );
   });
 
+  it('should skip stories tagged with vizzly-skip', () => {
+    let config = {};
+    let filtered = filterStories(stories, config);
+
+    assert.equal(
+      filtered.find(s => s.id === 'button--tag-skipped'),
+      undefined
+    );
+  });
+
+  it('should skip stories when both tag and parameters are present', () => {
+    let config = {};
+    let storiesWithBoth = [
+      ...stories,
+      {
+        id: 'card--both-skipped',
+        title: 'Card',
+        tags: ['vizzly-skip'],
+        parameters: { vizzly: { skip: true } },
+      },
+    ];
+    let filtered = filterStories(storiesWithBoth, config);
+
+    assert.equal(filtered.find(s => s.id === 'card--both-skipped'), undefined);
+  });
+
   it('should apply both include and skip filters', () => {
     let config = { include: 'card*' };
     let filtered = filterStories(stories, config);

clients/storybook/tests/sdk-integration.test.js

@@ -19,12 +19,14 @@ import { join, resolve } from 'node:path';
 import { after, before, describe, it } from 'node:test';
 
 import { closeBrowser, launchBrowser, navigateToUrl } from '../src/browser.js';
-import { discoverStories, generateStoryUrl } from '../src/crawler.js';
+import { discoverStories, generateStoryUrl, readIndexJson } from '../src/crawler.js';
 import { getBeforeScreenshotHook, getStoryConfig } from '../src/hooks.js';
 import { captureAndSendScreenshot } from '../src/screenshot.js';
 import { startStaticServer, stopStaticServer } from '../src/server.js';
 import { setViewport } from '../src/utils/viewport.js';
 
+let skippedStoryName = 'WE SHOULD NEVER SEE THIS IN VIZZLY';
+
 /**
  * Prepare a story page for screenshot (test helper)
  * @param {Object} browser - Browser instance
@@ -217,6 +219,34 @@ describe('Storybook E2E with example-storybook', { skip: !runE2E }, () => {
         );
       }
     });
+
+    it('skips vizzly-skip tagged stories from discovery', async () => {
+      let indexData = await readIndexJson(storybookBuildPath);
+      let entries = Object.values(indexData.entries || indexData.stories || {});
+      let skippedEntry = entries.find(
+        entry =>
+          entry.type === 'story' &&
+          entry.name === skippedStoryName &&
+          entry.tags?.includes('vizzly-skip')
+      );
+
+      assert.ok(
+        skippedEntry,
+        `${skippedStoryName} should exist in storybook index with vizzly-skip tag`
+      );
+
+      let config = {
+        storybookPath: storybookBuildPath,
+        include: null,
+        exclude: null,
+      };
+      let stories = await discoverStories(storybookBuildPath, config);
+
+      assert.equal(
+        stories.find(story => story.name === skippedStoryName),
+        undefined
+      );
+    });
   });
 
   // ===========================================================================