feat: enhance Storybook integration with caching, add MSW handlers, and improve test accessibility

Author: bballdavis

.github/workflows/ci.yml

@@ -200,7 +200,17 @@ jobs:
           cd client
           npm ci
 
+      - name: Cache Storybook build
+        id: cache-storybook
+        uses: actions/cache@v3
+        with:
+          path: client/storybook-static
+          key: ${{ runner.os }}-storybook-${{ hashFiles('client/src/**', 'client/.storybook/**', 'client/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-storybook-
+
       - name: Build Storybook for validation
+        if: steps.cache-storybook.outputs.cache-hit != 'true'
         run: cd client && npm run build-storybook
 
       - name: Run Jest story validation tests

.gitignore

@@ -58,11 +58,13 @@ backups/
 
 # Storybook outputs and caches
 storybook-static/
-client/storybook-static/
 build-storybook/
 client/build-storybook/
 .cache/storybook/
 
 # Storybook test artifacts
 .out_storybook_
 .storyshots
+
+# MSW service worker - regenerate with: cd client && npx msw init public/ --save
+client/public/mockServiceWorker.js

client/.storybook/fixtures/mswHandlers.js

@@ -0,0 +1,63 @@
+/**
+ * Default MSW request handlers shared across all Storybook stories.
+ *
+ * These provide baseline API responses so stories render without real network
+ * requests. Individual stories can override handlers via `parameters.msw`.
+ *
+ * Regenerate mockServiceWorker.js if it goes missing:
+ *   cd client && npx msw init public/ --save
+ */
+import { http, HttpResponse } from 'msw';
+import { DEFAULT_CONFIG } from '../src/config/configSchema';
+
+export const defaultMswHandlers = [
+  http.get('/getconfig', () =>
+    HttpResponse.json({
+      ...DEFAULT_CONFIG,
+      preferredResolution: '1080',
+      channelFilesToDownload: 3,
+      youtubeOutputDirectory: '/downloads/youtube',
+      isPlatformManaged: {
+        plexUrl: false,
+        authEnabled: true,
+        useTmpForDownloads: false,
+      },
+      deploymentEnvironment: {
+        platform: null,
+        isWsl: false,
+      },
+    })
+  ),
+  http.get('/storage-status', () =>
+    HttpResponse.json({
+      availableGB: '100',
+      percentFree: 50,
+      totalGB: '200',
+    })
+  ),
+  http.get('/api/channels/subfolders', () => HttpResponse.json(['Movies', 'Shows'])),
+  http.get('/api/cookies/status', () =>
+    HttpResponse.json({
+      cookiesEnabled: false,
+      customCookiesUploaded: false,
+      customFileExists: false,
+    })
+  ),
+  http.get('/api/keys', () => HttpResponse.json({ keys: [] })),
+  http.get('/api/db-status', () => HttpResponse.json({ status: 'healthy' })),
+  http.get('/setup/status', () =>
+    HttpResponse.json({
+      requiresSetup: false,
+      isLocalhost: true,
+      platformManaged: false,
+    })
+  ),
+  http.get('/getCurrentReleaseVersion', () =>
+    HttpResponse.json({
+      version: '1.0.0',
+      ytDlpVersion: '2024.01.01',
+    })
+  ),
+  http.get('/get-running-jobs', () => HttpResponse.json([])),
+  http.get('/runningjobs', () => HttpResponse.json([])),
+];

client/.storybook/main.js

@@ -15,11 +15,13 @@ const config = {
       plugins: [tsconfigPaths()],
       define: {
         ...(config.define ?? {}),
-        'process.env': {},
+        // Explicitly define NODE_ENV rather than wiping all of process.env,
+        // which would conflict with envPrefix env-var injection.
+        'process.env.NODE_ENV': JSON.stringify('development'),
       },
       envPrefix: ['VITE_', 'REACT_APP_'],
     });
   },
 };
 
