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

package/src/testing/component-utils.ts

@@ -0,0 +1,32 @@
+export function isStorybookAstroClientStub(component: unknown) {
+  return (
+    typeof component === 'function' &&
+    String(component).includes('Astro components are rendered server-side by Storybook')
+  );
+}
+
+export function isAstroComponentFactory(component: unknown) {
+  return typeof component === 'function' && 'isAstroComponentFactory' in component;
+}
+
+export function getComponentModuleId(component: unknown) {
+  if (typeof component !== 'function' || !('moduleId' in component)) {
+    return null;
+  }
+
+  if (typeof component.moduleId !== 'string') {
+    return null;
+  }
+
+  return component.moduleId.split('?')[0].split('#')[0];
+}
+
+export function getComponentModuleFilePath(component: unknown) {
+  const moduleId = getComponentModuleId(component);
+
+  if (!moduleId || !moduleId.startsWith('/')) {
+    return null;
+  }
+
+  return moduleId;
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export { composeStories, composeStory, setProjectAnnotations } from './story-composition.ts';
+export { renderStory, renderAstroStory } from './astro-runtime.ts';

package/src/testing/integration-config.ts

@@ -0,0 +1,121 @@
+import { resolve as resolvePath } from 'node:path';
+import type { Integration } from '../integrations/base.ts';
+import {
+  alpinejs,
+  preact,
+  react,
+  solid,
+  svelte,
+  vue,
+} from '../integrations/index.ts';
+
+const TESTING_INTEGRATIONS_ENV = 'STORYBOOK_ASTRO_TESTING_INTEGRATIONS';
+
+type SerializedIntegration = {
+  name: string;
+  options: unknown;
+};
+
+type SerializedIntegrationMap = Record<string, SerializedIntegration[]>;
+
+const REGEXP_TAG = '__storybookAstroRegExp';
+
+function replacer(_key: string, value: unknown): unknown {
+  if (value instanceof RegExp) {
+    return {
+      [REGEXP_TAG]: true,
+      source: value.source,
+      flags: value.flags
+    };
+  }
+
+  return value;
+}
+
+function reviver(_key: string, value: unknown): unknown {
+  if (
+    value &&
+    typeof value === 'object' &&
+    REGEXP_TAG in value &&
+    (value as Record<string, unknown>)[REGEXP_TAG] === true
+  ) {
+    const source = (value as Record<string, unknown>).source;
+    const flags = (value as Record<string, unknown>).flags;
+
+    if (typeof source === 'string' && typeof flags === 'string') {
+      return new RegExp(source, flags);
+    }
+  }
+
+  return value;
+}
+
+function readIntegrationMapFromEnv(): SerializedIntegrationMap {
+  const raw = process.env[TESTING_INTEGRATIONS_ENV];
+
+  if (!raw) {
+    return {};
+  }
+
+  try {
+    const parsed = JSON.parse(raw, reviver);
+
+    if (!parsed || typeof parsed !== 'object') {
+      return {};
+    }
+
+    return parsed as SerializedIntegrationMap;
+  } catch {
+    return {};
+  }
+}
+
+function writeIntegrationMapToEnv(value: SerializedIntegrationMap) {
+  process.env[TESTING_INTEGRATIONS_ENV] = JSON.stringify(value, replacer);
+}
+
+function serializeIntegration(integration: Integration): SerializedIntegration {
+  return {
+    name: integration.name,
+    options: integration.options
+  };
+}
+
+function deserializeIntegration(integration: SerializedIntegration): Integration {
+  switch (integration.name) {
+    case 'react':
+      return react(integration.options as Parameters<typeof react>[0]);
+    case 'solid':
+      return solid(integration.options as Parameters<typeof solid>[0]);
+    case 'preact':
+      return preact(integration.options as Parameters<typeof preact>[0]);
+    case 'vue':
+      return vue(integration.options as Parameters<typeof vue>[0]);
+    case 'svelte':
+      return svelte(integration.options as Parameters<typeof svelte>[0]);
+    case 'alpine':
+      return alpinejs(integration.options as Parameters<typeof alpinejs>[0]);
+    default:
+      throw new Error(`Unknown testing integration: ${integration.name}`);
+  }
+}
+
+export function registerTestingIntegrationsForRoot(root: string, integrations: Integration[]) {
+  const normalizedRoot = resolvePath(root);
+  const integrationMap = readIntegrationMapFromEnv();
+
+  integrationMap[normalizedRoot] = integrations.map(serializeIntegration);
+  writeIntegrationMapToEnv(integrationMap);
+}
+
+export function resolveTestingIntegrationsForRoot(root: string): Integration[] {
+  const normalizedRoot = resolvePath(root);
+  const integrationMap = readIntegrationMapFromEnv();
+  const integrations = integrationMap[normalizedRoot];
+
+  if (!integrations) {
+    return [];
+  }
+
+  return integrations.map(deserializeIntegration);
+}

package/src/testing/project-root.ts

@@ -0,0 +1,185 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getComponentModuleFilePath } from './component-utils.ts';
+
+const VITEST_CONFIG_FILES = [
+  'vitest.config.ts',
+  'vitest.config.mts',
+  'vitest.config.js',
+  'vitest.config.mjs',
+  'vitest.config.cjs'
+];
+
+function extractStackFilePath(line: string) {
+  const trimmed = line.trim();
+
+  const match = trimmed.match(/\((.+):(\d+):(\d+)\)$/) ?? trimmed.match(/^at\s+(.+):(\d+):(\d+)$/);
+
+  if (!match) {
+    return null;
+  }
+
+  const rawPath = match[1];
+
+  if (rawPath.startsWith('node:')) {
+    return null;
+  }
+
+  if (rawPath.startsWith('file://')) {
+    return fileURLToPath(rawPath);
+  }
+
+  if (rawPath.startsWith('/')) {
+    return rawPath;
+  }
+
+  return null;
+}
+
+async function getCurrentTestFilePath() {
+  try {
+    const { expect } = await import('vitest');
+    const vitestState = expect.getState() as {
+      testPath?: string;
+      filepath?: string;
+      filePath?: string;
+    };
+
+    const fromVitestState = vitestState.testPath ?? vitestState.filepath ?? vitestState.filePath;
+
+    if (typeof fromVitestState === 'string') {
+      const absolutePath = fromVitestState.startsWith('/')
+        ? fromVitestState
+        : resolve(process.cwd(), fromVitestState);
+
+      if (existsSync(absolutePath)) {
+        return absolutePath;
+      }
+    }
+  } catch {
+    // Fall through to stack-based lookup when Vitest state is unavailable.
+  }
+
+  const stack = new Error().stack;
+
+  if (!stack) {
+    return null;
+  }
+
+  const thisFilePath = fileURLToPath(import.meta.url);
+
+  for (const line of stack.split('\n')) {
+    const filePath = extractStackFilePath(line);
+
+    if (!filePath) {
+      continue;
+    }
+
+    if (filePath === thisFilePath || filePath.includes('/node_modules/')) {
+      continue;
+    }
+
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+
+  return null;
+}
+
+function findNearestVitestConfigDir(startPath: string) {
+  let dir = dirname(startPath);
+
+  while (true) {
+    if (VITEST_CONFIG_FILES.some((name) => existsSync(join(dir, name)))) {
+      return dir;
+    }
+
+    const parent = dirname(dir);
+
+    if (parent === dir) {
+      break;
+    }
+
+    dir = parent;
+  }
+
+  return null;
+}
+
+function packageJsonDeclaresAstro(packageJsonPath: string) {
+  if (!existsSync(packageJsonPath)) {
+    return false;
+  }
+
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+
+    return ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'].some(
+      (field) =>
+        packageJson[field] &&
+        typeof packageJson[field] === 'object' &&
+        Object.prototype.hasOwnProperty.call(packageJson[field], 'astro')
+    );
+  } catch {
+    return false;
+  }
+}
+
+function findNearestAstroPackageDir(startPath: string) {
+  let dir = dirname(startPath);
+
+  while (true) {
+    const packageJsonPath = join(dir, 'package.json');
+
+    if (packageJsonDeclaresAstro(packageJsonPath)) {
+      return dir;
+    }
+
+    const parent = dirname(dir);
+
+    if (parent === dir) {
+      break;
+    }
+
+    dir = parent;
+  }
+
+  return null;
+}
+
+function canResolveAstroFrom(dir: string) {
+  try {
+    const require = createRequire(`${join(dir, '__storybook-astro-testing-resolve__.js')}`);
+
+    require.resolve('astro/package.json');
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveTestingProjectRoot(component: unknown) {
+  const currentTestFilePath = await getCurrentTestFilePath();
+  const componentModulePath = getComponentModuleFilePath(component);
+  const candidates = [
+    currentTestFilePath ? findNearestVitestConfigDir(currentTestFilePath) : null,
+    currentTestFilePath ? findNearestAstroPackageDir(currentTestFilePath) : null,
+    componentModulePath ? findNearestAstroPackageDir(componentModulePath) : null,
+    packageJsonDeclaresAstro(join(process.cwd(), 'package.json')) ? process.cwd() : null,
+    process.env.INIT_CWD && packageJsonDeclaresAstro(join(process.env.INIT_CWD, 'package.json'))
+      ? process.env.INIT_CWD
+      : null
+  ].filter((value): value is string => Boolean(value));
+
+  for (const candidate of candidates) {
+    if (canResolveAstroFrom(candidate)) {
+      return candidate;
+    }
+  }
+
+  return process.cwd();
+}

package/src/testing/renderer-daemon.ts

@@ -0,0 +1,269 @@
+import { createServer as createHttpServer } from 'node:http';
+import type { IncomingMessage } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import type { ViteDevServer } from 'vite';
+import { createViteServer } from '../viteStorybookAstroMiddlewarePlugin.ts';
+import { resolveTestingIntegrationsForRoot } from './integration-config.ts';
+import { runWithWorkingDirectory } from './working-directory.ts';
+import { ssrLoadModuleWithFsFallback } from '../lib/ssr-load-module-with-fs-fallback.ts';
+
+const RENDER_PATH = '/render';
+
+export const TESTING_RENDERER_DAEMON_URL_ENV = 'STORYBOOK_ASTRO_TESTING_RENDERER_DAEMON_URL';
+
+type RenderPayload = {
+  resolveFrom: string;
+  component: string;
+  args?: Record<string, unknown>;
+  slots?: Record<string, unknown>;
+};
+
+type RenderHandler = (data: {
+  component: string;
+  args?: Record<string, unknown>;
+  slots?: Record<string, unknown>;
+}) => Promise<string>;
+
+type RunningDaemon = {
+  url: string;
+  close: () => Promise<void>;
+};
+
+async function readJsonBody(request: IncomingMessage) {
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+
+  if (chunks.length === 0) {
+    return null;
+  }
+
+  return JSON.parse(Buffer.concat(chunks).toString('utf-8')) as unknown;
+}
+
+function createBadRequest(message: string) {
+  const error = new Error(message);
+
+  (error as Error & { statusCode?: number }).statusCode = 400;
+
+  return error;
+}
+
+function assertRenderPayload(payload: unknown): asserts payload is RenderPayload {
+  if (!payload || typeof payload !== 'object') {
+    throw createBadRequest('Invalid render payload.');
+  }
+
+  const record = payload as Record<string, unknown>;
+
+  if (typeof record.resolveFrom !== 'string' || record.resolveFrom.length === 0) {
+    throw createBadRequest('Missing render payload field: resolveFrom.');
+  }
+
+  if (typeof record.component !== 'string' || record.component.length === 0) {
+    throw createBadRequest('Missing render payload field: component.');
+  }
+
+  if (
+    'args' in record &&
+    typeof record.args !== 'undefined' &&
+    (typeof record.args !== 'object' || record.args === null || Array.isArray(record.args))
+  ) {
+    throw createBadRequest('Render payload field args must be an object when provided.');
+  }
+
+  if (
+    'slots' in record &&
+    typeof record.slots !== 'undefined' &&
+    (typeof record.slots !== 'object' || record.slots === null || Array.isArray(record.slots))
+  ) {
+    throw createBadRequest('Render payload field slots must be an object when provided.');
+  }
+}
+
+function getErrorStatusCode(error: unknown) {
+  if (error && typeof error === 'object' && 'statusCode' in error) {
+    const statusCode = (error as { statusCode?: unknown }).statusCode;
+
+    if (typeof statusCode === 'number' && Number.isInteger(statusCode) && statusCode >= 400) {
+      return statusCode;
+    }
+  }
+
+  return 500;
+}
+
+export async function startTestingRendererDaemon(): Promise<RunningDaemon> {
+  // One daemon process serves all Vitest workers; cache is keyed by project root.
+  const viteServerPromises = new Map<string, Promise<ViteDevServer>>();
+  const renderHandlerPromises = new Map<string, Promise<RenderHandler>>();
+
+  async function getViteServer(resolveFrom: string) {
+    if (!viteServerPromises.has(resolveFrom)) {
+      const integrations = resolveTestingIntegrationsForRoot(resolveFrom);
+
+      viteServerPromises.set(
+        resolveFrom,
+        runWithWorkingDirectory(resolveFrom, () => createViteServer(integrations, resolveFrom))
+      );
+    }
+
+    return viteServerPromises.get(resolveFrom)!;
+  }
+
+  async function getRenderHandler(resolveFrom: string) {
+    if (!renderHandlerPromises.has(resolveFrom)) {
+      renderHandlerPromises.set(resolveFrom, (async () => {
+        const integrations = resolveTestingIntegrationsForRoot(resolveFrom);
+        const viteServer = await getViteServer(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
+            })
+        }) as Promise<RenderHandler>;
+      })());
+    }
+
+    return renderHandlerPromises.get(resolveFrom)!;
+  }
+
+  const server = createHttpServer(async (request, response) => {
+    // Allow cross-origin requests from browser-like test environments (e.g. happy-dom).
+    response.setHeader('Access-Control-Allow-Origin', '*');
+    response.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+    response.setHeader('Access-Control-Allow-Headers', 'content-type');
+
+    if (request.method === 'OPTIONS') {
+      response.statusCode = 204;
+      response.end();
+
+      return;
+    }
+
+    if (request.method !== 'POST' || request.url !== RENDER_PATH) {
+      response.statusCode = 404;
+      response.end();
+
+      return;
+    }
+
+    try {
+      const payload = await readJsonBody(request);
+
+      assertRenderPayload(payload);
+
+      const handler = await getRenderHandler(payload.resolveFrom);
+      const html = await handler({
+        component: payload.component,
+        args: payload.args,
+        slots: payload.slots
+      });
+
+      response.statusCode = 200;
+      response.setHeader('content-type', 'application/json');
+      response.end(JSON.stringify({ html }));
+    } catch (error) {
+      const statusCode = getErrorStatusCode(error);
+
+      response.statusCode = statusCode;
+      response.setHeader('content-type', 'application/json');
+      response.end(JSON.stringify({
+        error: error instanceof Error ? error.message : String(error)
+      }));
+    }
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+
+  const address = server.address();
+
+  if (!address || typeof address === 'string') {
+    throw new Error('Failed to start Storybook Astro testing renderer daemon.');
+  }
+
+  const url = `http://127.0.0.1:${address.port}${RENDER_PATH}`;
+
+  return {
+    url,
+    close: async () => {
+      await Promise.all(
+        [...viteServerPromises.values()].map(async (viteServerPromise) => {
+          const viteServer = await viteServerPromise;
+
+          await viteServer.close();
+        })
+      );
+
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) {
+            reject(error);
+
+            return;
+          }
+
+          resolve();
+        });
+      });
+    }
+  };
+}
+
+export function getTestingRendererDaemonUrl() {
+  const value = process.env[TESTING_RENDERER_DAEMON_URL_ENV];
+
+  if (!value || value.length === 0) {
+    return null;
+  }
+
+  return value;
+}
+
+export async function renderViaTestingRendererDaemon(payload: RenderPayload) {
+  const daemonUrl = getTestingRendererDaemonUrl();
+
+  if (!daemonUrl) {
+    // Daemon is optional so local in-worker rendering can still be used as fallback.
+    return null;
+  }
+
+  // eslint-disable-next-line n/no-unsupported-features/node-builtins
+  const response = await fetch(daemonUrl, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json'
+    },
+    body: JSON.stringify(payload)
+  });
+
+  const parsed = (await response.json()) as {
+    html?: string;
+    error?: string;
+  };
+
+  if (!response.ok) {
+    throw new Error(parsed.error ?? `Renderer daemon returned ${response.status}.`);
+  }
+
+  if (typeof parsed.html !== 'string') {
+    throw new Error('Renderer daemon returned an invalid payload.');
+  }
+
+  return parsed.html;
+}

