@storybook-astro/framework 0.1.0-beta.9 → 1.0.0

package/src/rules.test.ts

@@ -0,0 +1,183 @@
+import { resolve } from 'node:path';
+import type { RequestHandler } from 'msw';
+import { describe, expect, test } from 'vitest';
+import { defineStoryRules, selectStoryRules, type StoryRulesConfig } from './rules.ts';
+
+function createRulesConfig(config: StoryRulesConfig) {
+  return {
+    default: defineStoryRules(config)
+  };
+}
+
+describe('story rules', () => {
+  test('returns an empty selection when no rules are configured', async () => {
+    const selection = await selectStoryRules({
+      configModule: undefined,
+      mode: 'development',
+      story: {
+        id: 'components-card--default'
+      }
+    });
+
+    expect(selection.moduleMocks.size).toBe(0);
+    expect(selection.mswHandlers).toEqual([]);
+  });
+
+  test('matches rules against story id and applies module mocks', async () => {
+    const selection = await selectStoryRules({
+      configModule: createRulesConfig({
+        rules: [
+          {
+            match: 'components-card--*',
+            use: ({ mock }) => {
+              mock('~/lib/api', '~/lib/api.mock');
+            }
+          }
+        ]
+      }),
+      mode: 'development',
+      story: {
+        id: 'components-card--default'
+      }
+    });
+
+    expect(selection.moduleMocks.get('~/lib/api')).toBe('~/lib/api.mock');
+    expect(selection.mswHandlers).toHaveLength(0);
+  });
+
+  test('matches rules against title and story name paths', async () => {
+    const selection = await selectStoryRules({
+      configModule: createRulesConfig({
+        rules: [
+          {
+            match: 'guides/getting-started/default-state',
+            use: ({ mock }) => {
+              mock('~/service', '~/service.mock');
+            }
+          }
+        ]
+      }),
+      mode: 'development',
+      story: {
+        id: 'guides-getting-started--default-state',
+        title: 'Guides/Getting Started',
+        name: 'Default State'
+      }
+    });
+
+    expect(selection.moduleMocks.get('~/service')).toBe('~/service.mock');
+  });
+
+  test('matches rules against /story/<id> style story identifiers', async () => {
+    const selection = await selectStoryRules({
+      configModule: createRulesConfig({
+        rules: [
+          {
+            match: '/story/components-card--default',
+            use: ({ mock }) => {
+              mock('~/store', '~/store.mock');
+            }
+          }
+        ]
+      }),
+      mode: 'development',
+      story: {
+        id: '/story/components-card--default'
+      }
+    });
+
+    expect(selection.moduleMocks.get('~/store')).toBe('~/store.mock');
+  });
+
+  test('collects MSW handlers from matching rules', async () => {
+    const firstHandler = {} as RequestHandler;
+    const secondHandler = {} as RequestHandler;
+
+    const selection = await selectStoryRules({
+      configModule: createRulesConfig({
+        rules: [
+          {
+            match: '*',
+            use: ({ msw }) => {
+              msw.use(firstHandler, secondHandler);
+            }
+          }
+        ]
+      }),
+      mode: 'production',
+      story: {
+        id: 'components-card--default'
+      }
+    });
+
+    expect(selection.mswHandlers).toEqual([firstHandler, secondHandler]);
+  });
+
+  test('resolves relative mock replacements from config file location', async () => {
+    const configFilePath = '/repo/.storybook/story-rules.ts';
+
+    const selection = await selectStoryRules({
+      configModule: createRulesConfig({
+        rules: [
+          {
+            match: '*',
+            use: ({ mock }) => {
+              mock('~/lib/api', './mocks/api.ts');
+            }
+          }
+        ]
+      }),
+      configFilePath,
+      mode: 'development',
+      story: {
+        id: 'components-card--default'
+      }
+    });
+
+    expect(selection.moduleMocks.get('~/lib/api')).toBe(
+      resolve('/repo/.storybook', './mocks/api.ts').replaceAll('\\', '/')
+    );
+  });
+
+  test('throws when a rule match pattern is empty', async () => {
+    await expect(
+      selectStoryRules({
+        configModule: createRulesConfig({
+          rules: [
+            {
+              match: '   ',
+              use: () => undefined
+            }
+          ]
+        }),
+        mode: 'development',
+        story: {
+          id: 'components-card--default'
+        }
+      })
+    ).rejects.toThrow('Story rule "match" cannot be empty.');
+  });
+
+  test('throws when a mock replacement is relative but config path is missing', async () => {
+    await expect(
+      selectStoryRules({
+        configModule: createRulesConfig({
+          rules: [
+            {
+              match: '*',
+              use: ({ mock }) => {
+                mock('~/lib/api', './mocks/api.ts');
+              }
+            }
+          ]
+        }),
+        mode: 'development',
+        story: {
+          id: 'components-card--default'
+        }
+      })
+    ).rejects.toThrow(
+      'Story rule mock replacement uses a relative path, but rules config path is unavailable.'
+    );
+  });
+});

