@sun-asterisk/sungen 1.0.24 → 2.0.0

package/src/core/live-scanner/step-replayer.ts

@@ -1,503 +0,0 @@
-/**
- * Step Replayer
- * Replays Gherkin steps on a live Playwright page to reveal dynamic elements.
- * Takes a snapshot and finds elements after each action.
- */
-
-import type { Page } from 'playwright';
-import { findElement } from './element-finder';
-import { LiveElement, ElementContext } from './types';
-import { SelectorResolver } from '../../generators/test-generator/utils/selector-resolver';
-
-interface ParsedStepInfo {
-  keyword: string;
-  text: string;
-  selectorRef?: string;
-  dataRef?: string;
-  elementType?: string;
-  nth?: number;
-}
-
-interface ReplayResult {
-  elements: Record<string, LiveElement>;
-  errors: string[];
-}
-
-/**
- * Resolve a {{dataRef}} path against test-data object.
- * Supports dot-notation: "email.valid" → testData.email.valid
- */
-function resolveDataRef(testData: Record<string, any>, dataRef: string): string {
-  const parts = dataRef.replace(/[{}]/g, '').split('.');
-  let value: any = testData;
-  for (const part of parts) {
-    value = value?.[part];
-  }
-  return typeof value === 'string' ? value : String(value ?? '');
-}
-
-/**
- * Replay a sequence of Gherkin steps on a Playwright page,
- * finding and interacting with elements along the way.
- */
-export async function replaySteps(
-  page: Page,
-  steps: ParsedStepInfo[],
-  featurePath: string,
-  baseUrl: string,
-  existingElements?: Record<string, LiveElement>,
-  testData?: Record<string, any> | null
-): Promise<ReplayResult> {
-  const elements: Record<string, LiveElement> = {};
-  const errors: string[] = [];
-  let currentContext: ElementContext = 'page';
-
-  // Pre-scan: detect which base keys have multiple normalized element types
-  // so we can append --type suffix (matching scaffold generator behavior)
-  // Uses normalizeElementType to match scaffold generator's extractTargetType mapping
-  // e.g. modal/dialog both normalize to 'dialog', so they won't create a false conflict
-  const typesPerKey = new Map<string, Set<string>>();
-  for (const step of steps) {
-    if (!step.selectorRef) continue;
-    const baseKey = generateElementKey(step.selectorRef, step.elementType, step.nth);
-    const action = detectAction(step.text);
-    const normalizedType = normalizeElementType(step.elementType || 'button', action);
-    if (!typesPerKey.has(baseKey)) {
-      typesPerKey.set(baseKey, new Set());
-    }
-    typesPerKey.get(baseKey)!.add(normalizedType);
-  }
-  const conflictKeys = new Set<string>();
-  for (const [key, types] of typesPerKey) {
-    if (types.size > 1) conflictKeys.add(key);
-  }
-
-  for (const step of steps) {
-    try {
-      const action = detectAction(step.text);
-
-      // Handle navigation (Given User is on [x] page)
-      if (action === 'navigate') {
-        await page.goto(baseUrl + featurePath, { waitUntil: 'networkidle', timeout: 15000 });
-        await settle(page);
-        if (step.selectorRef) {
-          const baseKey = generateElementKey(step.selectorRef, step.elementType, step.nth);
-          const normalizedType = normalizeElementType(step.elementType || 'page', action);
-          const key = conflictKeys.has(baseKey) ? `${baseKey}--${normalizedType}` : baseKey;
-          // Record the page element but don't search for it on the DOM
-          elements[key] = {
-            gherkinRef: step.selectorRef,
-            gherkinType: step.elementType || 'page',
-            selectorType: '',
-            selectorValue: featurePath,
-            role: '',
-            name: step.selectorRef,
-            testid: null,
-            tag: '',
-            contenteditable: false,
-            placeholder: null,
-            label: null,
-            context: 'page',
-            matchMethod: 'exact_role',
-            exact: false,
-            warning: null,
-          };
-        }
-        continue;
-      }
-
-      // Skip steps without element references
-      if (!step.selectorRef) continue;
-
-      const baseKey = generateElementKey(step.selectorRef, step.elementType, step.nth);
-      const elementType = step.elementType || 'button';
-      const normalizedType = normalizeElementType(elementType, action);
-      const key = conflictKeys.has(baseKey) ? `${baseKey}--${normalizedType}` : baseKey;
-      const nth = step.nth || 0;
-
-      // Skip column-type elements — they use header text matching, no DOM lookup needed
-      if (normalizedType === 'column') {
-        console.log(`      ⏭️  [${step.selectorRef}] column → skipped (table header match)`);
-        continue;
-      }
-
-      // Skip if element already resolved in existing scan (non-force mode)
-      if (existingElements && existingElements[key] && existingElements[key].matchMethod !== 'unresolved') {
-        elements[key] = existingElements[key];
-        (elements[key] as any).skipped = true;
-        console.log(`      ⏩ [${step.selectorRef}] ${elementType} → cached (${existingElements[key].selectorType})`);
-
-        // Still execute actions for cached elements to maintain page state
-        if (action === 'click') {
-          try {
-            await executeClick(page, step.selectorRef, elementType, nth);
-            await settle(page);
-            currentContext = await detectCurrentContext(page, currentContext, step.text);
-          } catch {
-            // Click failed for cached element, continue anyway
-          }
-        } else if (action === 'fill' && testData && step.dataRef) {
-          try {
-            const value = resolveDataRef(testData, step.dataRef);
-            if (value) {
-              await executeFill(page, step.selectorRef, elementType, nth, value);
-              await settle(page);
-            }
-          } catch {
-            // Fill failed for cached element, continue anyway
-          }
-        } else if (action === 'select' && testData && step.dataRef) {
-          try {
-            const value = resolveDataRef(testData, step.dataRef);
-            if (value) {
-              await executeSelect(page, step.selectorRef, elementType, nth, value);
-              await settle(page);
-            }
-          } catch {
-            // Select failed for cached element, continue anyway
-          }
-        }
-        continue;
-      }
-
-      // Find the element on the page, scoped to current context (dialog/page)
-      const element = await findElement(page, step.selectorRef, elementType, nth, currentContext);
-      element.context = currentContext;
-
-      // Record in matrix (first match wins for duplicate keys)
-      if (!elements[key]) {
-        elements[key] = element;
-      }
-
-      // Execute the action if element was found
-      if (element.matchMethod !== 'unresolved') {
-        if (action === 'click') {
-          await executeClick(page, step.selectorRef, elementType, nth);
-          await settle(page);
-          currentContext = await detectCurrentContext(page, currentContext, step.text);
-        } else if (action === 'fill') {
-          if (testData && step.dataRef) {
-            const value = resolveDataRef(testData, step.dataRef);
-            if (value) {
-              try {
-                await executeFill(page, step.selectorRef, elementType, nth, value);
-                await settle(page);
-              } catch (e: any) {
-                errors.push(`Step "${step.text}": fill failed — ${e.message}`);
-              }
-            }
-          }
-        } else if (action === 'select') {
-          if (testData && step.dataRef) {
-            const value = resolveDataRef(testData, step.dataRef);
-            if (value) {
-              try {
-                await executeSelect(page, step.selectorRef, elementType, nth, value);
-                await settle(page);
-              } catch (e: any) {
-                errors.push(`Step "${step.text}": select failed — ${e.message}`);
-              }
-            }
-          }
-        }
-        // Label-value detection: check if the data value appears in a sibling element
-        if (action === 'see' && normalizedType === 'text' && (elementType === 'label' || elementType === 'title' || elementType === 'caption') && testData && step.dataRef) {
-          const dataValue = resolveDataRef(testData, step.dataRef);
-          if (dataValue) {
-            try {
-              // Check if the parent container has both the label text and the data value
-              const hasLabelValue = await page.getByText(new RegExp(escapeRegex(element.gherkinRef) + '.*' + escapeRegex(dataValue))).first().isVisible({ timeout: 2000 });
-              if (hasLabelValue) {
-                element.matchMethod = 'label-value';
-                elements[key] = element;
-              }
-            } catch {
-              // Regex match failed, keep original matchMethod
-            }
-          }
-        }
-        // 'see' and 'wait' actions: just record, don't interact
-      } else {
-        // Try data-value fallback for click actions: use the resolved data value as element name
-        if (action === 'click' && testData && step.dataRef) {
-          const dataValue = resolveDataRef(testData, step.dataRef);
-          if (dataValue) {
-            // Brief wait for dynamic content (e.g. autocomplete dropdown after fill)
-            await page.waitForTimeout(1000);
-            const fallback = await findElement(page, dataValue, elementType, nth, currentContext);
-            if (fallback.matchMethod !== 'unresolved') {
-              // Preserve original gherkinRef; clear locator values since they come
-              // from test-data ({{dataRef}}) at runtime, not hardcoded from DOM.
-              // Store dataValue for logging in scanner.ts
-              fallback.gherkinRef = step.selectorRef;
-              (fallback as any).dataValue = dataValue;
-              fallback.name = '';
-              fallback.exact = false;
-              elements[key] = fallback;
-              try {
-                await executeClick(page, dataValue, elementType, nth);
-                await settle(page);
-                currentContext = await detectCurrentContext(page, currentContext, step.text);
-              } catch {
-                // Click failed, element still recorded
-              }
-              continue;
-            }
-          }
-        }
-        errors.push(`Step "${step.text}": element [${step.selectorRef}] not found`);
-        // Continue scanning remaining steps — record what we can even if some elements are missing
-      }
-    } catch (error: any) {
-      errors.push(`Step "${step.text}": ${error.message}`);
-      // On navigation or critical errors, stop replaying this scenario
-      if (error.message.includes('Navigation') || error.message.includes('net::')) {
-        break;
-      }
-    }
-  }
-
-  return { elements, errors };
-}
-
-async function executeClick(
-  page: Page,
-  ref: string,
-  elementType: string,
-  nth: number
-): Promise<void> {
-  const namePattern = new RegExp(escapeRegex(ref), 'i');
-
-  // Try role-based click first
-  const { getRoleFallbacks } = require('./role-fallback');
-  const roles = getRoleFallbacks(elementType);
-
-  for (const role of roles) {
-    try {
-      const locator = page.getByRole(role as any, { name: namePattern });
-      const target = nth > 0 ? locator.nth(nth) : locator.first();
-      if (await target.isVisible({ timeout: 3000 })) {
-        await target.click({ timeout: 5000 });
-        return;
-      }
-    } catch {
-      continue;
-    }
-  }
-
-  // Fallback to text click
-  try {
-    const locator = page.getByText(namePattern);
-    const target = nth > 0 ? locator.nth(nth) : locator.first();
-    await target.click({ timeout: 5000 });
-  } catch {
-    // Try testid as last resort
-    const normalized = ref.toLowerCase().replace(/[\s_-]+/g, '-');
-    await page.locator(`[data-testid*="${normalized}" i]`).first().click({ timeout: 5000 });
-  }
-}
-
-async function executeFill(
-  page: Page,
-  ref: string,
-  elementType: string,
-  nth: number,
-  value: string
-): Promise<void> {
-  const namePattern = new RegExp(escapeRegex(ref), 'i');
-
-  // Try placeholder first — most direct for input fields, avoids slow role attempts
-  try {
-    const locator = page.getByPlaceholder(namePattern);
-    const target = nth > 0 ? locator.nth(nth) : locator.first();
-    if (await target.isVisible({ timeout: 3000 })) {
-      await target.fill(value, { timeout: 5000 });
-      return;
-    }
-  } catch {
-    // continue
-  }
-
-  // Try label
-  try {
-    const locator = page.getByLabel(namePattern);
-    const target = nth > 0 ? locator.nth(nth) : locator.first();
-    if (await target.isVisible({ timeout: 3000 })) {
-      await target.fill(value, { timeout: 5000 });
-      return;
-    }
-  } catch {
-    // continue
-  }
-
-  // Try role-based fill (textbox, combobox, spinbutton)
-  const { getRoleFallbacks } = require('./role-fallback');
-  const roles = getRoleFallbacks(elementType);
-
-  for (const role of roles) {
-    try {
-      const locator = page.getByRole(role as any, { name: namePattern });
-      const target = nth > 0 ? locator.nth(nth) : locator.first();
-      if (await target.isVisible({ timeout: 3000 })) {
-        await target.fill(value, { timeout: 5000 });
-        return;
-      }
-    } catch {
-      continue;
-    }
-  }
-
-  // Try testid as last resort
-  const normalized = ref.toLowerCase().replace(/[\s_-]+/g, '-');
-  await page.locator(`[data-testid*="${normalized}" i]`).first().fill(value, { timeout: 5000 });
-}
-
-async function executeSelect(
-  page: Page,
-  ref: string,
-  elementType: string,
-  nth: number,
-  value: string
-): Promise<void> {
-  const namePattern = new RegExp(escapeRegex(ref), 'i');
-
-  // Try label first — most direct for select elements
-  try {
-    const locator = page.getByLabel(namePattern);
-    const target = nth > 0 ? locator.nth(nth) : locator.first();
-    if (await target.isVisible({ timeout: 3000 })) {
-      await target.selectOption(value, { timeout: 5000 });
-      return;
-    }
-  } catch {
-    // continue
-  }
-
-  // Try role-based select (combobox, listbox)
-  const { getRoleFallbacks } = require('./role-fallback');
-  const roles = getRoleFallbacks(elementType);
-
-  for (const role of roles) {
-    try {
-      const locator = page.getByRole(role as any, { name: namePattern });
-      const target = nth > 0 ? locator.nth(nth) : locator.first();
-      if (await target.isVisible({ timeout: 3000 })) {
-        await target.selectOption(value, { timeout: 5000 });
-        return;
-      }
-    } catch {
-      continue;
-    }
-  }
-
-  // Try testid as last resort
-  const normalized = ref.toLowerCase().replace(/[\s_-]+/g, '-');
-  await page.locator(`[data-testid*="${normalized}" i]`).first().selectOption(value, { timeout: 5000 });
-}
-
-function detectAction(text: string): string {
-  const lower = text.toLowerCase();
-  if (/\b(is on|navigate|go to|visit|open)\b/.test(lower) && /\bpage\b/.test(lower)) return 'navigate';
-  if (/\b(click|press|tap|submit)\b/.test(lower)) return 'click';
-  if (/\b(fill|enter|type|input)\b/.test(lower)) return 'fill';
-  if (/\b(see|verify|check|expect|visible|displayed)\b/.test(lower)) return 'see';
-  if (/\b(select|choose|pick)\b/.test(lower)) return 'select';
-  if (/\b(wait)\b/.test(lower)) return 'wait';
-  return 'see';
-}
-
-async function detectCurrentContext(
-  page: Page,
-  previous: ElementContext,
-  stepText: string
-): Promise<ElementContext> {
-  const lower = stepText.toLowerCase();
-
-  // Check if we opened a dialog/modal
-  if (/\b(dialog|modal|panel)\b/.test(lower)) {
-    return 'dialog';
-  }
-
-  // Check if a dialog is now visible on the page
-  try {
-    const dialogLocator = page.getByRole('dialog');
-    if (await dialogLocator.count() > 0) {
-      return 'dialog';
-    }
-  } catch {
-    // ignore
-  }
-
-  // Check for menu
-  if (/\b(menu|dropdown)\b/.test(lower)) {
-    return 'menu';
-  }
-
-  try {
-    const menuLocator = page.getByRole('menu');
-    if (await menuLocator.count() > 0) {
-      return 'menu';
-    }
-  } catch {
-    // ignore
-  }
-
-  return previous;
-}
-
-async function settle(page: Page): Promise<void> {
-  try {
-    await page.waitForLoadState('networkidle', { timeout: 5000 });
-  } catch {
-    // Timeout is acceptable — page may have long-polling connections
-  }
-  // Small extra wait for animations/transitions
-  await page.waitForTimeout(300);
-}
-
-function generateElementKey(ref: string, elementType?: string, nth?: number): string {
-  // Use the same key generation as the scaffold generator
-  // so live-scan keys match scaffold keys in the map command.
-  // Append --N suffix for nth > 0, consistent with scaffold generator format.
-  const baseKey = SelectorResolver.generateKey(ref);
-  return nth && nth > 0 ? `${baseKey}--${nth}` : baseKey;
-}
-
-/**
- * Normalize element type to match scaffold generator's extractTargetType() mapping.
- * e.g. modal→dialog, img/icon/logo→img, input→field, select→dropdown, etc.
- */
-function normalizeElementType(elementType: string, action: string): string {
-  const t = elementType.toLowerCase();
-  if (t === 'page') return 'page';
-  if (t === 'link') return 'link';
-  if (t === 'button') return 'button';
-  if (t === 'radio') return 'radio';
-  if (t === 'dropdown' || t === 'select') return 'dropdown';
-  if (t === 'checkbox') return 'checkbox';
-  if (t === 'field' || t === 'input') return 'field';
-  if (t === 'textbox') return 'textbox';
-  if (t === 'textarea') return 'textarea';
-  if (t === 'text') return 'text';
-  if (t === 'label') return 'label';
-  if (t === 'uploader') return 'uploader';
-  if (t === 'element') return 'element';
-  if (t === 'column' || t === 'columnheader') return 'column';
-  if (t === 'logo' || t === 'image' || t === 'img' || t === 'icon') return 'img';
-  if (t === 'option' || t === 'item' || t === 'listitem') return 'option';
-  if (t === 'dialog' || t === 'modal') return 'dialog';
-  if (t === 'heading' || t === 'header') return 'heading';
-  if (t === 'title' || t === 'caption' || t === 'message') return 'text';
-  // Default based on action (matches scaffold generator)
-  switch (action) {
-    case 'click': return 'text';
-    case 'fill': return 'field';
-    case 'see': return 'text';
-    case 'select': return 'dropdown';
-    default: return 'element';
-  }
-}
-
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

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

