@zibby/core 0.1.0

package/src/runtime/generation/mcp-ref-strategy.js

@@ -0,0 +1,197 @@
+import { TestGenerationStrategy } from './base.js';
+import { readFileSync, writeFileSync } from 'fs';
+
+/**
+ * MCPRefStrategy - Generates tests using MCP element descriptions
+ * 
+ * This strategy generates tests that use the EXACT elements that were
+ * interacted with during recording, identified by their MCP ref IDs.
+ * 
+ * Reliability: 99% - Works as long as the DOM structure is similar between runs
+ */
+export class MCPRefStrategy extends TestGenerationStrategy {
+  constructor() {
+    super(
+      'mcp-ref',
+      'MCP Reference Replay (Exact 1:1)',
+      200 // Highest priority - most accurate
+    );
+  }
+
+  canGenerate(context) {
+    // Check if events have MCP element descriptions
+    const eventsPath = context.eventsPath || `${context.sessionPath}/execute_live/events.json`;
+    
+    try {
+      const events = JSON.parse(readFileSync(eventsPath, 'utf-8'));
+      const hasMCPElements = events.some(e => e.data?.params?.element);
+      
+      if (!hasMCPElements) {
+        console.log('[MCPRefStrategy] ❌ No MCP element descriptions found in events');
+        return false;
+      }
+      
+      console.log('[MCPRefStrategy] ✅ MCP element descriptions available');
+      return true;
+    } catch (e) {
+      console.log('[MCPRefStrategy] ❌ Failed to read events:', e.message);
+      return false;
+    }
+  }
+
+  getName() {
+    return 'MCP Reference Replay (Exact 1:1)';
+  }
+
+  getPriority() {
+    return 200;
+  }
+
+  async generate(context) {
+    const { testFilePath, sessionPath, state } = context;
+    const eventsPath = `${sessionPath}/execute_live/events.json`;
+    const testTitle = state?.title || 'Generated Test';
+    
+    console.log('[MCPRefStrategy] 🎯 Generating test using MCP element descriptions (1:1 replay)');
+    console.log(`[MCPRefStrategy]    events: ${eventsPath}`);
+    console.log(`[MCPRefStrategy]    output: ${testFilePath}`);
+    
+    const events = JSON.parse(readFileSync(eventsPath, 'utf-8'));
+    const actionEvents = events.filter(e => 
+      ['navigate', 'type', 'fill', 'click', 'select_option'].includes(e.type)
+    );
+
+    let testCode = `import { test, expect } from '@playwright/test';\n`;
+    testCode += `import { ZibbyRuntime } from '@zibby/core';\n\n`;
+    testCode += `test('${testTitle}', async ({ page }) => {\n`;
+    testCode += `  const timestamp = Date.now();\n\n`;
+
+    for (const event of actionEvents) {
+      const mcpElement = event.data?.params?.element || 'element';
+      const _ref = event.data?.params?.ref;
+      
+      // Priority order for element text (handles Chinese/multi-language):
+      // 1. traceActualText - extracted from accessibility tree in trace.zip (MOST RELIABLE)
+      // 2. traceActualRole - extracted from accessibility tree (ACTUAL role)
+      // 3. traceActualAriaLabel - extracted from accessibility tree (ACTUAL aria-label)
+      // 4. actualText - captured during live recording (if available)
+      // 5. mcpElement - AI's description (fallback)
+      const traceText = event.enrichedData?.traceActualText;
+      const traceRole = event.enrichedData?.traceActualRole;
+      const _traceLabel = event.enrichedData?.traceActualAriaLabel;
+      const liveText = event.enrichedData?.actualText;
+      const actualText = traceText || liveText;
+      const actualRole = traceRole || event.enrichedData?.actualRole;
+      
+      // Use FULL description for text matching (don't strip role suffix)
+      const _fullText = actualText || mcpElement;
+      // Use name only (without role) for getByRole
+      const nameOnly = actualText || this._extractName(mcpElement);
+      const selectorRole = actualRole || this._extractRole(mcpElement);
+      
+      const sourceNote = traceText ? ' [accessibility-tree]' : (liveText ? ' [live]' : ' [AI]');
+
+      if (event.type === 'navigate') {
+        testCode += `  await page.goto('${event.data.params.url}');\n\n`;
+      } else if (event.type === 'click') {
+        testCode += `  // ${mcpElement}${actualText ? ` (actual: "${actualText}")${sourceNote}` : ''}\n`;
+        testCode += `  await ZibbyRuntime.step(page, {\n`;
+        testCode += `    name: '${this._escapeString(mcpElement)}',\n`;
+        testCode += `    action: 'click',\n`;
+        testCode += `    strategies: [\n`;
+        
+        // 95% RELIABLE STRATEGY:
+        // Priority 1: Use getByRole with the EXACT description from trace
+        // Playwright aggregates ALL nested text automatically, so "HR Our core HR system button"
+        // will match even if text is split across <div>HR</div><div>Our core HR system</div>
+        testCode += `      { type: 'role', role: '${selectorRole}', name: '${this._escapeString(nameOnly)}' },\n`;
+        
+        // Priority 2: Text search (Playwright searches ALL nested text)
+        testCode += `      { type: 'text', text: '${this._escapeString(nameOnly)}' }\n`;
+        
+        testCode += `    ]\n`;
+        testCode += `  });\n\n`;
+      } else if (event.type === 'fill' || event.type === 'type') {
+        const value = event.data.params.text;
+        testCode += `  // ${mcpElement}${actualText ? ` (actual: "${actualText}")${sourceNote}` : ''}\n`;
+        testCode += `  await ZibbyRuntime.step(page, {\n`;
+        testCode += `    name: '${this._escapeString(mcpElement)}',\n`;
+        testCode += `    action: 'fill',\n`;
+        testCode += `    value: '${this._escapeString(value)}',\n`;
+        testCode += `    strategies: [\n`;
+        testCode += `      { type: 'role', role: '${selectorRole}', name: '${this._escapeString(nameOnly)}' },\n`;
+        testCode += `      { type: 'attributes', placeholder: '${this._escapeString(nameOnly)}' }\n`;
+        testCode += `    ]\n`;
+        testCode += `  });\n\n`;
+      } else if (event.type === 'select_option') {
+        const values = event.data.params.values;
+        const value = Array.isArray(values) ? values[0] : values;
+        testCode += `  // ${mcpElement}${actualText ? ` (actual: "${actualText}")${sourceNote}` : ''}\n`;
+        testCode += `  await ZibbyRuntime.step(page, {\n`;
+        testCode += `    name: '${this._escapeString(mcpElement)}',\n`;
+        testCode += `    action: 'select',\n`;
+        testCode += `    value: '${this._escapeString(value)}',\n`;
+        testCode += `    strategies: [\n`;
+        testCode += `      { type: 'role', role: 'combobox', name: '${this._escapeString(nameOnly)}' }\n`;
+        testCode += `    ]\n`;
+        testCode += `  });\n\n`;
+      }
+    }
+
+    testCode += `});\n`;
+
+    writeFileSync(testFilePath, testCode);
+    
+    console.log(`[MCPRefStrategy] ✅ Generated test with ${actionEvents.length} actions using MCP descriptions`);
+    
+    return {
+      success: true,
+      testPath: testFilePath,
+      method: 'MCP Reference Replay (1:1)',
+      actionsGenerated: actionEvents.length
+    };
+  }
+
+  /**
+   * Extract role from MCP element description
+   * e.g., "Login button" -> "button", "Email textbox" -> "textbox"
+   */
+  _extractRole(mcpElement) {
+    const lowerElement = mcpElement.toLowerCase();
+    
+    if (lowerElement.includes('button')) return 'button';
+    if (lowerElement.includes('textbox')) return 'textbox';
+    if (lowerElement.includes('link')) return 'link';
+    if (lowerElement.includes('checkbox')) return 'checkbox';
+    if (lowerElement.includes('radio')) return 'radio';
+    if (lowerElement.includes('combobox')) return 'combobox';
+    if (lowerElement.includes('heading')) return 'heading';
+    
+    // Default to generic
+    return 'button';
+  }
+
+  /**
+   * Extract name from MCP element description
+   * e.g., "Login button" -> "Login", "Email textbox" -> "Email"
+   */
+  _extractName(mcpElement) {
+    // Remove common role suffixes
+    return mcpElement
+      .replace(/\s+(button|textbox|link|checkbox|radio|combobox)$/i, '')
+      .trim();
+  }
+
+  /**
+   * Escape special regex characters for safe use in regex
+   * Important for Chinese, Arabic, and special symbols
+   */
+  _escapeRegex(text) {
+    // Escape special regex characters but preserve Unicode (Chinese, etc.)
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+
+  _escapeString(text) {
+    return text.replace(/'/g, "\\'").replace(/\n/g, '\\n');
+  }
+}

package/src/runtime/generation/stable-id-strategy.js

@@ -0,0 +1,170 @@
+import { TestGenerationStrategy } from './base.js';
+import { readFileSync, writeFileSync } from 'fs';
+
+/**
+ * StableIdStrategy - Generates tests using injected stable IDs
+ * 
+ * This strategy uses deterministic IDs injected into the DOM during recording.
+ * The same IDs are re-injected during test execution for direct element lookup.
+ * 
+ * Reliability: 95%+ - Works as long as DOM structure is similar between runs
+ * Bypasses all text-matching and CSS selector fragility issues.
+ */
+export class StableIdStrategy extends TestGenerationStrategy {
+  constructor() {
+    super(
+      'stable-id',
+      'Stable ID Injection (Experimental)',
+      300 // Highest priority - most reliable when available
+    );
+  }
+
+  canGenerate(context) {
+    // Check if events have stable IDs
+    const eventsPath = context.eventsPath || `${context.sessionPath}/execute_live/events.json`;
+    
+    try {
+      const events = JSON.parse(readFileSync(eventsPath, 'utf-8'));
+      const hasStableIds = events.some(e => e.stableId || e.data?.stableId);
+      
+      if (!hasStableIds) {
+        console.log('[StableIdStrategy] ❌ No stable IDs found in events');
+        return false;
+      }
+      
+      console.log('[StableIdStrategy] ✅ Stable IDs available');
+      return true;
+    } catch (e) {
+      console.log('[StableIdStrategy] ❌ Failed to read events:', e.message);
+      return false;
+    }
+  }
+
+  getName() {
+    return 'Stable ID Injection (Experimental)';
+  }
+
+  getPriority() {
+    return 300;
+  }
+
+  async generate(context) {
+    const { testFilePath, sessionPath, state } = context;
+    const eventsPath = `${sessionPath}/execute_live/events.json`;
+    const testTitle = state?.title || 'Generated Test';
+    
+    console.log('[StableIdStrategy] 🎯 Generating test using stable IDs');
+    console.log(`[StableIdStrategy]    events: ${eventsPath}`);
+    console.log(`[StableIdStrategy]    output: ${testFilePath}`);
+    
+    const events = JSON.parse(readFileSync(eventsPath, 'utf-8'));
+    const actionEvents = events.filter(e => 
+      ['navigate', 'type', 'fill', 'click', 'select_option', 'select'].includes(e.type)
+    );
+
+    let testCode = `import { test, expect } from '@playwright/test';\n`;
+    testCode += `import { StableIdRuntime } from '@zibby/core';\n\n`;
+    testCode += `test('${testTitle}', async ({ page }) => {\n`;
+
+    let skipNavigates = false;
+    let lastClickId = null;
+    
+    for (let i = 0; i < actionEvents.length; i++) {
+      const event = actionEvents[i];
+      const stableId = event.stableId || event.data?.stableId;
+      const mcpElement = event.data?.element || event.data?.params?.element || 'element';
+      
+      // Skip duplicate consecutive clicks on same element
+      if (event.type === 'click' && stableId && stableId === lastClickId) {
+        console.log(`[StableIdStrategy] Skipping duplicate click on ${stableId}`);
+        continue;
+      }
+      
+      if (event.type === 'navigate') {
+        const url = event.data?.url || event.data?.params?.url;
+        if (url && !skipNavigates) {
+          testCode += `  await page.goto('${url}');\n`;
+          testCode += `  await StableIdRuntime.injectStableIds(page);\n\n`;
+        }
+        // Keep skipNavigates as-is - multiple navigates after click should all be skipped
+      } else if (event.type === 'click') {
+        skipNavigates = true;
+        lastClickId = stableId;
+        if (stableId) {
+          testCode += `  await StableIdRuntime.clickWithRetry(page, '${stableId}');\n`;
+        } else {
+          const selector = this._generateSemanticSelector(mcpElement);
+          testCode += `  await ${selector}.click();\n`;
+          testCode += `  await StableIdRuntime.afterNavigation(page);\n`;
+        }
+      } else if (event.type === 'fill' || event.type === 'type') {
+        skipNavigates = false;
+        const value = event.data?.text || event.data?.params?.text || '';
+        if (stableId) {
+          testCode += `  await StableIdRuntime.fillWithRetry(page, '${stableId}', '${this._escapeString(value)}');\n`;
+        } else {
+          testCode += `  await page.getByPlaceholder('${this._escapeString(mcpElement)}').fill('${this._escapeString(value)}');\n`;
+        }
+      } else if (event.type === 'select_option' || event.type === 'select') {
+        skipNavigates = false;
+        const values = event.data?.values || event.data?.params?.values;
+        const value = Array.isArray(values) ? values[0] : values || '';
+        if (stableId) {
+          testCode += `  await StableIdRuntime.selectWithRetry(page, '${stableId}', '${this._escapeString(value)}');\n`;
+        } else {
+          testCode += `  await page.locator('select').selectOption('${this._escapeString(value)}');\n`;
+        }
+      }
+    }
+
+    testCode += `});\n`;
+
+    writeFileSync(testFilePath, testCode);
+    
+    console.log(`[StableIdStrategy] ✅ Generated test with ${actionEvents.length} actions using stable IDs`);
+    
+    return {
+      success: true,
+      testPath: testFilePath,
+      method: 'Stable ID Injection (Experimental)',
+      actionsGenerated: actionEvents.length
+    };
+  }
+
+  _escapeString(text) {
+    return text.replace(/'/g, "\\'").replace(/\n/g, '\\n');
+  }
+
+  _generateSemanticSelector(elementDesc) {
+    // Parse element description like "Login button", "Email textbox", "Our people link"
+    const desc = elementDesc.toLowerCase();
+    
+    // Extract role and name
+    let role = 'locator';
+    let name = elementDesc;
+    
+    if (desc.includes('button')) {
+      role = 'button';
+      name = elementDesc.replace(/\s*button\s*/gi, '').trim();
+    } else if (desc.includes('link')) {
+      role = 'link';
+      name = elementDesc.replace(/\s*link\s*/gi, '').trim();
+    } else if (desc.includes('textbox')) {
+      role = 'textbox';
+      name = elementDesc.replace(/\s*textbox\s*/gi, '').trim();
+    } else if (desc.includes('checkbox')) {
+      role = 'checkbox';
+      name = elementDesc.replace(/\s*checkbox\s*/gi, '').trim();
+    } else if (desc.includes('combobox') || desc.includes('dropdown') || desc.includes('select')) {
+      role = 'combobox';
+      name = elementDesc.replace(/\s*(combobox|dropdown|select)\s*/gi, '').trim();
+    }
+    
+    if (role !== 'locator' && name) {
+      return `page.getByRole('${role}', { name: '${this._escapeString(name)}' })`;
+    } 
+      // Generic fallback - try text match
+      return `page.getByText('${this._escapeString(elementDesc)}')`;
+    
+  }
+}

package/src/runtime/stable-id-runtime.js

@@ -0,0 +1,248 @@
+/**
+ * StableIdRuntime - Re-inject stable IDs during test execution
+ * 
+ * MUST use EXACT SAME algorithm as mcps/browser/src/stable-id-inject.js
+ * This code runs in the browser context where browser globals are available
+ */
+/* global document, window, URL */
+export class StableIdRuntime {
+  static async beforeEach(page) {
+    await this.injectStableIds(page);
+    page.on('load', async () => {
+      await this.injectStableIds(page);
+    });
+  }
+
+  static async afterNavigation(page) {
+    // Wait for any pending navigation to complete
+    await page.waitForLoadState('domcontentloaded').catch(() => {});
+    await this.injectStableIds(page);
+  }
+  
+  static async clickWithRetry(page, stableId, options = {}) {
+    const timeout = options.timeout || 10000;
+    const selector = `[data-zibby-id="${stableId}"]`;
+    const startTime = Date.now();
+    
+    while (Date.now() - startTime < timeout) {
+      await this.injectStableIds(page);
+      
+      const el = page.locator(selector);
+      if (await el.count() > 0) {
+        try {
+          await el.click({ timeout: 2000 });
+          return;
+        } catch (e) {
+          // If element is covered, try force click
+          if (e.message.includes('intercepts pointer')) {
+            await el.click({ force: true });
+            return;
+          }
+        }
+      }
+      
+      await page.waitForTimeout(200);
+    }
+    
+    throw new Error(`Element ${selector} not found after ${timeout}ms`);
+  }
+  
+  static async fillWithRetry(page, stableId, value, timeout = 10000) {
+    const selector = `[data-zibby-id="${stableId}"]`;
+    const startTime = Date.now();
+    
+    while (Date.now() - startTime < timeout) {
+      await this.injectStableIds(page);
+      
+      const el = page.locator(selector);
+      if (await el.count() > 0) {
+        await el.fill(value);
+        return;
+      }
+      
+      await page.waitForTimeout(200);
+    }
+    
+    throw new Error(`Element ${selector} not found after ${timeout}ms`);
+  }
+  
+  static async selectWithRetry(page, stableId, value, timeout = 10000) {
+    const selector = `[data-zibby-id="${stableId}"]`;
+    const startTime = Date.now();
+    
+    while (Date.now() - startTime < timeout) {
+      await this.injectStableIds(page);
+      
+      const el = page.locator(selector);
+      if (await el.count() > 0) {
+        await el.selectOption(value);
+        return;
+      }
+      
+      await page.waitForTimeout(200);
+    }
+    
+    throw new Error(`Element ${selector} not found after ${timeout}ms`);
+  }
+
+  static async injectStableIds(page) {
+    try {
+      await page.evaluate(() => {
+      // EXACT SAME algorithm as stable-id-inject.js
+      
+      function getSemanticLabel(el) {
+        if (el.getAttribute('aria-label')) return el.getAttribute('aria-label').trim();
+        
+        const labelledBy = el.getAttribute('aria-labelledby');
+        if (labelledBy) {
+          const labelEl = document.getElementById(labelledBy);
+          if (labelEl) return labelEl.textContent.trim();
+        }
+        
+        if (el.id) {
+          const label = document.querySelector(`label[for="${el.id}"]`);
+          if (label) return label.textContent.trim();
+        }
+        
+        const parentLabel = el.closest('label');
+        if (parentLabel) {
+          const clone = parentLabel.cloneNode(true);
+          clone.querySelectorAll('input, select, textarea').forEach(e => e.remove());
+          const text = clone.textContent.trim();
+          if (text) return text;
+        }
+        
+        if (el.placeholder) return el.placeholder;
+        
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'button' || tag === 'a' || el.getAttribute('role') === 'button') {
+          return (el.textContent || '').trim().slice(0, 50);
+        }
+        
+        if (el.title) return el.title;
+        
+        if (tag === 'input' && (el.type === 'submit' || el.type === 'button')) {
+          return el.value || '';
+        }
+        
+        return '';
+      }
+
+      function getSemanticContext(el) {
+        const context = [];
+        
+        const form = el.closest('form');
+        if (form) {
+          if (form.id) context.push(`form#${  form.id}`);
+          else if (form.name) context.push(`form[name=${  form.name  }]`);
+          else if (form.action) {
+            try {
+              const action = new URL(form.action, window.location.origin).pathname;
+              context.push(`form[action=${  action  }]`);
+            } catch {
+              context.push(`form[action=${  form.getAttribute('action')  }]`);
+            }
+          } else {
+            const forms = document.querySelectorAll('form');
+            const index = Array.from(forms).indexOf(form);
+            context.push(`form:nth(${  index  })`);
+          }
+        }
+        
+        const landmark = el.closest('header, nav, main, footer, aside, [role="banner"], [role="navigation"], [role="main"], [role="contentinfo"]');
+        if (landmark) {
+          const tag = landmark.tagName.toLowerCase();
+          const role = landmark.getAttribute('role');
+          context.push(role || tag);
+        }
+        
+        const section = el.closest('section, article, [role="region"]');
+        if (section) {
+          const heading = section.querySelector('h1, h2, h3, h4, h5, h6');
+          if (heading) {
+            context.push(`section:${  heading.textContent.trim().slice(0, 30)}`);
+          }
+        }
+        
+        const fieldset = el.closest('fieldset');
+        if (fieldset) {
+          const legend = fieldset.querySelector('legend');
+          if (legend) {
+            context.push(`fieldset:${  legend.textContent.trim()}`);
+          }
+        }
+        
+        const dialog = el.closest('dialog, [role="dialog"], [role="alertdialog"]');
+        if (dialog) {
+          const title = dialog.querySelector('[role="heading"], h1, h2, h3');
+          if (title) context.push(`dialog:${  title.textContent.trim().slice(0, 30)}`);
+          else context.push('dialog');
+        }
+        
+        return context.join('/');
+      }
+
+      function computeStableId(el) {
+        const tag = el.tagName.toLowerCase();
+        const id = el.id || '';
+        const name = el.name || '';
+        const type = el.type || '';
+        const role = el.getAttribute('role') || '';
+        
+        let href = '';
+        if (el.href) {
+          try {
+            href = new URL(el.href, window.location.origin).pathname.slice(0, 50);
+          } catch {
+            href = el.getAttribute('href')?.slice(0, 50) || '';
+          }
+        }
+        
+        const label = getSemanticLabel(el).slice(0, 50).replace(/\s+/g, ' ');
+        const context = getSemanticContext(el);
+        
+        const sig = [tag, id, name, type, role, href, label, context].join('|');
+        
+        let hash = 5381;
+        for (let i = 0; i < sig.length; i++) {
+          hash = ((hash << 5) + hash) ^ sig.charCodeAt(i);
+        }
+        
+        return `zibby-${  (hash >>> 0).toString(36)}`;
+      }
+
+      const selectors = [
+        'button', 'a', 'input', 'select', 'textarea',
+        'label[for]',
+        '[role="button"]', '[role="link"]', '[role="textbox"]',
+        '[role="checkbox"]', '[role="radio"]', '[role="combobox"]',
+        '[role="menuitem"]', '[role="tab"]', '[role="option"]',
+        '[role="switch"]', '[role="slider"]',
+        '[onclick]', '[data-action]'
+      ].join(', ');
+
+      const idCounts = new Map();
+      let count = 0;
+
+      document.querySelectorAll(selectors).forEach((el) => {
+        const style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden') return;
+        
+        let stableId = computeStableId(el);
+        
+        const baseId = stableId;
+        const existing = idCounts.get(baseId) || 0;
+        if (existing > 0) stableId = `${baseId  }-${  existing}`;
+        idCounts.set(baseId, existing + 1);
+        
+        el.setAttribute('data-zibby-id', stableId);
+        count++;
+      });
+
+      console.log(`[Zibby] Injected ${count} stable IDs`);
+    });
+    } catch (_e) {
+      // Navigation destroyed context - this is OK, IDs will be injected on next retry
+    }
+  }
+}

package/src/runtime/verification/base.js

@@ -0,0 +1,44 @@
+/**
+ * Base class for test verification strategies
+ * Defines the interface that all verification strategies must implement
+ */
+export class TestVerificationStrategy {
+  /**
+   * Verify a generated test
+   * @param {Object} context - Verification context
+   * @param {string} context.testFilePath - Path to test file
+   * @param {string} context.cwd - Current working directory
+   * @param {number} context.timeout - Test timeout in ms
+   * @returns {Promise<Object>} - { success: boolean, passed: number, failed: number, errorDetails?: string }
+   */
+  async verify(_context) {
+    throw new Error('TestVerificationStrategy.verify() must be implemented');
+  }
+
+  /**
+   * Check if this strategy can verify the test
+   * @param {Object} context - Same context as verify()
+   * @returns {boolean}
+   */
+  canVerify(_context) {
+    throw new Error('TestVerificationStrategy.canVerify() must be implemented');
+  }
+
+  /**
+   * Get strategy name for logging
+   * @returns {string}
+   */
+  getName() {
+    throw new Error('TestVerificationStrategy.getName() must be implemented');
+  }
+
+  /**
+   * Get strategy priority (higher = try first)
+   * @returns {number}
+   */
+  getPriority() {
+    return 0;
+  }
+}
+
+export default TestVerificationStrategy;