-export default config;
+export default config;

client/.storybook/preview.js

@@ -1,77 +1,28 @@
 import React from 'react';
 import { initialize, mswLoader } from 'msw-storybook-addon';
-import { http, HttpResponse } from 'msw';
 import { ThemeProvider } from '@mui/material/styles';
 import CssBaseline from '@mui/material/CssBaseline';
 import { LocalizationProvider } from '@mui/x-date-pickers';
 import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
 import { MemoryRouter } from 'react-router-dom';
 import WebSocketContext from '../src/contexts/WebSocketContext';
 import { lightTheme, darkTheme } from '../src/theme';
-import { DEFAULT_CONFIG } from '../src/config/configSchema';
+import { defaultMswHandlers } from './fixtures/mswHandlers';
 
 initialize({
   onUnhandledRequest: 'bypass',
 });
 
+/**
+ * Stub WebSocket context for stories. subscribe/unsubscribe are no-ops since
+ * stories don't need live socket events. Override via story decorators if needed.
+ */
 const mockWebSocketContext = {
   socket: null,
   subscribe: () => {},
   unsubscribe: () => {},
 };
 
-const defaultMswHandlers = [
-  http.get('/getconfig', () =>
-    HttpResponse.json({
-      ...DEFAULT_CONFIG,
-      preferredResolution: '1080',
-      channelFilesToDownload: 3,
-      youtubeOutputDirectory: '/downloads/youtube',
-      isPlatformManaged: {
-        plexUrl: false,
-        authEnabled: true,
-        useTmpForDownloads: false,
-      },
-      deploymentEnvironment: {
-        platform: null,
-        isWsl: false,
-      },
-    })
-  ),
-  http.get('/storage-status', () =>
-    HttpResponse.json({
-      availableGB: '100',
-      percentFree: 50,
-      totalGB: '200',
-    })
-  ),
-  http.get('/api/channels/subfolders', () => HttpResponse.json(['Movies', 'Shows'])),
-  http.get('/api/cookies/status', () =>
-    HttpResponse.json({
-      cookiesEnabled: false,
-      customCookiesUploaded: false,
-      customFileExists: false,
-    })
-  ),
-  http.get('/api/keys', () => HttpResponse.json({ keys: [] })),
-  http.get('/api/db-status', () => HttpResponse.json({ status: 'healthy' })),
-  http.get('/setup/status', () =>
-    HttpResponse.json({
-      requiresSetup: false,
-      isLocalhost: true,
-      platformManaged: false,
-    })
-  ),
-  http.get('/getCurrentReleaseVersion', () =>
-    HttpResponse.json({
-      version: '1.0.0',
-      ytDlpVersion: '2024.01.01',
-    })
-  ),
-  http.get('/get-running-jobs', () => HttpResponse.json([])),
-  http.get('/runningjobs', () => HttpResponse.json([])),
-];
-
 const normalizeHandlers = (value) => {
   if (!value) return [];
   if (Array.isArray(value)) return value;
@@ -151,4 +102,4 @@ const preview = {
   ],
 };
 
-export default preview;
+export default preview;

client/.storybook/test-runner.js

@@ -1,3 +1,13 @@
+/**
+ * Storybook test-runner configuration (Playwright-based).
+ *
+ * Used for LOCAL development testing via `npm run test-storybook`.
+ * NOT used in CI — the CI workflow validates stories through Jest
+ * (see client/src/tests/storybook_coverage.test.js and the
+ * test-storybook job in .github/workflows/ci.yml).
+ *
+ * Enable debug output with: STORYBOOK_TEST_RUNNER_DEBUG=1 npm run test-storybook
+ */
 const DEBUG = process.env.STORYBOOK_TEST_RUNNER_DEBUG === '1';
 
 function logLine(line) {
@@ -88,4 +98,4 @@ const config = {
   },
 };
 
-export default config;
+export default config;