@@ -1,58 +0,0 @@
-/**
- * Live Scanner Types
- * Defines the data structures for live DOM scanning and matrix file output.
- *
- * Selector types map directly to Playwright locator strategies:
- *   testid      → page.getByTestId(value)
- *   role        → page.getByRole(value, { name })
- *   label       → page.getByLabel(value)
- *   placeholder → page.getByPlaceholder(value)
- *   text        → page.getByText(value)
- */
-
-export type MatchMethod = 'testid' | 'exact_role' | 'role_fallback' | 'label' | 'placeholder' | 'text_only' | 'contenteditable' | 'label-value' | 'unresolved';
-
-export type SelectorType = 'testid' | 'role' | 'label' | 'placeholder' | 'text' | 'locator';
-
-export type ElementContext = 'page' | 'dialog' | 'menu' | 'modal' | 'popup';
-
-export interface LiveElement {
-  gherkinRef: string;
-  gherkinType: string;
-  selectorType: SelectorType | '';
-  selectorValue: string;
-  role: string;
-  name: string;
-  testid: string | null;
-  tag: string;
-  contenteditable: boolean;
-  placeholder: string | null;
-  label: string | null;
-  context: ElementContext;
-  matchMethod: MatchMethod;
-  exact: boolean;
-  warning: string | null;
-}
-
-export interface LiveScanScenario {
-  auth: string | null;
-  extends: string | null;
-  path: string;
-  elements: Record<string, LiveElement>;
-}
-
-export interface LiveScanResult {
-  screen: string;
-  baseUrl: string;
-  scannedAt: string;
-  scenarios: Record<string, LiveScanScenario>;
-}
-
-export interface LiveScanOptions {
-  baseUrl?: string;
-  screenName: string;
-  screensDir: string;
-  headed?: boolean;
-  authDir?: string;
-  force?: boolean;
-}