package/src/testing/story-composition.ts

@@ -0,0 +1,33 @@
+import {
+  composeStories as portableComposeStories,
+  composeStory as portableComposeStory,
+  setProjectAnnotations as portableSetProjectAnnotations,
+} from '../portable-stories.ts';
+import type { ProjectAnnotations, Store_CSFExports as StoreCsfExports } from 'storybook/internal/types';
+import type { AstroRenderer } from '../portable-stories.ts';
+import type { ComposedStory, StoryMeta } from './types.ts';
+
+export function composeStories<
+  TModule extends StoreCsfExports<AstroRenderer> & Record<string, unknown>
+>(
+  storiesImport: TModule,
+  projectAnnotations?: ProjectAnnotations<AstroRenderer>
+) {
+  const composed = portableComposeStories(storiesImport, projectAnnotations);
+
+  for (const [storyExportName, story] of Object.entries(composed)) {
+    if (typeof story === 'function') {
+      const composedStory = story as ComposedStory;
+
+      composedStory.__storybookAstroMeta = storiesImport.default as StoryMeta;
+      composedStory.__storybookAstroStoryExport = storiesImport[
+        storyExportName as keyof TModule
+      ] as ComposedStory['__storybookAstroStoryExport'];
+    }
+  }
+
+  return composed;
+}
+
+export const composeStory = portableComposeStory;
+export const setProjectAnnotations = portableSetProjectAnnotations;

