@detiq/crawler 1.1.10 → 1.1.12

package/src/locator-extractor.ts

@@ -56,6 +56,7 @@ export function elementToPlaywrightLocator(element: {
   text?: string | null;
   notes?: unknown;
   selector?: string | null;
+  ariaState?: Record<string, unknown> | null;
 }): PlaywrightLocator | null {
   const attrs = parseNotes(element.notes);
   const testId = attrs['data-testid'];
@@ -66,6 +67,12 @@ export function elementToPlaywrightLocator(element: {
   const text = (element.text ?? '').trim();
   const meaning = (element.meaning ?? '').trim();
   const role = mapRole(element.role);
+  const ariaState: Record<string, string> = {};
+  if (element.ariaState && typeof element.ariaState === 'object') {
+    for (const [k, v] of Object.entries(element.ariaState)) {
+      if (typeof v === 'string') ariaState[k] = v;
+    }
+  }
 
   const label = meaning || text || testId || ariaLabel || placeholder || id || name || 'element';
   const key = toKey(label);
@@ -106,7 +113,19 @@ export function elementToPlaywrightLocator(element: {
     }
   }
 
-  // Priority 3: checkbox/radio → getByLabel
+  // Priority 3: checkbox/radio → getByRole with optional checked state from ariaState
+  if ((role === 'checkbox' || role === 'radio') && meaning) {
+    const isChecked = ariaState['checked'];
+    const stateOpt = isChecked === 'true' ? `, { name: ${JSON.stringify(meaning)}, checked: true }` : isChecked === 'false' ? `, { name: ${JSON.stringify(meaning)}, checked: false }` : `, { name: ${JSON.stringify(meaning)} }`;
+    return {
+      key,
+      expression: `page.getByRole(${JSON.stringify(role)}${stateOpt})`,
+      elementType: role,
+      confidence: 'high',
+      source: 'role-name',
+      description: meaning,
+    };
+  }
   if ((role === 'checkbox' || role === 'radio') && ariaLabel) {
     return {
       key,
@@ -118,11 +137,29 @@ export function elementToPlaywrightLocator(element: {
     };
   }
 
-  // Priority 4: button/link with meaningful name → getByRole
+  // Priority 3b: tab/option/treeitem → getByRole with optional selected state
+  const tabLikeRoles = ['tab', 'option', 'treeitem', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'gridcell'];
+  if (tabLikeRoles.includes(role ?? '') && meaning) {
+    const isSelected = ariaState['selected'];
+    const isCurrent = ariaState['current'];
+    const stateOpt = isSelected === 'true' ? `, { name: ${JSON.stringify(meaning)}, selected: true }` : isCurrent ? `, { name: ${JSON.stringify(meaning)} }` : `, { name: ${JSON.stringify(meaning)} }`;
+    return {
+      key,
+      expression: `page.getByRole(${JSON.stringify(role)}${stateOpt})`,
+      elementType: role ?? 'element',
+      confidence: 'high',
+      source: 'role-name',
+      description: meaning,
+    };
+  }
+
+  // Priority 4: button/link with meaningful name → getByRole; include pressed state for toggles
   if ((role === 'button' || role === 'link') && meaning) {
+    const isPressed = ariaState['pressed'];
+    const stateOpt = isPressed === 'true' ? `, { name: ${JSON.stringify(meaning)}, pressed: true }` : isPressed === 'false' ? `, { name: ${JSON.stringify(meaning)}, pressed: false }` : `, { name: ${JSON.stringify(meaning)} }`;
     return {
       key,
-      expression: `page.getByRole(${JSON.stringify(role)}, { name: ${JSON.stringify(meaning)} })`,
+      expression: `page.getByRole(${JSON.stringify(role)}${stateOpt})`,
       elementType: role,
       confidence: 'high',
       source: 'role-name',
@@ -194,6 +231,7 @@ export function elementsToPlaywrightLocators(elements: Array<{
   notes?: unknown;
   selector?: string | null;
   isInteractive?: boolean | null;
+  ariaState?: Record<string, unknown> | null;
 }>): PlaywrightLocator[] {
   const CONFIDENCE_RANK = { high: 0, medium: 1, low: 2 };
   const byKey = new Map<string, PlaywrightLocator>();

package/src/test-executor.ts

@@ -138,6 +138,116 @@ function applyHealInfo(result: StepResult, r: { healed: boolean; healedVia?: 'me
   result.healConfidence = r.healConfidence;
 }
 
+export async function executeExecutionStep(
+  page: Page,
+  step: ExecutionStep,
+  options: { healCtx?: { tenantId: string; projectId: string } } = {},
+): Promise<Pick<StepResult, 'healed' | 'healedVia' | 'healReasoning' | 'healConfidence' | 'elementBoundingRect' | 'elementSelector'>> {
+  const result: Pick<StepResult, 'healed' | 'healedVia' | 'healReasoning' | 'healConfidence' | 'elementBoundingRect' | 'elementSelector'> = {};
+  const timeout = step.timeout ?? parseInt(process.env.TEST_STEP_TIMEOUT_MS ?? '8000', 10);
+
+  switch (step.action) {
+    case 'navigate':
+      if (!step.url) throw new Error('Navigate step missing url');
+      assertCrawlUrlSafe(step.url);
+      await page.goto(step.url, { waitUntil: 'domcontentloaded', timeout });
+      break;
+
+    case 'click': {
+      const r = await resolveLocator(page, step, options.healCtx);
+      if (!r) throw new Error('Could not resolve locator');
+      result.elementBoundingRect = await r.loc.first().boundingBox().catch(() => null);
+      result.elementSelector = step.selector;
+      await r.loc.first().click({ timeout });
+      applyHealInfo(result as StepResult, r);
+      break;
+    }
+
+    case 'fill': {
+      const r = await resolveLocator(page, step, options.healCtx);
+      if (!r) throw new Error('Could not resolve locator');
+      result.elementBoundingRect = await r.loc.first().boundingBox().catch(() => null);
+      result.elementSelector = step.selector;
+      await r.loc.first().fill(step.value ?? '', { timeout });
+      applyHealInfo(result as StepResult, r);
+      break;
+    }
+
+    case 'select': {
+      const r = await resolveLocator(page, step, options.healCtx);
+      if (!r) throw new Error('Could not resolve locator');
+      result.elementBoundingRect = await r.loc.first().boundingBox().catch(() => null);
+      result.elementSelector = step.selector;
+      await r.loc.first().selectOption(step.value ?? '', { timeout });
+      applyHealInfo(result as StepResult, r);
+      break;
+    }
+
+    case 'hover': {
+      const r = await resolveLocator(page, step, options.healCtx);
+      if (!r) throw new Error('Could not resolve locator');
+      result.elementBoundingRect = await r.loc.first().boundingBox().catch(() => null);
+      result.elementSelector = step.selector;
+      await r.loc.first().hover({ timeout });
+      applyHealInfo(result as StepResult, r);
+      break;
+    }
+
+    case 'press_key':
+      await page.keyboard.press(step.value ?? 'Enter');
+      break;
+
+    case 'assert_visible': {
+      const r = await resolveLocator(page, step, options.healCtx);
+      if (!r) throw new Error('Could not resolve locator');
+      await r.loc.first().waitFor({ state: 'visible', timeout });
+      result.elementBoundingRect = await r.loc.first().boundingBox().catch(() => null);
+      result.elementSelector = step.selector;
+      applyHealInfo(result as StepResult, r);
+      break;
+    }
+
+    case 'assert_text': {
+      const r = await resolveLocator(page, step, options.healCtx);
+      if (!r) throw new Error('Could not resolve locator');
+      const text = await r.loc.first().textContent({ timeout });
+      if (!text?.includes(step.value ?? '')) {
+        throw new Error(`Expected text "${step.value}" not found. Got: "${text?.slice(0, 100)}"`);
+      }
+      result.elementBoundingRect = await r.loc.first().boundingBox().catch(() => null);
+      result.elementSelector = step.selector;
+      applyHealInfo(result as StepResult, r);
+      break;
+    }
+
+    case 'assert_url': {
+      const url = page.url();
+      if (!url.includes(step.value ?? '')) {
+        throw new Error(`Expected URL to contain "${step.value}". Got: "${url}"`);
+      }
+      break;
+    }
+
+    case 'wait':
+      await page.waitForTimeout(step.timeout ?? parseInt(process.env.TEST_STEP_DELAY_MS ?? '2000', 10));
+      break;
+
+    case 'screenshot':
+      break;
+
+    case 'script':
+    case 'setVariable':
+      if (step.value) {
+        await page.evaluate(step.value).catch(err => {
+          throw new Error(`Script execution failed: ${err.message}`);
+        });
+      }
+      break;
+  }
+
+  return result;
+}
+
 async function runPlan(
   page: Page,
   plan: ExecutionStep[],
@@ -253,6 +363,18 @@ async function runPlan(
           result.screenshotPath = ssPath;
           break;
         }
+
+        case 'script':
+        case 'setVariable': {
+          if (step.value) {
+            // Execute arbitrary JS string. Often used by manual test builder extension for custom variables
+            // or assertions.
+            await page.evaluate(step.value).catch(err => {
+              throw new Error(`Script execution failed: ${err.message}`);
+            });
+          }
+          break;
+        }
       }
 
       result.status = 'PASSED';

package/types/crawler.d.ts

@@ -190,4 +190,13 @@ export declare function crawlProject(opts: {
     domHashes: string[];
     discoveredUrls?: undefined;
 }>;
+export declare function domFallbackElements(page: any): Promise<Array<{
+    meaning: string;
+    role: string;
+    expectedData?: string;
+    notes?: string;
+    boundingRect?: Record<string, number>;
+    ariaState?: Record<string, string>;
+    parentLandmark?: string;
+}>>;
 export {};

package/types/locator-extractor.d.ts

@@ -17,6 +17,7 @@ export declare function elementToPlaywrightLocator(element: {
     text?: string | null;
     notes?: unknown;
     selector?: string | null;
+    ariaState?: Record<string, unknown> | null;
 }): PlaywrightLocator | null;
 /**
  * Convert an array of DB Element records to deduplicated Playwright locators.
@@ -29,6 +30,7 @@ export declare function elementsToPlaywrightLocators(elements: Array<{
     notes?: unknown;
     selector?: string | null;
     isInteractive?: boolean | null;
+    ariaState?: Record<string, unknown> | null;
 }>): PlaywrightLocator[];
 /**
  * Format locators as a block for injection into LLM script generation prompts.

package/types/test-executor.d.ts

@@ -1,3 +1,4 @@
+import { type Page } from 'playwright';
 import type { ExecutionStep } from '@detiq/agents';
 export interface StepResult {
     stepNumber: number;
@@ -47,6 +48,12 @@ export interface ExecutionResult {
         duration: number;
     }>;
 }
+export declare function executeExecutionStep(page: Page, step: ExecutionStep, options?: {
+    healCtx?: {
+        tenantId: string;
+        projectId: string;
+    };
+}): Promise<Pick<StepResult, 'healed' | 'healedVia' | 'healReasoning' | 'healConfidence' | 'elementBoundingRect' | 'elementSelector'>>;
 export declare function executeTestPlan(plan: ExecutionStep[], options: {
     screenshotDir: string;
     testRunId: string;