package/src/core/selector-base/annotation-handler.ts

@@ -1,127 +0,0 @@
-/**
- * Annotation Handler
- * Handles Gherkin annotations: selector IDs, data refs, ignore, etc.
- */
-
-import { RuntimeConfig } from '../../config/config-schema';
-import { ParsedScenario, ParsedStep } from './gherkin-parser';
-
-export interface ExtractedAnnotation {
-  id: string;
-  type: 'selector' | 'data' | 'ignore';
-  value?: string;
-}
-
-export class AnnotationHandler {
-  private config: RuntimeConfig;
-
-  constructor(config: RuntimeConfig) {
-    this.config = config;
-  }
-
-  /**
-   * Extract element ID from step text
-   * Supports: [screen.element] ONLY (not data refs)
-   * Data refs <data.field> are handled separately in test-data system
-   */
-  extractElementId(stepText: string, screenName: string): ExtractedAnnotation | null {
-    // Extract selector ID: [screen.element-name]
-    const selectorPattern = new RegExp(this.config.annotations.selectorId.pattern);
-    const selectorMatch = stepText.match(selectorPattern);
-
-    if (selectorMatch) {
-      const fullId = selectorMatch[1]; // e.g., "chat.input"
-      const [screen, element] = fullId.split('.');
-
-      // Only return if it matches the target screen
-      if (screen === screenName) {
-        return {
-          id: element,
-          type: 'selector'
-        };
-      }
-    }
-
-    // NOTE: Data references <data.field> are NOT included in selector files
-    // They belong in qa/test-data/ directory, not qa/selectors/
-    // This is per GHERKIN_STANDARDS.md specification
-
-    return null;
-  }
-
-  /**
-   * Check if step should be ignored
-   * Supports: # @ignore
-   */
-  shouldIgnoreStep(step: ParsedStep): boolean {
-    const ignorePattern = new RegExp(this.config.annotations.ignore.pattern);
-    return ignorePattern.test(step.text);
-  }
-
-  /**
-   * Check if entire scenario should be ignored
-   * Supports: # @ignore-testcase
-   */
-  shouldIgnoreScenario(scenario: ParsedScenario): boolean {
-    // Check scenario description
-    // @ts-ignore - Legacy parser may have description field
-    if (scenario.description) {
-      const ignorePattern = new RegExp(this.config.annotations.ignoreTestCase.pattern);
-      // @ts-ignore
-      if (ignorePattern.test(scenario.description)) {
-        return true;
-      }
-    }
-
-    // Check scenario tags (if any)
-    // @ts-ignore - Legacy parser may have tags field
-    if (scenario.tags && scenario.tags.includes('@ignore')) {
-      return true;
-    }
-
-    return false;
-  }
-
-  /**
-   * Check if step should be skipped in production
-   * Supports: # @skip-production
-   */
-  shouldSkipInProduction(step: ParsedStep): boolean {
-    const skipPattern = new RegExp(this.config.annotations.skipProduction.pattern);
-    return skipPattern.test(step.text);
-  }
-
-  /**
-   * Extract all element IDs from step (can have multiple)
-   */
-  extractAllElementIds(stepText: string): string[] {
-    const ids: string[] = [];
-
-    // Extract all [screen.element] patterns
-    const selectorPattern = new RegExp(this.config.annotations.selectorId.pattern, 'g');
-    let match;
-
-    while ((match = selectorPattern.exec(stepText)) !== null) {
-      ids.push(match[1]);
-    }
-
-    return ids;
-  }
-
-  /**
-   * Extract data references from step
-   */
-  extractDataRefs(stepText: string): string[] {
-    const refs: string[] = [];
-
-    // Extract all <data.ref> patterns
-    const dataPattern = new RegExp(this.config.annotations.dataRef.pattern, 'g');
-    let match;
-
-    while ((match = dataPattern.exec(stepText)) !== null) {
-      refs.push(match[1]);
-    }
-
-    return refs;
-  }
-}