package/src/rules.ts

@@ -0,0 +1,314 @@
+import { dirname, isAbsolute, resolve } from 'node:path';
+import type { RequestHandler } from 'msw';
+import type { RenderStoryInput } from './types.ts';
+
+type StoryMode = 'development' | 'production';
+type StoryRuleUseResult = void | Promise<void>;
+
+export type StoryRuleUseContext = {
+  mode: StoryMode;
+  story: StoryRuleStory;
+  msw: {
+    use: (...handlers: RequestHandler[]) => void;
+  };
+  mock: (specifier: string, replacement: string) => void;
+};
+
+export type StoryRuleUse = (context: StoryRuleUseContext) => StoryRuleUseResult;
+
+export type StoryRule = {
+  match: string | string[];
+  use: StoryRuleUse | StoryRuleUse[];
+};
+
+export type StoryRulesConfig = {
+  rules: StoryRule[];
+};
+
+export type StoryRuleStory = {
+  id: string;
+  title?: string;
+  name?: string;
+  keys: string[];
+};
+
+export type StoryRuleSelectionInput = {
+  configModule: unknown;
+  configFilePath?: string;
+  mode: StoryMode;
+  story?: RenderStoryInput;
+};
+
+export type StoryRuleSelection = {
+  moduleMocks: Map<string, string>;
+  mswHandlers: RequestHandler[];
+};
+
+type MutableStoryRuleSelection = {
+  moduleMocks: Map<string, string>;
+  mswHandlers: RequestHandler[];
+};
+
+export function defineStoryRules(config: StoryRulesConfig): StoryRulesConfig {
+  return config;
+}
+
+export async function selectStoryRules(
+  input: StoryRuleSelectionInput
+): Promise<StoryRuleSelection> {
+  const config = normalizeRulesConfig(input.configModule);
+  const story = normalizeStory(input.story);
+  const selection = createEmptySelection();
+
+  for (const rule of config.rules) {
+    if (!isStoryRuleMatch(rule.match, story)) {
+      continue;
+    }
+
+    const uses = Array.isArray(rule.use) ? rule.use : [rule.use];
+
+    for (const use of uses) {
+      if (typeof use !== 'function') {
+        throw new Error('Each story rule "use" entry must be a function.');
+      }
+
+      await use({
+        mode: input.mode,
+        story,
+        msw: {
+          use: (...handlers) => {
+            selection.mswHandlers.push(...handlers);
+          }
+        },
+        mock: (specifier, replacement) => {
+          const normalizedSpecifier = normalizeMockSpecifier(specifier);
+          const normalizedReplacement = normalizeMockReplacement(replacement, input.configFilePath);
+
+          selection.moduleMocks.set(normalizedSpecifier, normalizedReplacement);
+        }
+      });
+    }
+  }
+
+  return selection;
+}
+
+function normalizeRulesConfig(configModule: unknown): StoryRulesConfig {
+  const configExport = getRulesConfigExport(configModule);
+
+  if (configExport === undefined || configExport === null) {
+    return {
+      rules: []
+    };
+  }
+
+  if (!isRecord(configExport)) {
+    throw new Error(
+      'Story rules config must export an object with a "rules" array via a default export or named export.'
+    );
+  }
+
+  const rules = configExport.rules;
+
+  if (rules === undefined) {
+    return {
+      rules: []
+    };
+  }
+
+  if (!Array.isArray(rules)) {
+    throw new Error('Story rules config "rules" must be an array.');
+  }
+
+  return {
+    rules: rules as StoryRule[]
+  };
+}
+
+function getRulesConfigExport(configModule: unknown): unknown {
+  if (!isRecord(configModule)) {
+    return configModule;
+  }
+
+  if ('default' in configModule && configModule.default !== undefined) {
+    return configModule.default;
+  }
+
+  if ('rules' in configModule) {
+    return {
+      rules: configModule.rules
+    };
+  }
+
+  return undefined;
+}
+
+function normalizeStory(story?: RenderStoryInput): StoryRuleStory {
+  const id = normalizeStoryId(story?.id);
+  const title = normalizeOptionalString(story?.title);
+  const name = normalizeOptionalString(story?.name);
+  const keys = Array.from(resolveStoryKeys({ id, title, name }));
+
+  return {
+    id,
+    title,
+    name,
+    keys
+  };
+}
+
+function resolveStoryKeys(story: { id: string; title?: string; name?: string }) {
+  const keys = new Set<string>();
+
+  keys.add('');
+
+  const storyId = story.id;
+  const idPath = storyId ? storyId.replaceAll('--', '/') : '';
+
+  if (storyId) {
+    keys.add(storyId);
+    keys.add(`/story/${storyId}`);
+  }
+
+  if (idPath) {
+    keys.add(idPath);
+    keys.add(`/story/${idPath}`);
+  }
+
+  const titlePath = story.title
+    ? story.title
+        .split('/')
+        .map((segment) => slugify(segment))
+        .filter(Boolean)
+        .join('/')
+    : '';
+
+  const storyNamePath = story.name ? slugify(story.name) : '';
+
+  if (titlePath && storyNamePath) {
+    const composedPath = `${titlePath}/${storyNamePath}`;
+
+    keys.add(composedPath);
+    keys.add(`/story/${composedPath}`);
+  }
+
+  return keys;
+}
+
+function isStoryRuleMatch(match: string | string[], story: StoryRuleStory): boolean {
+  const patterns = Array.isArray(match) ? match : [match];
+
+  return patterns.some((pattern) => {
+    if (typeof pattern !== 'string') {
+      throw new Error('Story rule "match" must be a string or an array of strings.');
+    }
+
+    const normalizedPattern = pattern.trim();
+
+    if (!normalizedPattern) {
+      throw new Error('Story rule "match" cannot be empty.');
+    }
+
+    return story.keys.some((key) => isWildcardMatch(normalizedPattern, key));
+  });
+}
+
+function isWildcardMatch(pattern: string, candidate: string): boolean {
+  const escapedPattern = escapeRegExp(pattern).replaceAll('*', '.*');
+  const regex = new RegExp(`^${escapedPattern}$`);
+
+  return regex.test(candidate);
+}
+
+function normalizeStoryId(id?: string): string {
+  const value = normalizeOptionalString(id) ?? '';
+
+  if (!value) {
+    return '';
+  }
+
+  return value.startsWith('/story/') ? value.slice('/story/'.length) : value;
+}
+
+function normalizeOptionalString(value: unknown): string | undefined {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalizedValue = value.trim();
+
+  return normalizedValue || undefined;
+}
+
+function normalizeMockSpecifier(value: unknown): string {
+  if (typeof value !== 'string') {
+    throw new Error('Story rule mock specifier must be a string.');
+  }
+
+  const normalizedValue = value.trim();
+
+  if (!normalizedValue) {
+    throw new Error('Story rule mock specifier cannot be empty.');
+  }
+
+  return normalizedValue;
+}
+
+function normalizeMockReplacement(value: unknown, configFilePath?: string): string {
+  if (typeof value !== 'string') {
+    throw new Error('Story rule mock replacement must be a string.');
+  }
+
+  const normalizedValue = value.trim();
+
+  if (!normalizedValue) {
+    throw new Error('Story rule mock replacement cannot be empty.');
+  }
+
+  if (isAbsolute(normalizedValue)) {
+    return toPosixPath(normalizedValue);
+  }
+
+  if (normalizedValue.startsWith('.')) {
+    if (!configFilePath) {
+      throw new Error(
+        'Story rule mock replacement uses a relative path, but rules config path is unavailable.'
+      );
+    }
+
+    return toPosixPath(resolve(dirname(configFilePath), normalizedValue));
+  }
+
+  return normalizedValue;
+}
+
+function slugify(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function createEmptySelection(): MutableStoryRuleSelection {
+  return {
+    moduleMocks: new Map(),
+    mswHandlers: []
+  };
+}
+
+function toPosixPath(input: string): string {
+  return input.replaceAll('\\', '/');
+}
+
+function escapeRegExp(input: string) {
+  return input.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  return !Array.isArray(value);
+}

package/src/testing/astro-runtime.ts

@@ -0,0 +1,219 @@
+import { fileURLToPath } from 'node:url';
+import type { ViteDevServer } from 'vite';
+import type { Integration as StorybookAstroIntegration } from '../integrations/base.ts';
+import { resolveTestingIntegrationsForRoot } from './integration-config.ts';
+import { resolveTestingProjectRoot } from './project-root.ts';
+import { runWithWorkingDirectory } from './working-directory.ts';
+import { getComponentModuleId, isAstroComponentFactory, isStorybookAstroClientStub } from './component-utils.ts';
+import { ssrLoadModuleWithFsFallback } from '../lib/ssr-load-module-with-fs-fallback.ts';
+import type { ComposedStory } from './types.ts';
+import { renderViaTestingRendererDaemon } from './renderer-daemon.ts';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let astroContainerPromise: Promise<any> | null = null;
+
+const astroSsrViteServerPromises = new Map<string, Promise<ViteDevServer>>();
+
+const astroSsrHandlerPromises = new Map<
+  string,
+  Promise<(data: { component: string; args?: Record<string, unknown> }) => Promise<string>>
+>();
+
+const testingIntegrationsCache = new Map<string, StorybookAstroIntegration[]>();
+
+function getTestingIntegrations(resolveFrom: string) {
+  if (!testingIntegrationsCache.has(resolveFrom)) {
+    testingIntegrationsCache.set(resolveFrom, resolveTestingIntegrationsForRoot(resolveFrom));
+  }
+
+  return testingIntegrationsCache.get(resolveFrom)!;
+}
+
+async function getAstroContainer() {
+  if (!astroContainerPromise) {
+    const { experimental_AstroContainer: AstroContainer } = await import('astro/container');
+
+    astroContainerPromise = AstroContainer.create();
+  }
+
+  return astroContainerPromise;
+}
+
+async function getAstroSsrViteServer(resolveFrom: string) {
+  if (!astroSsrViteServerPromises.has(resolveFrom)) {
+    const { createViteServer } = await import('../viteStorybookAstroMiddlewarePlugin.ts');
+    const integrations = getTestingIntegrations(resolveFrom);
+
+    astroSsrViteServerPromises.set(
+      resolveFrom,
+      runWithWorkingDirectory(resolveFrom, () => createViteServer(integrations, resolveFrom))
+    );
+  }
+
+  return astroSsrViteServerPromises.get(resolveFrom)!;
+}
+
+async function getAstroSsrHandler(resolveFrom: string) {
+  if (!astroSsrHandlerPromises.has(resolveFrom)) {
+    astroSsrHandlerPromises.set(resolveFrom, (async () => {
+      const integrations = getTestingIntegrations(resolveFrom);
+      const viteServer = await getAstroSsrViteServer(resolveFrom);
+      const middlewareModulePath = fileURLToPath(new URL('../middleware', import.meta.url));
+      const middleware = await runWithWorkingDirectory(resolveFrom, () =>
+        viteServer.ssrLoadModule(middlewareModulePath, {
+          fixStacktrace: true
+        })
+      );
+
+      return middleware.handlerFactory(integrations, {
+        loadModule: (id: string) =>
+          ssrLoadModuleWithFsFallback(viteServer, id, {
+            fixStacktrace: true
+          })
+      });
+    })());
+  }
+
+  return astroSsrHandlerPromises.get(resolveFrom)!;
+}
+
+async function resolveAstroComponent(component: unknown, resolveFrom: string) {
+  let resolvedComponent = component;
+
+  if (!isAstroComponentFactory(resolvedComponent)) {
+    throw new Error('Story meta.component must be an Astro component factory.');
+  }
+
+  if ('moduleId' in resolvedComponent && typeof resolvedComponent.moduleId === 'string') {
+    const moduleId = resolvedComponent.moduleId;
+    const normalizedModuleId = moduleId.split('?')[0].split('#')[0];
+
+    try {
+      const mod = await import(/* @vite-ignore */ normalizedModuleId) as Record<string, unknown>;
+
+      if (isAstroComponentFactory(mod.default)) {
+        resolvedComponent = mod.default;
+      }
+    } catch {
+      // keep current component when direct module import is unavailable
+    }
+
+    if (isStorybookAstroClientStub(resolvedComponent)) {
+      try {
+        const viteServer = await getAstroSsrViteServer(resolveFrom);
+        const mod = (await ssrLoadModuleWithFsFallback(viteServer, normalizedModuleId)) as Record<string, unknown>;
+
+        if (isAstroComponentFactory(mod.default)) {
+          resolvedComponent = mod.default;
+        }
+      } catch {
+        // keep current component when SSR module loading is unavailable
+      }
+    }
+  }
+
+  return resolvedComponent;
+}
+
+async function renderAstroComponentToDom(
+  component: unknown,
+  args: Record<string, unknown>,
+  resolveFrom: string
+) {
+  const moduleId = getComponentModuleId(component);
+
+  if (moduleId) {
+    try {
+      // Fast path: reuse a single shared SSR daemon instead of spinning SSR in each worker.
+      const html = await renderViaTestingRendererDaemon({
+        resolveFrom,
+        component: moduleId,
+        args
+      });
+
+      if (typeof html === 'string') {
+        if (typeof document !== 'undefined') {
+          document.body.innerHTML = html;
+        }
+
+        return html;
+      }
+    } catch {
+      // Fall back to in-worker rendering below when daemon render fails.
+    }
+
+    try {
+      const handler = await getAstroSsrHandler(resolveFrom);
+      const html = await handler({
+        component: moduleId,
+        args
+      });
+
+      if (typeof document !== 'undefined') {
+        document.body.innerHTML = html;
+      }
+
+      return html;
+    } catch {
+      // Fall back to direct Container rendering below
+    }
+  }
+
+  const resolvedComponent = await resolveAstroComponent(component, resolveFrom);
+  const container = await getAstroContainer();
+  
+  if (!container) {
+    throw new Error('Failed to initialize Astro container for rendering');
+  }
+  
+  const html = await container.renderToString(resolvedComponent, {
+    props: args
+  });
+
+  if (typeof document !== 'undefined') {
+    document.body.innerHTML = html;
+  }
+
+  return html;
+}
+
+async function renderComposedStory(story: ComposedStory) {
+  const meta = story.__storybookAstroMeta;
+  const storyExport = story.__storybookAstroStoryExport;
+  let component = meta?.component ?? story.component;
+
+  if (!isAstroComponentFactory(component)) {
+    const maybeRendered = await story();
+
+    if (isAstroComponentFactory(maybeRendered)) {
+      component = maybeRendered;
+    } else if (
+      typeof maybeRendered === 'object' &&
+      maybeRendered !== null &&
+      'component' in maybeRendered &&
+      isAstroComponentFactory((maybeRendered as { component: unknown }).component)
+    ) {
+      component = (maybeRendered as { component: unknown }).component;
+    }
+  }
+
+  if (!component) {
+    throw new Error('Unable to resolve Astro component from composed story.');
+  }
+
+  const args = {
+    ...(meta?.args ?? {}),
+    ...(storyExport?.args ?? {}),
+    ...(story.args ?? {})
+  };
+
+  const resolveFrom = await resolveTestingProjectRoot(component);
+
+  return renderAstroComponentToDom(component, args, resolveFrom);
+}
+
+export async function renderStory(story: ComposedStory) {
+  return renderComposedStory(story);
+}
+
+export const renderAstroStory = renderStory;