@sun-asterisk/sungen 1.0.22 → 1.0.24

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

@@ -32,11 +32,12 @@ export async function findElement(
   page: Page,
   gherkinRef: string,
   gherkinType: string,
-  nth: number = 0
+  nth: number = 0,
+  context: ElementContext = 'page'
 ): Promise<LiveElement> {
   const namePattern = new RegExp(escapeRegex(gherkinRef), 'i');
 
-  const result = await cascadingSearch(page, gherkinRef, gherkinType, namePattern, nth);
+  const result = await cascadingSearch(page, gherkinRef, gherkinType, namePattern, nth, context);
 
   if (!result) {
     return buildUnresolvedElement(gherkinRef, gherkinType);
@@ -80,6 +81,7 @@ export async function findElement(
     name: actualName,
     testid: attrs.testid,
     tag: attrs.tag,
+    contenteditable: attrs.contenteditable,
     placeholder: attrs.placeholder,
     label: attrs.label,
     context: 'page',
@@ -94,7 +96,8 @@ async function cascadingSearch(
   gherkinRef: string,
   gherkinType: string,
   namePattern: RegExp,
-  nth: number
+  nth: number,
+  context: ElementContext = 'page'
 ): Promise<FindResult | null> {
   // ① getByTestId
   const testidResult = await tryTestId(page, gherkinRef, nth);
@@ -134,6 +137,14 @@ async function cascadingSearch(
     // ⑤ getByPlaceholder — for input fields
     const placeholderResult = await tryPlaceholder(page, gherkinRef, namePattern, nth);
     if (placeholderResult) return placeholderResult;
+
+    // ⑤.5 contenteditable — for rich text editors (textarea/textbox/field types)
+    // When role match fails (editor has role="textbox" but no accessible name),
+    // try to find a [contenteditable="true"] element scoped to the current context
+    if (isEditableType(gherkinType)) {
+      const ceResult = await tryContentEditable(page, nth, context);
+      if (ceResult) return ceResult;
+    }
   }
 
   // ⑥ getByText — final fallback
@@ -173,7 +184,7 @@ async function tryTestId(page: Page, ref: string, nth: number): Promise<FindResu
   return null;
 }
 
-// ② ③ getByRole — exact string first, then regex fallback
+// ② ③ getByRole — regex first, exact disambiguation when ambiguous
 async function tryRole(
   page: Page,
   role: string,
@@ -181,12 +192,13 @@ async function tryRole(
   namePattern: RegExp,
   nth: number
 ): Promise<FindResult | null> {
-  // Step 1: Exact string match (prevents short refs matching longer names)
   try {
-    const exactLocator = page.getByRole(role as any, { name: gherkinRef, exact: true });
-    const exactCount = await exactLocator.count();
-    if (exactCount > 0) {
-      const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
+    const locator = page.getByRole(role as any, { name: namePattern });
+    const count = await locator.count();
+    if (count === 0) return null;
+
+    if (count === 1) {
+      const target = nth > 0 ? locator.nth(nth) : locator.first();
       if (await target.isVisible({ timeout: 3000 })) {
         return {
           locator: target,
@@ -197,22 +209,31 @@ async function tryRole(
           warning: null,
         };
       }
-    }
-  } catch {
-    // Exact match not found, continue to regex
-  }
+    } else {
+      // Multiple matches — try exact to disambiguate
+      try {
+        const exactLocator = page.getByRole(role as any, { name: gherkinRef, exact: true });
+        const exactCount = await exactLocator.count();
+        if (exactCount > 0) {
+          const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
+          if (await target.isVisible({ timeout: 3000 })) {
+            return {
+              locator: target,
+              selectorType: 'role',
+              selectorValue: role,
+              role: role,
+              matchMethod: 'exact_role',
+              warning: null,
+            };
+          }
+        }
+      } catch {
+        // Exact disambiguation failed
+      }
 
-  // Step 2: Regex fallback (substring match)
-  try {
-    const locator = page.getByRole(role as any, { name: namePattern });
-    const count = await locator.count();
-    if (count > 0) {
+      // Fall back to first regex match
       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',
@@ -229,140 +250,191 @@ async function tryRole(
   return null;
 }
 
-// ④ getByLabel — exact string first, then regex fallback
+// ④ getByLabel — regex first, exact disambiguation when ambiguous
 async function tryLabel(page: Page, gherkinRef: string, namePattern: RegExp, nth: number): Promise<FindResult | null> {
-  // Step 1: Exact string match
-  try {
-    const exactLocator = page.getByLabel(gherkinRef, { exact: true });
-    const exactCount = await exactLocator.count();
-    if (exactCount > 0) {
-      const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
-      if (await target.isVisible({ timeout: 3000 })) {
-        return {
-          locator: target,
-          selectorType: 'label',
-          selectorValue: '',  // Will be filled from attrs
-          role: '',
-          matchMethod: 'label',
-          warning: null,
-        };
-      }
-    }
-  } catch {
-    // Exact match not found, continue to regex
-  }
-
-  // Step 2: Regex fallback
   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,
-        };
+    if (count === 0) return null;
+
+    if (count > 1) {
+      // Multiple matches — try exact to disambiguate
+      try {
+        const exactLocator = page.getByLabel(gherkinRef, { exact: true });
+        const exactCount = await exactLocator.count();
+        if (exactCount > 0) {
+          const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
+          if (await target.isVisible({ timeout: 3000 })) {
+            return {
+              locator: target,
+              selectorType: 'label',
+              selectorValue: '',
+              role: '',
+              matchMethod: 'label',
+              warning: null,
+            };
+          }
+        }
+      } catch {
+        // Exact disambiguation failed
       }
     }
+
+    // Single match or exact failed — use first regex match
+    const target = nth > 0 ? locator.nth(nth) : locator.first();
+    if (await target.isVisible({ timeout: 3000 })) {
+      return {
+        locator: target,
+        selectorType: 'label',
+        selectorValue: '',
+        role: '',
+        matchMethod: 'label',
+        warning: null,
+      };
+    }
   } catch {
     // Label not found
   }
   return null;
 }
 
-// ⑤ getByPlaceholder — exact string first, then regex fallback
+// ⑤ getByPlaceholder — regex first, exact disambiguation when ambiguous
 async function tryPlaceholder(page: Page, gherkinRef: string, namePattern: RegExp, nth: number): Promise<FindResult | null> {
-  // Step 1: Exact string match
-  try {
-    const exactLocator = page.getByPlaceholder(gherkinRef, { exact: true });
-    const exactCount = await exactLocator.count();
-    if (exactCount > 0) {
-      const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
-      if (await target.isVisible({ timeout: 3000 })) {
-        const rawPlaceholder = await target.getAttribute('placeholder');
-        return {
-          locator: target,
-          selectorType: 'placeholder',
-          selectorValue: sanitizeText(rawPlaceholder || ''),
-          role: '',
-          matchMethod: 'placeholder',
-          warning: null,
-        };
-      }
-    }
-  } catch {
-    // Exact match not found, continue to regex
-  }
-
-  // Step 2: Regex fallback
   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 rawPlaceholder = await target.getAttribute('placeholder');
-        return {
-          locator: target,
-          selectorType: 'placeholder',
-          selectorValue: sanitizeText(rawPlaceholder || ''),
-          role: '',
-          matchMethod: 'placeholder',
-          warning: null,
-        };
+    if (count === 0) return null;
+
+    if (count > 1) {
+      // Multiple matches — try exact to disambiguate
+      try {
+        const exactLocator = page.getByPlaceholder(gherkinRef, { exact: true });
+        const exactCount = await exactLocator.count();
+        if (exactCount > 0) {
+          const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
+          if (await target.isVisible({ timeout: 3000 })) {
+            const rawPlaceholder = await target.getAttribute('placeholder');
+            return {
+              locator: target,
+              selectorType: 'placeholder',
+              selectorValue: sanitizeText(rawPlaceholder || ''),
+              role: '',
+              matchMethod: 'placeholder',
+              warning: null,
+            };
+          }
+        }
+      } catch {
+        // Exact disambiguation failed
       }
     }
+
+    // Single match or exact failed — use first regex match
+    const target = nth > 0 ? locator.nth(nth) : locator.first();
+    if (await target.isVisible({ timeout: 3000 })) {
+      const rawPlaceholder = await target.getAttribute('placeholder');
+      return {
+        locator: target,
+        selectorType: 'placeholder',
+        selectorValue: sanitizeText(rawPlaceholder || ''),
+        role: '',
+        matchMethod: 'placeholder',
+        warning: null,
+      };
+    }
   } catch {
     // Placeholder not found
   }
   return null;
 }
 
-// ⑥ getByText — exact string first, then regex fallback
-async function tryText(page: Page, gherkinRef: string, namePattern: RegExp, nth: number): Promise<FindResult | null> {
-  // Step 1: Exact string match
+/**
+ * Check if gherkinType is an editable/input type that could be a contenteditable div
+ */
+function isEditableType(gherkinType: string): boolean {
+  const normalized = gherkinType.toLowerCase().trim();
+  return normalized === 'textarea' || normalized === 'textbox' || normalized === 'field' || normalized === 'editor';
+}
+
+
+
+// ⑤.5 contenteditable — for rich text editors
+// Scoped to current context (dialog/page) to avoid matching wrong editor.
+// The nth from Gherkin refers to text matches, not contenteditable count,
+// so we try the requested nth first, then fall back to first match.
+async function tryContentEditable(page: Page, nth: number, context: ElementContext): Promise<FindResult | null> {
   try {
-    const exactLocator = page.getByText(gherkinRef, { exact: true });
-    const exactCount = await exactLocator.count();
-    if (exactCount > 0) {
-      const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
+    // Scope the search to the current context
+    const root = context === 'dialog' ? page.getByRole('dialog') : page;
+    const locator = root.locator('[contenteditable="true"]');
+    const count = await locator.count();
+    if (count === 0) return null;
+
+    // Try requested nth first, then fall back to first visible
+    const candidates = nth > 0 && count > nth ? [nth, 0] : [0];
+    for (const idx of candidates) {
+      const target = idx > 0 ? locator.nth(idx) : 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,
+          selectorType: 'locator',
+          selectorValue: '[contenteditable="true"]',
+          role: 'textbox',
+          matchMethod: 'contenteditable',
+          warning: count > 1
+            ? `${count} contenteditable elements in ${context}, using index ${idx}. Use nth in Gherkin to disambiguate.`
+            : null,
         };
       }
     }
   } catch {
-    // Exact match not found, continue to regex
+    // Not found
   }
+  return null;
+}
 
-  // Step 2: Regex fallback
+// ⑥ getByText — regex first, exact disambiguation when ambiguous
+async function tryText(page: Page, gherkinRef: string, 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,
-        };
+    if (count === 0) return null;
+
+    if (count > 1) {
+      // Multiple matches — try exact to disambiguate
+      try {
+        const exactLocator = page.getByText(gherkinRef, { exact: true });
+        const exactCount = await exactLocator.count();
+        if (exactCount > 0) {
+          const target = nth > 0 ? exactLocator.nth(nth) : exactLocator.first();
+          if (await target.isVisible({ timeout: 3000 })) {
+            return {
+              locator: target,
+              selectorType: 'text',
+              selectorValue: '',
+              role: '',
+              matchMethod: 'text_only',
+              warning: null,
+            };
+          }
+        }
+      } catch {
+        // Exact disambiguation failed
       }
     }
+
+    // Single match or exact failed — use first regex match
+    const target = nth > 0 ? locator.nth(nth) : locator.first();
+    if (await target.isVisible({ timeout: 3000 })) {
+      return {
+        locator: target,
+        selectorType: 'text',
+        selectorValue: '',
+        role: '',
+        matchMethod: 'text_only',
+        warning: null,
+      };
+    }
   } catch {
     // Text not found
   }
@@ -372,6 +444,7 @@ async function tryText(page: Page, gherkinRef: string, namePattern: RegExp, nth:
 async function extractElementAttributes(locator: Locator): Promise<{
   testid: string | null;
   tag: string;
+  contenteditable: boolean;
   accessibleName: string;
   placeholder: string | null;
   label: string | null;
@@ -392,16 +465,22 @@ async function extractElementAttributes(locator: Locator): Promise<{
         label = clean(el.closest('label')?.textContent) || null;
       }
 
+      // Detect contenteditable: check element itself and ancestors (rich text editors
+      // often have contenteditable on a parent div wrapping the editable area)
+      const isContentEditable = el.getAttribute('contenteditable') === 'true'
+        || el.isContentEditable;
+
       return {
         testid: el.getAttribute('data-testid'),
         tag: el.tagName.toLowerCase(),
+        contenteditable: isContentEditable,
         accessibleName: clean(el.getAttribute('aria-label') || el.textContent?.trim()?.substring(0, 100)),
         placeholder: clean(el.getAttribute('placeholder')) || null,
         label,
       };
     });
   } catch {
-    return { testid: null, tag: 'unknown', accessibleName: '', placeholder: null, label: null };
+    return { testid: null, tag: 'unknown', contenteditable: false, accessibleName: '', placeholder: null, label: null };
   }
 }
 
@@ -415,6 +494,7 @@ function buildUnresolvedElement(gherkinRef: string, gherkinType: string): LiveEl
     name: gherkinRef,
     testid: null,
     tag: '',
+    contenteditable: false,
     placeholder: null,
     label: null,
     context: 'page',

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

@@ -45,6 +45,7 @@ export function mergeMatrixElements(result: LiveScanResult): Record<string, Live
         name: el.name || '',
         testid: el.testid || null,
         tag: el.tag || '',
+        contenteditable: el.contenteditable === true,
         placeholder: el.placeholder || null,
         label: el.label || null,
         context: (el.context as any) || 'page',

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

@@ -46,6 +46,7 @@ export function writeMatrix(result: LiveScanResult, outputPath: string): void {
         name: sanitizeForYaml(element.name),
         testid: element.testid,
         tag: element.tag,
+        contenteditable: element.contenteditable,
         placeholder: sanitizeForYaml(element.placeholder),
         label: sanitizeForYaml(element.label),
         context: element.context,

package/src/core/live-scanner/role-fallback.ts

@@ -14,6 +14,7 @@ const ROLE_FALLBACK_GROUPS: Record<string, string[]> = {
   dialog:   ['dialog', 'alertdialog'],
   modal:    ['dialog', 'alertdialog'],
   tab:      ['tab', 'button', 'link'],
+  option:   ['option', 'menuitem', 'listitem'],
   row:      ['row', 'listitem', 'option'],
   tag:      ['button', 'link', 'option'],
   uploader: ['textbox', 'button'],

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

@@ -6,11 +6,13 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { glob } from 'glob';
+import * as yaml from 'yaml';
 import { LiveScanResult, LiveScanScenario, LiveScanOptions } from './types';
 import { replaySteps } from './step-replayer';
 import { writeMatrix } from './matrix-writer';
 import { readMatrix, mergeMatrixElements } from './matrix-reader';
 import { readBaseUrlFromPlaywrightConfig } from './config-reader';
+import { readYamlIfExists } from '../../utils/yaml-io';
 
 export class LiveScanner {
   private options: LiveScanOptions;
@@ -81,7 +83,11 @@ export class LiveScanner {
 
         try {
           const parsed = parser.parseFeatureFile(featureFile);
-          const result = await this.scanFeature(browser, playwright, parsed, baseUrl, existingResult);
+          const result = await this.scanFeature(browser, playwright, parsed, baseUrl, existingResult, featureName);
+          if (!result) {
+            console.log(`   ⏭️  Feature skipped (missing test-data)`);
+            continue;
+          }
           results.push(result);
 
           // Write matrix file
@@ -99,6 +105,42 @@ export class LiveScanner {
     return results;
   }
 
+  /**
+   * Load test-data YAML for a feature, merging override over base.
+   * Returns null if no test-data file exists.
+   */
+  private loadTestData(featureName: string): Record<string, any> | null {
+    const testDataDir = path.join(this.options.screensDir, this.options.screenName, 'test-data');
+    const basePath = path.join(testDataDir, `${featureName}.yaml`);
+    const overridePath = path.join(testDataDir, `${featureName}.override.yaml`);
+
+    const base = readYamlIfExists<Record<string, any>>(basePath);
+    const override = readYamlIfExists<Record<string, any>>(overridePath);
+
+    if (!base && !override) return null;
+
+    return { ...(base || {}), ...(override || {}) };
+  }
+
+  /**
+   * Find dataRef keys from steps that resolve to empty string in testData.
+   */
+  private findEmptyDataKeys(testData: Record<string, any>, steps: any[]): string[] {
+    const emptyKeys: string[] = [];
+    for (const step of steps) {
+      if (!step.dataRef) continue;
+      const parts = step.dataRef.replace(/[{}]/g, '').split('.');
+      let value: any = testData;
+      for (const part of parts) {
+        value = value?.[part];
+      }
+      if (value === undefined || value === null || value === '') {
+        emptyKeys.push(step.dataRef);
+      }
+    }
+    return [...new Set(emptyKeys)];
+  }
+
   private resolveBaseUrl(): string {
     // 1. Explicit option (from --url flag)
     if (this.options.baseUrl) {
@@ -124,8 +166,9 @@ export class LiveScanner {
     playwright: any,
     feature: any,
     baseUrl: string,
-    existingResult?: LiveScanResult | null
-  ): Promise<LiveScanResult> {
+    existingResult?: LiveScanResult | null,
+    featureFileName?: string
+  ): Promise<LiveScanResult | null> {
     const featurePath = feature.path || '/';
     const scenarios: Record<string, LiveScanScenario> = {};
 
@@ -140,6 +183,31 @@ export class LiveScanner {
       }
     }
 
+    // Collect all steps across scenarios to check for dataRefs
+    const allSteps = feature.scenarios.flatMap((s: any) => s.steps || []);
+    const hasDataRefs = allSteps.some((s: any) => s.dataRef);
+
+    // Load test-data if needed
+    let testData: Record<string, any> | null = null;
+    if (hasDataRefs) {
+      const testDataName = featureFileName || path.basename(feature.sourceFile || '', '.feature');
+      testData = this.loadTestData(testDataName);
+      if (!testData) {
+        const screenName = this.options.screenName;
+        console.warn(`   ⚠️  Feature has {{dataRef}} steps but no test-data file found — skipping feature`);
+        console.warn(`   💡 To fix:`);
+        console.warn(`      1. Run: sungen map --screen ${screenName} --skip-live-scan`);
+        console.warn(`      2. Fill test-data values in qa/screens/${screenName}/test-data/`);
+        console.warn(`      3. Re-run: sungen live-scan --screen ${screenName}`);
+        return null;
+      }
+      const emptyKeys = this.findEmptyDataKeys(testData, allSteps);
+      if (emptyKeys.length > 0) {
+        console.warn(`   ⚠️  Empty test-data values for: ${emptyKeys.join(', ')}`);
+        console.warn(`   💡 Fill these in qa/screens/${this.options.screenName}/test-data/ for accurate results`);
+      }
+    }
+
     for (const scenario of feature.scenarios) {
       // Skip @steps-only scenarios (they're reusable blocks, not standalone)
       if (scenario.stepsName && !scenario.extendsName) {
@@ -182,7 +250,7 @@ export class LiveScanner {
       const page = await context.newPage();
 
       try {
-        const result = await replaySteps(page, steps, featurePath, baseUrl, existingElements);
+        const result = await replaySteps(page, steps, featurePath, baseUrl, existingElements, testData);
 
         scenarios[scenarioKey] = {
           auth: authRole,
@@ -216,15 +284,14 @@ export class LiveScanner {
             // Already printed in replaySteps
             continue;
           }
+          // Use dataValue (from data-value fallback) for display when name is empty
+          const displayName = el.name || el.dataValue || el.gherkinRef;
           if (el.matchMethod === 'unresolved') {
             console.log(`      ✗ [${el.gherkinRef}] ${el.gherkinType} → NOT FOUND`);
           } else if (el.warning) {
-            console.log(`      ⚠ [${el.gherkinRef}] ${el.gherkinType} → ${el.selectorType}(${el.selectorValue || el.name}) (${el.warning})`);
+            console.log(`      ⚠ [${el.gherkinRef}] ${el.gherkinType} → ${el.selectorType}(${el.selectorValue || displayName}) (${el.warning})`);
           } else {
-            const locatorDesc = el.selectorType
-              ? `${el.selectorType}${el.role ? `('${el.role}', {name: '${el.name}'})` : `('${el.selectorValue || el.name}')`}`
-              : el.gherkinType;
-            console.log(`      ✓ [${el.gherkinRef}] → getBy${capitalize(el.selectorType || 'text')}${el.role ? `('${el.role}', {name: '${el.name}'})` : `('${el.selectorValue || el.name}')`}`);
+            console.log(`      ✓ [${el.gherkinRef}] → getBy${capitalize(el.selectorType || 'text')}${el.role ? `('${el.role}', {name: '${displayName}'})` : `('${el.selectorValue || displayName}')`}`);
           }
         }
       } finally {