@fragments-sdk/cli 0.2.2

package/src/test/discovery.ts

@@ -0,0 +1,172 @@
+/**
+ * Test discovery - finds variants with play functions
+ */
+
+import { readFile } from 'node:fs/promises';
+import type { SegmentsConfig } from '../core/index.js';
+import { discoverSegmentFiles, parseSegmentFile } from '../core/node.js';
+import type { TestCase, DiscoveryOptions } from './types.js';
+
+/**
+ * Discovered segment with play function metadata
+ */
+interface DiscoveredVariant {
+  component: string;
+  variant: string;
+  tags: string[];
+  hasPlayFunction: boolean;
+  storyId?: string;
+  sourceFile: string;
+}
+
+/**
+ * Discover all variants with play functions
+ */
+export async function discoverTests(
+  config: SegmentsConfig,
+  configDir: string,
+  options: DiscoveryOptions = {}
+): Promise<TestCase[]> {
+  const files = await discoverSegmentFiles(config, configDir);
+  const variants: DiscoveredVariant[] = [];
+
+  for (const file of files) {
+    try {
+      const content = await readFile(file.absolutePath, 'utf-8');
+      const parsed = parseSegmentFile(content, file.relativePath);
+
+      if (!parsed.meta.name) continue;
+
+      // Filter by component name if specified
+      if (options.component) {
+        const componentMatch = parsed.meta.name.toLowerCase().includes(options.component.toLowerCase());
+        if (!componentMatch) continue;
+      }
+
+      // Extract tags from meta for the component
+      const componentTags = parsed.meta.tags || [];
+
+      for (const variant of parsed.variants) {
+        // Check if variant has play function by scanning source code
+        const hasPlay = hasPlayFunctionInSource(content, variant.name);
+
+        if (!hasPlay) continue;
+
+        // Filter by tags if specified (use component-level tags since variant tags aren't in parsed data)
+        if (options.tags && options.tags.length > 0) {
+          const hasMatchingTag = options.tags.some((tag: string) =>
+            componentTags.some((ct: string) => ct.toLowerCase().includes(tag.toLowerCase()))
+          );
+          if (!hasMatchingTag) continue;
+        }
+
+        // Filter by grep pattern if specified
+        if (options.grep) {
+          const pattern = new RegExp(options.grep, 'i');
+          const matchesName = pattern.test(variant.name);
+          const matchesComponent = pattern.test(parsed.meta.name);
+          if (!matchesName && !matchesComponent) continue;
+        }
+
+        // Exclude pattern
+        if (options.exclude) {
+          const pattern = new RegExp(options.exclude, 'i');
+          const excludeName = pattern.test(variant.name);
+          const excludeComponent = pattern.test(parsed.meta.name);
+          if (excludeName || excludeComponent) continue;
+        }
+
+        variants.push({
+          component: parsed.meta.name,
+          variant: variant.name,
+          tags: componentTags,
+          hasPlayFunction: true,
+          storyId: undefined, // Not available from static parsing
+          sourceFile: file.relativePath,
+        });
+      }
+    } catch {
+      // Skip files that can't be parsed
+      continue;
+    }
+  }
+
+  // Convert to test cases
+  return variants.map((v) => ({
+    id: `${v.component}--${v.variant}`.replace(/\s+/g, '-').toLowerCase(),
+    component: v.component,
+    variant: v.variant,
+    tags: v.tags,
+    play: null as unknown as TestCase['play'], // Play function loaded at runtime in browser
+    sourceFile: v.sourceFile,
+    storyId: v.storyId,
+  }));
+}
+
+/**
+ * Check if a variant has a play function by scanning the source code
+ */
+function hasPlayFunctionInSource(content: string, variantName: string): boolean {
+  // Look for play function patterns in the source
+  // Pattern 1: play: async ({ ... }) => { ... }
+  // Pattern 2: play: async function ({ ... }) { ... }
+  // Pattern 3: play: playFunction (reference)
+
+  // Normalize variant name for matching (handle Default, Primary, etc.)
+  const patterns = [
+    // Export const VariantName = { ... play: ... }
+    new RegExp(`export\\s+const\\s+${escapeRegExp(variantName)}\\s*=\\s*\\{[^}]*\\bplay\\s*:`, 's'),
+    // variants: [{ name: 'VariantName', ... play: ... }]
+    new RegExp(`name\\s*:\\s*['"\`]${escapeRegExp(variantName)}['"\`][^}]*\\bplay\\s*:`, 's'),
+    // In case the variant has play in its definition object
+    new RegExp(`['"\`]${escapeRegExp(variantName)}['"\`]\\s*:\\s*\\{[^}]*\\bplay\\s*:`, 's'),
+  ];
+
+  return patterns.some(pattern => pattern.test(content));
+}
+
+/**
+ * Escape special regex characters
+ */
+function escapeRegExp(string: string): string {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Group test cases by component
+ */
+export function groupTestsByComponent(testCases: TestCase[]): Map<string, TestCase[]> {
+  const groups = new Map<string, TestCase[]>();
+
+  for (const test of testCases) {
+    const existing = groups.get(test.component) || [];
+    existing.push(test);
+    groups.set(test.component, existing);
+  }
+
+  return groups;
+}
+
+/**
+ * Get unique tags from all test cases
+ */
+export function getUniqueTags(testCases: TestCase[]): string[] {
+  const tags = new Set<string>();
+  for (const test of testCases) {
+    for (const tag of test.tags) {
+      tags.add(tag);
+    }
+  }
+  return Array.from(tags).sort();
+}
+
+/**
+ * Get unique components from all test cases
+ */
+export function getUniqueComponents(testCases: TestCase[]): string[] {
+  const components = new Set<string>();
+  for (const test of testCases) {
+    components.add(test.component);
+  }
+  return Array.from(components).sort();
+}

package/src/test/index.ts

@@ -0,0 +1,281 @@
+/**
+ * Main test command - orchestrates test discovery, execution, and reporting
+ */
+
+import { resolve, join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import pc from 'picocolors';
+import type { SegmentsConfig } from '../core/index.js';
+import type {
+  TestConfig,
+  DiscoveryOptions,
+  RunnerOptions,
+  TestReporter,
+  TestRunResult,
+} from './types.js';
+import { discoverTests, getUniqueComponents, getUniqueTags } from './discovery.js';
+import { runTests } from './runner.js';
+import { createConsoleReporter } from './reporters/console.js';
+import { createJUnitReporter } from './reporters/junit.js';
+import { createJsonReporter } from './reporters/json.js';
+import { startWatchMode } from './watch.js';
+
+export interface TestCommandOptions {
+  // Discovery options
+  component?: string;
+  tags?: string;
+  grep?: string;
+  exclude?: string;
+
+  // Execution options
+  parallel?: number;
+  timeout?: number;
+  retries?: number;
+  bail?: boolean;
+  browser?: 'chromium' | 'firefox' | 'webkit';
+  headless?: boolean;
+
+  // Feature flags
+  a11y?: boolean;
+  visual?: boolean;
+  updateSnapshots?: boolean;
+  watch?: boolean;
+
+  // Output options
+  reporters?: string;
+  output?: string;
+
+  // Server options
+  serverUrl?: string;
+  port?: number;
+
+  // CI mode
+  ci?: boolean;
+}
+
+/**
+ * Default options
+ */
+const DEFAULT_OPTIONS = {
+  parallel: 4,
+  timeout: 30000,
+  retries: 0,
+  bail: false,
+  browser: 'chromium' as const,
+  headless: true,
+  a11y: false,
+  visual: false,
+  updateSnapshots: false,
+  watch: false,
+  reporters: 'console',
+  output: './test-results',
+  port: 6006,
+  ci: false,
+};
+
+/**
+ * Run the test command
+ */
+export async function runTestCommand(
+  config: SegmentsConfig,
+  configDir: string,
+  options: TestCommandOptions
+): Promise<number> {
+  // Merge with defaults
+  const opts = {
+    ...DEFAULT_OPTIONS,
+    ...options,
+  };
+
+  // Parse discovery options
+  const discoveryOptions: DiscoveryOptions = {
+    component: opts.component,
+    tags: opts.tags ? opts.tags.split(',').map((t) => t.trim()) : undefined,
+    grep: opts.grep,
+    exclude: opts.exclude,
+  };
+
+  // Parse runner options
+  const runnerOptions: RunnerOptions = {
+    parallel: opts.parallel,
+    timeout: opts.timeout,
+    retries: opts.retries,
+    bail: opts.bail,
+    a11y: opts.a11y,
+    visual: opts.visual,
+    updateSnapshots: opts.updateSnapshots,
+    outputDir: resolve(configDir, opts.output),
+    browser: opts.browser,
+    headless: opts.headless,
+    serverUrl: opts.serverUrl,
+    port: opts.port,
+  };
+
+  // In CI mode, adjust settings
+  if (opts.ci) {
+    runnerOptions.headless = true;
+  }
+
+  // Discover tests
+  console.log(pc.cyan('\nDiscovering tests...'));
+  const testCases = await discoverTests(config, configDir, discoveryOptions);
+
+  if (testCases.length === 0) {
+    console.log(pc.yellow('No tests with play functions found'));
+
+    // Show helpful info about what was searched
+    const components = getUniqueComponents(testCases);
+    const tags = getUniqueTags(testCases);
+
+    if (discoveryOptions.component) {
+      console.log(pc.dim(`  Filtered by component: ${discoveryOptions.component}`));
+    }
+    if (discoveryOptions.tags?.length) {
+      console.log(pc.dim(`  Filtered by tags: ${discoveryOptions.tags.join(', ')}`));
+    }
+    if (discoveryOptions.grep) {
+      console.log(pc.dim(`  Filtered by pattern: ${discoveryOptions.grep}`));
+    }
+
+    console.log();
+    console.log(pc.dim('Add play functions to your segment variants to enable testing.'));
+    console.log();
+
+    return opts.ci ? 0 : 0; // Not a failure if no tests
+  }
+
+  console.log(pc.dim(`Found ${testCases.length} test(s)`));
+
+  // Create output directory
+  await mkdir(runnerOptions.outputDir, { recursive: true });
+
+  // Create reporters
+  const reporters = createReporters(opts.reporters, runnerOptions.outputDir, opts.ci);
+
+  // Watch mode
+  if (opts.watch && !opts.ci) {
+    await startWatchMode(config, configDir, runnerOptions, reporters);
+    return 0;
+  }
+
+  // Run tests
+  let result: TestRunResult;
+  try {
+    result = await runTests(testCases, runnerOptions, reporters);
+  } catch (error) {
+    console.error(pc.red('Error running tests:'), error);
+    return 1;
+  }
+
+  // Return exit code based on results
+  if (opts.ci && result.totalFailed > 0) {
+    return 1;
+  }
+
+  return result.totalFailed > 0 ? 1 : 0;
+}
+
+/**
+ * Create reporters based on configuration
+ */
+function createReporters(
+  reporterNames: string,
+  outputDir: string,
+  ci: boolean
+): TestReporter[] {
+  const reporters: TestReporter[] = [];
+  const names = reporterNames.split(',').map((n) => n.trim().toLowerCase());
+
+  for (const name of names) {
+    switch (name) {
+      case 'console':
+        reporters.push(
+          createConsoleReporter({
+            verbose: !ci,
+            showTiming: true,
+          })
+        );
+        break;
+
+      case 'junit':
+        reporters.push(
+          createJUnitReporter({
+            outputPath: join(outputDir, 'junit.xml'),
+            suiteName: 'Segments Tests',
+          })
+        );
+        break;
+
+      case 'json':
+        reporters.push(
+          createJsonReporter({
+            outputPath: join(outputDir, 'results.json'),
+            pretty: true,
+            includeSteps: true,
+            includeStacks: !ci,
+          })
+        );
+        break;
+
+      default:
+        console.warn(pc.yellow(`Unknown reporter: ${name}`));
+    }
+  }
+
+  // Always include console reporter if not explicitly specified
+  if (!names.includes('console') && reporters.length === 0) {
+    reporters.push(createConsoleReporter({ verbose: !ci }));
+  }
+
+  return reporters;
+}
+
+/**
+ * List available tests without running them
+ */
+export async function listTests(
+  config: SegmentsConfig,
+  configDir: string,
+  options: Pick<TestCommandOptions, 'component' | 'tags' | 'grep' | 'exclude'>
+): Promise<void> {
+  const discoveryOptions: DiscoveryOptions = {
+    component: options.component,
+    tags: options.tags ? options.tags.split(',').map((t) => t.trim()) : undefined,
+    grep: options.grep,
+    exclude: options.exclude,
+  };
+
+  const testCases = await discoverTests(config, configDir, discoveryOptions);
+
+  console.log();
+  console.log(pc.cyan(pc.bold('Available Tests')));
+  console.log();
+
+  if (testCases.length === 0) {
+    console.log(pc.yellow('No tests with play functions found'));
+    return;
+  }
+
+  // Group by component
+  const byComponent = new Map<string, typeof testCases>();
+  for (const test of testCases) {
+    const existing = byComponent.get(test.component) || [];
+    existing.push(test);
+    byComponent.set(test.component, existing);
+  }
+
+  for (const [component, tests] of byComponent) {
+    console.log(pc.bold(component));
+    for (const test of tests) {
+      const tags = test.tags.length > 0 ? pc.dim(` [${test.tags.join(', ')}]`) : '';
+      console.log(`  ${pc.green('›')} ${test.variant}${tags}`);
+    }
+    console.log();
+  }
+
+  console.log(pc.dim(`Total: ${testCases.length} test(s) in ${byComponent.size} component(s)`));
+  console.log();
+}
+
+// Re-export types
+export type { TestCase, TestResult, TestRunResult, TestSuite, TestReporter } from './types.js';

package/src/test/reporters/console.ts

@@ -0,0 +1,194 @@
+/**
+ * Console reporter - pretty terminal output
+ */
+
+import pc from 'picocolors';
+import type { TestCase, TestResult, TestRunResult, TestReporter } from '../types.js';
+
+export interface ConsoleReporterOptions {
+  /** Show verbose output including all steps */
+  verbose?: boolean;
+  /** Show timing for each test */
+  showTiming?: boolean;
+}
+
+/**
+ * Create a console reporter
+ */
+export function createConsoleReporter(options: ConsoleReporterOptions = {}): TestReporter {
+  const { verbose = false, showTiming = true } = options;
+
+  let startTime: number;
+  let testCount: number;
+  let currentIndex: number;
+
+  return {
+    onRunStart(count: number) {
+      testCount = count;
+      currentIndex = 0;
+      startTime = Date.now();
+
+      console.log();
+      console.log(pc.cyan(pc.bold('Segments Test Runner')));
+      console.log(pc.dim(`Running ${count} test${count === 1 ? '' : 's'}...`));
+      console.log();
+    },
+
+    onTestStart(testCase: TestCase) {
+      currentIndex++;
+      if (verbose) {
+        const progress = pc.dim(`[${currentIndex}/${testCount}]`);
+        console.log(`${progress} ${pc.dim('Running')} ${testCase.component} › ${testCase.variant}`);
+      }
+    },
+
+    onTestComplete(result: TestResult) {
+      const { testCase, status, duration, steps, error, accessibility } = result;
+      const timing = showTiming ? pc.dim(` (${formatDuration(duration)})`) : '';
+
+      const statusIcon = getStatusIcon(status);
+      const testName = `${testCase.component} › ${testCase.variant}`;
+
+      if (status === 'passed') {
+        console.log(`  ${statusIcon} ${testName}${timing}`);
+
+        // Show a11y results if present
+        if (accessibility && accessibility.violations.length > 0) {
+          console.log(
+            pc.yellow(`    ⚠ ${accessibility.violations.length} accessibility violation(s)`)
+          );
+        }
+      } else if (status === 'failed') {
+        console.log(`  ${statusIcon} ${pc.red(testName)}${timing}`);
+
+        // Show error message
+        if (error) {
+          console.log(pc.red(`    ${error.message}`));
+          if (verbose && error.stack) {
+            console.log(pc.dim(`    ${error.stack.split('\n').slice(1, 4).join('\n    ')}`));
+          }
+        }
+
+        // Show failed steps
+        if (verbose || steps.some((s) => s.status === 'failed')) {
+          for (const step of steps) {
+            if (step.status === 'failed') {
+              console.log(pc.red(`    ✗ ${step.name}`));
+              if (step.error) {
+                console.log(pc.red(`      ${step.error.message}`));
+              }
+            } else if (verbose && step.status === 'passed') {
+              console.log(pc.dim(`    ✓ ${step.name}`));
+            }
+          }
+        }
+
+        // Show retry info
+        if (result.retryAttempt) {
+          console.log(pc.dim(`    (failed after ${result.retryAttempt + 1} attempts)`));
+        }
+      } else if (status === 'skipped') {
+        console.log(`  ${statusIcon} ${pc.dim(testName)} ${pc.dim('(skipped)')}`);
+      }
+
+      // Show all steps in verbose mode
+      if (verbose && status === 'passed' && steps.length > 0) {
+        for (const step of steps) {
+          const stepTiming = showTiming ? pc.dim(` ${formatDuration(step.duration)}`) : '';
+          console.log(pc.dim(`    ✓ ${step.name}${stepTiming}`));
+        }
+      }
+    },
+
+    onRunComplete(result: TestRunResult) {
+      const { totalTests, totalPassed, totalFailed, totalSkipped, totalDuration, suites } = result;
+
+      console.log();
+      console.log(pc.dim('─'.repeat(50)));
+      console.log();
+
+      // Summary by suite
+      if (suites.length > 1) {
+        console.log(pc.bold('Test Suites:'));
+        for (const suite of suites) {
+          const statusIcon = suite.failed > 0 ? pc.red('✗') : pc.green('✓');
+          const failedText = suite.failed > 0 ? pc.red(`${suite.failed} failed, `) : '';
+          const passedText = suite.passed > 0 ? pc.green(`${suite.passed} passed`) : '';
+          const skippedText = suite.skipped > 0 ? pc.dim(`, ${suite.skipped} skipped`) : '';
+          console.log(`  ${statusIcon} ${suite.name} (${failedText}${passedText}${skippedText})`);
+        }
+        console.log();
+      }
+
+      // Overall summary
+      console.log(pc.bold('Tests:'));
+      const parts: string[] = [];
+
+      if (totalFailed > 0) {
+        parts.push(pc.red(`${totalFailed} failed`));
+      }
+      if (totalPassed > 0) {
+        parts.push(pc.green(`${totalPassed} passed`));
+      }
+      if (totalSkipped > 0) {
+        parts.push(pc.dim(`${totalSkipped} skipped`));
+      }
+      parts.push(`${totalTests} total`);
+
+      console.log(`  ${parts.join(', ')}`);
+      console.log(`  ${pc.dim('Time:')} ${formatDuration(totalDuration)}`);
+
+      // A11y summary if applicable
+      if (result.totalA11yViolations !== undefined) {
+        if (result.totalA11yViolations > 0) {
+          console.log(
+            `  ${pc.yellow('Accessibility:')} ${result.totalA11yViolations} violation(s)`
+          );
+        } else {
+          console.log(`  ${pc.green('Accessibility:')} All checks passed`);
+        }
+      }
+
+      console.log();
+
+      // Final status
+      if (totalFailed > 0) {
+        console.log(pc.red(pc.bold('Test run failed')));
+      } else {
+        console.log(pc.green(pc.bold('Test run passed')));
+      }
+      console.log();
+    },
+  };
+}
+
+/**
+ * Get status icon with color
+ */
+function getStatusIcon(status: TestResult['status']): string {
+  switch (status) {
+    case 'passed':
+      return pc.green('✓');
+    case 'failed':
+      return pc.red('✗');
+    case 'skipped':
+      return pc.dim('○');
+    default:
+      return ' ';
+  }
+}
+
+/**
+ * Format duration in human-readable form
+ */
+function formatDuration(ms: number): string {
+  if (ms < 1000) {
+    return `${Math.round(ms)}ms`;
+  }
+  if (ms < 60000) {
+    return `${(ms / 1000).toFixed(2)}s`;
+  }
+  const minutes = Math.floor(ms / 60000);
+  const seconds = ((ms % 60000) / 1000).toFixed(1);
+  return `${minutes}m ${seconds}s`;
+}