@sun-asterisk/sungen 1.0.18 → 1.0.19

package/src/cli/commands/live-scan-command.ts

@@ -0,0 +1,79 @@
+/**
+ * Live Scan CLI Command
+ * Launches a browser, replays Gherkin steps, and produces .live-scan.yaml matrix files.
+ * Auto-detects baseURL from playwright.config.ts.
+ */
+
+import { Command } from 'commander';
+import { RuntimeConfig } from '../../config/config-schema';
+import { LiveScanner } from '../../core/live-scanner';
+
+export function createLiveScanCommand(config: RuntimeConfig): Command {
+  const cmd = new Command('live-scan');
+
+  cmd
+    .description('Scan a live site to discover real selectors for Gherkin element references')
+    .requiredOption('-s, --screen <name>', 'Screen name to scan')
+    .option('--url <baseUrl>', 'Override base URL (default: read from playwright.config.ts)')
+    .option('--headed', 'Launch browser in headed (visible) mode', false)
+    .option('--auth-dir <path>', 'Directory containing auth storage state files', 'specs/.auth')
+    .action(async (options) => {
+      try {
+        console.log('\n🔍 Sungen Live Scanner\n');
+        console.log(`📍 Screen: ${options.screen}`);
+        console.log(`🖥️  Mode: ${options.headed ? 'headed' : 'headless'}`);
+
+        const scanner = new LiveScanner({
+          baseUrl: options.url,  // undefined = auto-detect from playwright.config.ts
+          screenName: options.screen,
+          screensDir: 'qa/screens',
+          headed: options.headed,
+          authDir: options.authDir,
+        });
+
+        const results = await scanner.scan();
+
+        // Print final summary
+        console.log('\n📊 SCAN SUMMARY\n');
+
+        let totalElements = 0;
+        let totalResolved = 0;
+        let totalWarnings = 0;
+        let totalUnresolved = 0;
+
+        for (const result of results) {
+          for (const scenario of Object.values(result.scenarios)) {
+            for (const element of Object.values(scenario.elements)) {
+              totalElements++;
+              if (element.matchMethod === 'unresolved') {
+                totalUnresolved++;
+              } else {
+                totalResolved++;
+                if (element.warning) totalWarnings++;
+              }
+            }
+          }
+        }
+
+        console.log(`Total Elements:  ${totalElements}`);
+        console.log(`Resolved:        ${totalResolved}`);
+        console.log(`Warnings:        ${totalWarnings}`);
+        console.log(`Unresolved:      ${totalUnresolved}`);
+
+        if (totalUnresolved > 0) {
+          console.log(`\n⚠️  ${totalUnresolved} element(s) could not be found on the live site`);
+        }
+
+        if (totalResolved > 0) {
+          console.log(`\n✅ Live scan complete. Run 'sungen map --screen ${options.screen}' to generate selectors.`);
+        }
+
+        console.log('');
+      } catch (error: any) {
+        console.error('\n❌ Live scan failed:', error.message);
+        process.exit(1);
+      }
+    });
+
+  return cmd;
+}

package/src/cli/index.ts

@@ -166,13 +166,29 @@ async function main() {
         // Process screen folder: qa/screens/<screen>/features/
         const screensDir = options.output || 'qa/screens';
         const forceOverwrite = cliOptions.force || false;
-        
+
+        // Run live-scan first if --scan-live flag is set
+        if (options.scanLive) {
+          const { LiveScanner } = require('../core/live-scanner');
+          console.log('🔍 Running live-scan before mapping...\n');
+
+          const scanner = new LiveScanner({
+            screenName: options.screen,
+            screensDir,
+            headed: options.headed,
+            authDir: options.authDir,
+          });
+
+          await scanner.scan();
+          console.log('');
+        }
+
         if (forceOverwrite) {
           console.log(`Mapping screen: ${options.screen} (force: selectors will be overwritten)\n`);
         } else {
           console.log(`Mapping screen: ${options.screen}\n`);
         }
-        
+
         const results = generator.processScreen(options.screen, screensDir, forceOverwrite);
         
         for (const result of results) {
@@ -326,6 +342,23 @@ async function main() {
     }
   });
 