package/src/testing/types.ts

@@ -0,0 +1,14 @@
+export type StoryMeta = {
+  component: unknown;
+  args?: Record<string, unknown>;
+};
+
+export type ComposedStory = {
+  (...args: unknown[]): unknown;
+  args?: Record<string, unknown>;
+  component?: unknown;
+  run?: () => unknown | Promise<unknown>;
+  storyName?: string;
+  __storybookAstroMeta?: StoryMeta;
+  __storybookAstroStoryExport?: { args?: Record<string, unknown> };
+};

package/src/testing/working-directory.ts

@@ -0,0 +1,28 @@
+let workingDirectoryLock: Promise<void> = Promise.resolve();
+
+export async function runWithWorkingDirectory<T>(dir: string, fn: () => Promise<T>) {
+  const previousLock = workingDirectoryLock;
+  let releaseLock!: () => void;
+
+  workingDirectoryLock = new Promise<void>((resolve) => {
+    releaseLock = resolve;
+  });
+
+  await previousLock;
+
+  const previousCwd = process.cwd();
+
+  try {
+    if (previousCwd !== dir) {
+      process.chdir(dir);
+    }
+
+    return await fn();
+  } finally {
+    if (process.cwd() !== previousCwd) {
+      process.chdir(previousCwd);
+    }
+
+    releaseLock();
+  }
+}