+  const liveScanCmd = adapter.addLiveScanCommand(program);
+  liveScanCmd.action(async (options) => {
+    try {
+      const cliOptions = {
+        ...program.opts(),
+        ...options
+      };
+      const config = new ConfigLoader().load(cliOptions);
+      const { createLiveScanCommand } = require('./commands/live-scan-command');
+
+      await createLiveScanCommand(config).parseAsync(['node', 'sungen', ...process.argv.slice(3)]);
+    } catch (error) {
+      console.error('❌ Live scan failed:', error);
+      process.exit(1);
+    }
+  });
+
   const addScreenCmd = adapter.addAddScreenCommand(program);
   addScreenCmd.action(async (options) => {
     try {

package/src/config/default.config.yaml

@@ -72,6 +72,12 @@ testGenerator:
   enableAIFallback: false  # Enable AI for unknown patterns (--ai-mapper flag)
   dictionaryPath: "qa/executor/playwright/dictionary.yaml"
 
+# Live scan configuration
+liveScan:
+  baseUrl: ""  # Base URL for live scanning (e.g., "http://localhost:3000")
+  headed: false  # Launch browser in headed mode
+  authDir: "specs/.auth"  # Directory containing auth storage state files
+
 # Cache configuration
 cache:
   enabled: true

package/src/core/live-scanner/config-reader.ts

@@ -0,0 +1,57 @@
+/**
+ * Config Reader
+ * Extracts baseURL from playwright.config.ts in the project root.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Read baseURL from playwright.config.ts by searching for the baseURL property.
+ * Searches from the given directory upward to find playwright.config.ts.
+ */
+export function readBaseUrlFromPlaywrightConfig(startDir: string = process.cwd()): string | null {
+  const configPath = findPlaywrightConfig(startDir);
+  if (!configPath) return null;
+
+  const content = fs.readFileSync(configPath, 'utf-8');
+  return extractBaseUrl(content);
+}
+
+function findPlaywrightConfig(startDir: string): string | null {
+  const names = ['playwright.config.ts', 'playwright.config.js', 'playwright.config.mjs'];
+  let dir = path.resolve(startDir);
+
+  // Search up to 5 levels up
+  for (let i = 0; i < 5; i++) {
+    for (const name of names) {
+      const configPath = path.join(dir, name);
+      if (fs.existsSync(configPath)) {
+        return configPath;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+function extractBaseUrl(content: string): string | null {
+  // Match baseURL: 'value' or baseURL: "value" in the config
+  // Handles both direct assignment and inside use: { ... }
+  const patterns = [
+    /baseURL\s*:\s*['"]([^'"]+)['"]/,
+    /baseUrl\s*:\s*['"]([^'"]+)['"]/,
+  ];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match) {
+      return match[1];
+    }
+  }
+
+  return null;
+}

package/src/core/live-scanner/element-finder.ts

@@ -0,0 +1,333 @@
+/**
+ * Element Finder
+ *
+ * Searches for elements using Playwright's own locator strategies in priority order:
+ *   ① getByTestId    — data-testid attribute
+ *   ② getByRole      — ARIA role + accessible name (exact match, then fallback roles)
+ *   ③ getByLabel     — associated <label> text
+ *   ④ getByPlaceholder — placeholder attribute
+ *   ⑤ getByText      — visible text content
+ *
+ * The result records WHICH Playwright strategy found the element,
+ * so `map` can generate the correct locator code.
+ */
+
+import type { Page, Locator } from 'playwright';
+import { getRoleFallbacks, isTextOnlyType } from './role-fallback';
+import { LiveElement, MatchMethod, SelectorType, ElementContext } from './types';
+
+interface FindResult {
+  locator: Locator;
+  selectorType: SelectorType;
+  selectorValue: string;
+  role: string;
+  matchMethod: MatchMethod;
+  warning: string | null;
+}
+
+/**
+ * Find an element on the page using cascading Playwright locator strategies.
+ */
+export async function findElement(
+  page: Page,
+  gherkinRef: string,
+  gherkinType: string,
+  nth: number = 0
+): Promise<LiveElement> {
+  const namePattern = new RegExp(escapeRegex(gherkinRef), 'i');
+
+  const result = await cascadingSearch(page, gherkinRef, gherkinType, namePattern, nth);
+
+  if (!result) {
+    return buildUnresolvedElement(gherkinRef, gherkinType);
+  }
+
+  const attrs = await extractElementAttributes(result.locator);
+
+  // Use Playwright's computed accessible name (includes alt text, aria-label, etc.)
+  // This matches what getByRole/getByText actually see, unlike textContent
+  let playwrightName = '';
+  try {
+    playwrightName = await result.locator.evaluate((el) => {
+      // computedRole/computedLabel not available in all browsers, fallback to aria
+      return (el as any).computedName
+        || el.getAttribute('aria-label')
+        || el.textContent?.trim()?.substring(0, 100)
+        || '';
+    });
+    // Better approach: use Playwright's accessibility snapshot
+    const ariaSnapshot = await result.locator.ariaSnapshot();
+    // Parse accessible name from snapshot (format: "- role \"name\"" or "- role \"name\": ...")
+    const nameMatch = ariaSnapshot?.match(/"([^"]+)"/);
+    if (nameMatch) {
+      playwrightName = nameMatch[1];
+    }
+  } catch {
+    playwrightName = attrs.accessibleName || gherkinRef;
+  }
+
+  const actualName = playwrightName || attrs.accessibleName || gherkinRef;
+  const isExactMatch = actualName.toLowerCase().trim() === gherkinRef.toLowerCase().trim();
+
+  return {
+    gherkinRef,
+    gherkinType,
+    selectorType: result.selectorType,
+    selectorValue: result.selectorValue,
+    role: result.role,
+    name: actualName,
+    testid: attrs.testid,
+    tag: attrs.tag,
+    placeholder: attrs.placeholder,
+    label: attrs.label,
+    context: 'page',
+    matchMethod: result.matchMethod,
+    exact: isExactMatch,
+    warning: result.warning,
+  };
+}
+
+async function cascadingSearch(
+  page: Page,
+  gherkinRef: string,
+  gherkinType: string,
+  namePattern: RegExp,
+  nth: number
+): Promise<FindResult | null> {
+  // ① getByTestId
+  const testidResult = await tryTestId(page, gherkinRef, nth);
+  if (testidResult) return testidResult;
+
+  // For text-only types (text, message, error), skip role and go to text
+  if (!isTextOnlyType(gherkinType)) {
+    // ② getByRole — exact role match
+    const roles = getRoleFallbacks(gherkinType);
+    if (roles.length > 0) {
+      const exactResult = await tryRole(page, roles[0], namePattern, nth);
+      if (exactResult) {
+        return {
+          ...exactResult,
+          matchMethod: 'exact_role',
+          warning: null,
+        };
+      }
+
+      // ③ getByRole — fallback roles
+      for (let i = 1; i < roles.length; i++) {
+        const fallbackResult = await tryRole(page, roles[i], namePattern, nth);
+        if (fallbackResult) {
+          return {
+            ...fallbackResult,
+            matchMethod: 'role_fallback',
+            warning: `Gherkin says '${gherkinType}' but found role '${roles[i]}'`,
+          };
+        }
+      }
+    }
+
+    // ④ getByLabel — for form elements
+    const labelResult = await tryLabel(page, namePattern, nth);
+    if (labelResult) return labelResult;
+
+    // ⑤ getByPlaceholder — for input fields
+    const placeholderResult = await tryPlaceholder(page, namePattern, nth);
+    if (placeholderResult) return placeholderResult;
+  }
+
+  // ⑥ getByText — final fallback
+  const textResult = await tryText(page, namePattern, nth);
+  if (textResult) return textResult;
+
+  return null;
+}
+
+// ① getByTestId
+async function tryTestId(page: Page, ref: string, nth: number): Promise<FindResult | null> {
+  const normalized = ref.toLowerCase().replace(/[\s_-]+/g, '-');
+  const patterns = [normalized, ref.toLowerCase().replace(/\s+/g, '')];
+
+  for (const pattern of patterns) {
+    try {
+      const locator = page.locator(`[data-testid*="${pattern}" i]`);
+      const count = await locator.count();
+      if (count > 0) {
+        const target = nth > 0 ? locator.nth(nth) : locator.first();
+        if (await target.isVisible({ timeout: 3000 })) {
+          const testid = await target.getAttribute('data-testid');
+          return {
+            locator: target,
+            selectorType: 'testid',
+            selectorValue: testid || pattern,
+            role: '',
+            matchMethod: 'testid',
+            warning: null,
+          };
+        }
+      }
+    } catch {
+      // Continue
+    }
+  }
+  return null;
+}
+
+// ② ③ getByRole
+async function tryRole(
+  page: Page,
+  role: string,
+  namePattern: RegExp,
+  nth: number
+): Promise<FindResult | null> {
+  try {
+    const locator = page.getByRole(role as any, { name: namePattern });
+    const count = await locator.count();
+    if (count > 0) {
+      const target = nth > 0 ? locator.nth(nth) : locator.first();
+      if (await target.isVisible({ timeout: 3000 })) {
+        // Get the actual accessible name for the selector
+        const accessibleName = await target.evaluate((el) =>
+          el.getAttribute('aria-label') || el.textContent?.trim()?.substring(0, 100) || ''
+        );
+        return {
+          locator: target,
+          selectorType: 'role',
+          selectorValue: role,
+          role: role,
+          matchMethod: 'exact_role',
+          warning: null,
+        };
+      }
+    }
+  } catch {
+    // Role not found
+  }
+  return null;
+}
+
+// ④ getByLabel
+async function tryLabel(page: Page, namePattern: RegExp, nth: number): Promise<FindResult | null> {
+  try {
+    const locator = page.getByLabel(namePattern);
+    const count = await locator.count();
+    if (count > 0) {
+      const target = nth > 0 ? locator.nth(nth) : locator.first();
+      if (await target.isVisible({ timeout: 3000 })) {
+        return {
+          locator: target,
+          selectorType: 'label',
+          selectorValue: '',  // Will be filled from attrs
+          role: '',
+          matchMethod: 'label',
+          warning: null,
+        };
+      }
+    }
+  } catch {
+    // Label not found
+  }
+  return null;
+}
+
+// ⑤ getByPlaceholder
+async function tryPlaceholder(page: Page, namePattern: RegExp, nth: number): Promise<FindResult | null> {
+  try {
+    const locator = page.getByPlaceholder(namePattern);
+    const count = await locator.count();
+    if (count > 0) {
+      const target = nth > 0 ? locator.nth(nth) : locator.first();
+      if (await target.isVisible({ timeout: 3000 })) {
+        const placeholder = await target.getAttribute('placeholder');
+        return {
+          locator: target,
+          selectorType: 'placeholder',
+          selectorValue: placeholder || '',
+          role: '',
+          matchMethod: 'placeholder',
+          warning: null,
+        };
+      }
+    }
+  } catch {
+    // Placeholder not found
+  }
+  return null;
+}
+
+// ⑥ getByText
+async function tryText(page: Page, namePattern: RegExp, nth: number): Promise<FindResult | null> {
+  try {
+    const locator = page.getByText(namePattern);
+    const count = await locator.count();
+    if (count > 0) {
+      const target = nth > 0 ? locator.nth(nth) : locator.first();
+      if (await target.isVisible({ timeout: 3000 })) {
+        return {
+          locator: target,
+          selectorType: 'text',
+          selectorValue: '',  // Will be filled from attrs
+          role: '',
+          matchMethod: 'text_only',
+          warning: null,
+        };
+      }
+    }
+  } catch {
+    // Text not found
+  }
+  return null;
+}
+
+async function extractElementAttributes(locator: Locator): Promise<{
+  testid: string | null;
+  tag: string;
+  accessibleName: string;
+  placeholder: string | null;
+  label: string | null;
+}> {
+  try {
+    return await locator.evaluate((el) => {
+      // Find associated label
+      let label: string | null = null;
+      if (el.id) {
+        const labelEl = el.ownerDocument.querySelector(`label[for="${el.id}"]`);
+        if (labelEl) label = labelEl.textContent?.trim() || null;
+      }
+      if (!label && el.closest('label')) {
+        label = el.closest('label')?.textContent?.trim() || null;
+      }
+
+      return {
+        testid: el.getAttribute('data-testid'),
+        tag: el.tagName.toLowerCase(),
+        accessibleName: el.getAttribute('aria-label') || el.textContent?.trim()?.substring(0, 100) || '',
+        placeholder: el.getAttribute('placeholder'),
+        label,
+      };
+    });
+  } catch {
+    return { testid: null, tag: 'unknown', accessibleName: '', placeholder: null, label: null };
+  }
+}
+
+function buildUnresolvedElement(gherkinRef: string, gherkinType: string): LiveElement {
+  return {
+    gherkinRef,
+    gherkinType,
+    selectorType: '',
+    selectorValue: '',
+    role: '',
+    name: gherkinRef,
+    testid: null,
+    tag: '',
+    placeholder: null,
+    label: null,
+    context: 'page',
+    matchMethod: 'unresolved',
+    exact: false,
+    warning: 'Element not found on page',
+  };
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/core/live-scanner/index.ts

@@ -0,0 +1,7 @@
+export { LiveScanner } from './scanner';
+export { findElement } from './element-finder';
+export { getRoleFallbacks, isTextOnlyType } from './role-fallback';
+export { writeMatrix } from './matrix-writer';
+export { readMatrix, mergeMatrixElements } from './matrix-reader';
+export { readBaseUrlFromPlaywrightConfig } from './config-reader';
+export * from './types';

package/src/core/live-scanner/matrix-reader.ts

@@ -0,0 +1,70 @@
+/**
+ * Matrix Reader
+ * Loads and parses a .live-scan.yaml file for consumption by the map command.
+ * Merges elements across scenarios (first match wins).
+ */
+
+import * as fs from 'fs';
+import * as yaml from 'yaml';
+import { LiveElement, LiveScanResult } from './types';
+
+/**
+ * Read a .live-scan.yaml file and return the parsed result.
+ * Returns null if file doesn't exist.
+ */
+export function readMatrix(filePath: string): LiveScanResult | null {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const parsed = yaml.parse(content);
+
+  if (!parsed || !parsed.scenarios) {
+    return null;
+  }
+
+  return parsed as LiveScanResult;
+}
+
+/**
+ * Merge all elements across scenarios into a flat map.
+ * First successful (non-unresolved) match wins for duplicate keys.
+ */
+export function mergeMatrixElements(result: LiveScanResult): Record<string, LiveElement> {
+  const merged: Record<string, LiveElement> = {};
+
+  for (const scenario of Object.values(result.scenarios)) {
+    const elements = (scenario as any).elements;
+    if (!elements) continue;
+
+    for (const [key, raw] of Object.entries(elements)) {
+      const el = raw as any;
+
+      // Convert from YAML snake_case to interface camelCase
+      const element: LiveElement = {
+        gherkinRef: el.name || key,
+        gherkinType: el.gherkin_type || '',
+        selectorType: el.selector_type || '',
+        selectorValue: el.selector_value || '',
+        role: el.role || '',
+        name: el.name || '',
+        testid: el.testid || null,
+        tag: el.tag || '',
+        placeholder: el.placeholder || null,
+        label: el.label || null,
+        context: (el.context as any) || 'page',
+        matchMethod: (el.match_method as any) || 'unresolved',
+        exact: el.exact === true,
+        warning: el.warning || null,
+      };
+
+      // First non-unresolved match wins
+      if (!merged[key] || (merged[key].matchMethod === 'unresolved' && element.matchMethod !== 'unresolved')) {
+        merged[key] = element;
+      }
+    }
+  }
+
+  return merged;
+}

package/src/core/live-scanner/matrix-writer.ts

@@ -0,0 +1,66 @@
+/**
+ * Matrix Writer
+ * Writes LiveScanResult to a .live-scan.yaml file.
+ */
+
+import * as fs from 'fs';
+import * as yaml from 'yaml';
+import { LiveScanResult } from './types';
+
+export function writeMatrix(result: LiveScanResult, outputPath: string): void {
+  const output: any = {
+    screen: result.screen,
+    baseUrl: result.baseUrl,
+    scannedAt: result.scannedAt,
+    scenarios: {},
+  };
+
+  for (const [scenarioKey, scenario] of Object.entries(result.scenarios)) {
+    const scenarioData: any = {
+      auth: scenario.auth,
+      path: scenario.path,
+    };
+
+    if (scenario.extends) {
+      scenarioData.extends = scenario.extends;
+    }
+
+    scenarioData.elements = {};
+
+    for (const [elementKey, element] of Object.entries(scenario.elements)) {
+      scenarioData.elements[elementKey] = {
+        gherkin_type: element.gherkinType,
+        selector_type: element.selectorType,
+        selector_value: element.selectorValue,
+        role: element.role,
+        name: element.name,
+        testid: element.testid,
+        tag: element.tag,
+        placeholder: element.placeholder,
+        label: element.label,
+        context: element.context,
+        match_method: element.matchMethod,
+        exact: element.exact,
+        warning: element.warning,
+      };
+    }
+
+    output.scenarios[scenarioKey] = scenarioData;
+  }
+
+  const header = [
+    `# Auto-generated by sungen live-scan`,
+    `# Screen: ${result.screen} | Base URL: ${result.baseUrl}`,
+    `# Scanned: ${result.scannedAt}`,
+    `# Do not edit manually — re-run 'sungen live-scan' to regenerate`,
+    '',
+  ].join('\n');
+
+  const yamlStr = yaml.stringify(output, {
+    lineWidth: 120,
+    defaultStringType: 'QUOTE_DOUBLE',
+    nullStr: 'null',
+  });
+
+  fs.writeFileSync(outputPath, header + yamlStr, 'utf-8');
+}