@sridharkikkeri/playwright-common 1.0.19 → 1.0.22

package/src/core/selfhealing/ElementProfileStore.ts

@@ -0,0 +1,76 @@
+import { Locator } from '@playwright/test';
+
+export interface ElementProfile {
+    selector: string;
+    intent: string;
+    attributes: Record<string, string>;
+    lastHealedSelector?: string;
+    healingFailed?: boolean;
+    failureType?: string;
+}
+
+/**
+ * Stores and manages element profiles for self-healing.
+ * Captured durante successful runs to be used as a baseline for healing.
+ */
+export class ElementProfileStore {
+    private profiles: Map<string, ElementProfile> = new Map();
+
+    private getKey(pageName: string, intent: string): string {
+        return `${pageName}:${intent}`;
+    }
+
+    /**
+     * Captures the profile of a successful locator.
+     */
+    async captureProfile(locator: Locator, pageName: string, intent: string): Promise<void> {
+        const key = this.getKey(pageName, intent);
+        try {
+            const attributes = await locator.evaluate((el) => {
+                const attrs: Record<string, string> = {};
+                Array.from(el.attributes).forEach(attr => {
+                    attrs[attr.name] = attr.value;
+                });
+                attrs['text'] = el.textContent?.trim() || '';
+                attrs['tag'] = el.tagName.toLowerCase();
+                return attrs;
+            });
+
+            this.profiles.set(key, {
+                selector: locator.toString(),
+                intent,
+                attributes
+            });
+        } catch {
+            // Ignore if element is gone or evaluation fails during capture
+        }
+    }
+
+    getProfile(pageName: string, intent: string): ElementProfile | undefined {
+        return this.profiles.get(this.getKey(pageName, intent));
+    }
+
+    getHealedSelector(pageName: string, intent: string): string | undefined {
+        return this.profiles.get(this.getKey(pageName, intent))?.lastHealedSelector;
+    }
+
+    updateHealedSelector(pageName: string, intent: string, selector: string): void {
+        const profile = this.getProfile(pageName, intent);
+        if (profile) {
+            profile.lastHealedSelector = selector;
+            profile.healingFailed = false;
+        }
+    }
+
+    markHealingFailed(pageName: string, intent: string, failureType: string): void {
+        const profile = this.getProfile(pageName, intent);
+        if (profile) {
+            profile.healingFailed = true;
+            profile.failureType = failureType;
+        }
+    }
+
+    hasHealingFailed(pageName: string, intent: string): boolean {
+        return this.profiles.get(this.getKey(pageName, intent))?.healingFailed || false;
+    }
+}

package/src/core/selfhealing/LocatorHealing.ts

@@ -0,0 +1,84 @@
+import { Page, Locator } from '@playwright/test';
+import { ElementProfile } from './ElementProfileStore';
+import { Logger } from '../utils/Logger';
+
+/**
+ * AI-powered logic to heal failing locators using element profiles.
+ */
+export class LocatorHealing {
+  public lastFailureType: string | null = null;
+
+  constructor(private page: Page) { }
+
+  /**
+   * Evaluates a selector string into a Playwright Locator.
+   */
+  evaluateLocatorPublic(selector: string): Locator {
+    return this.page.locator(selector);
+  }
+
+  /**
+   * Orchestrates the AI healing process.
+   * @param originalSelector The broken selector.
+   * @param intent The intended action (for context).
+   * @param error The original error encountered.
+   * @param profile The historical fingerprint of the element.
+   */
+  async healWithAI(
+    originalSelector: string,
+    intent: string,
+    error: Error | null,
+    profile?: ElementProfile
+  ): Promise<string | null> {
+    Logger.info(`🤖 Starting AI healing for: ${intent}`);
+
+    if (!profile) {
+      Logger.error(`❌ No profile found for ${intent}. AI cannot heal without a baseline.`);
+      this.lastFailureType = 'NO_PROFILE';
+      return null;
+    }
+
+    // In a real implementation, this would call an LLM with the profile and current DOM.
+    // For now, we simulate a smart recovery logic based on the profile attributes.
+    try {
+      const attributes = profile.attributes;
+
+      // Strategy 1: Try healing via Text content if available
+      if (attributes['text']) {
+        const textSelector = `text="${attributes['text']}"`;
+        const count = await this.page.locator(textSelector).count();
+        if (count === 1) {
+          Logger.info(`✅ Healed using Text content: ${textSelector}`);
+          return textSelector;
+        }
+      }
+
+      // Strategy 2: Try healing via specific attributes (id, data-testid, etc.)
+      const criticalAttrs = ['data-testid', 'id', 'name', 'aria-label'];
+      for (const attr of criticalAttrs) {
+        if (attributes[attr]) {
+          const attrSelector = `[${attr}="${attributes[attr]}"]`;
+          const count = await this.page.locator(attrSelector).count();
+          if (count === 1) {
+            Logger.info(`✅ Healed using Attribute: ${attrSelector}`);
+            return attrSelector;
+          }
+        }
+      }
+
+      this.lastFailureType = 'AI_RECOVERY_FAILED';
+      return null;
+    } catch {
+      this.lastFailureType = 'HEALING_ERROR';
+      return null;
+    }
+  }
+
+  /**
+   * Legacy heal method (kept for compatibility or simple fixes).
+   */
+  static heal(page: Page, locator: Locator): Locator {
+    Logger.error(`Locator failed: ${locator.toString()}`);
+    return locator;
+  }
+}

package/src/core/utils/ErrorUtils.ts

@@ -0,0 +1,21 @@
+/**
+ * Utility class for handling and parsing Playwright errors.
+ */
+export class ErrorUtils {
+    /**
+     * Converts a value to a standard Error object.
+     */
+    static toError(error: unknown): Error {
+        if (error instanceof Error) return error;
+        return new Error(String(error));
+    }
+
+    /**
+     * Extracts a clean message from a Playwright error.
+     */
+    static getErrorMessage(error: unknown): string {
+        const err = this.toError(error);
+        // Remove stack trace and other noise if necessary
+        return err.message.split('\n')[0];
+    }
+}

package/src/core/utils/Logger.ts

@@ -0,0 +1,14 @@
+
+/**
+ * Simple logger utility for framework-level logging.
+ */
+export class Logger {
+  /**
+   * Logs an informational message.
+   */
+  static info(msg: string) { console.log(`[INFO] ${msg}`); }
+  /**
+   * Logs an error message.
+   */
+  static error(msg: string) { console.error(`[ERROR] ${msg}`); }
+}

package/src/core/visual/VisualTesting.ts

@@ -0,0 +1,95 @@
+import { Page, Locator, expect } from '@playwright/test';
+import { AllureUtil } from '../reporting/AllureUtil';
+
+export interface VisualCompareOptions {
+    /** Maximum allowed pixel difference ratio (0-1). Default: 0.01 (1%) */
+    threshold?: number;
+    /** Mask dynamic elements before comparison */
+    mask?: Locator[];
+    /** Full page screenshot vs viewport only */
+    fullPage?: boolean;
+    /** Custom snapshot name */
+    name?: string;
+}
+
+/**
+ * Visual regression testing utility using Playwright's built-in snapshot comparison.
+ * Integrates with Allure reporting for diff visualization.
+ */
+export class VisualTesting {
+    constructor(private page: Page) {}
+
+    /**
+     * Compare full page screenshot against baseline.
+     */
+    async compareFullPage(options: VisualCompareOptions = {}): Promise<void> {
+        const name = options.name || 'full-page';
+        
+        await AllureUtil.step(`Visual Check: ${name}`, async () => {
+            try {
+                await expect(this.page).toHaveScreenshot(`${name}.png`, {
+                    fullPage: options.fullPage ?? true,
+                    mask: options.mask,
+                    maxDiffPixelRatio: options.threshold ?? 0.01,
+                });
+                AllureUtil.attachText('Visual Check', `✅ Passed: ${name}`);
+            } catch (error) {
+                AllureUtil.attachText('Visual Check', `❌ Failed: ${name}`);
+                throw error;
+            }
+        });
+    }
+
+    /**
+     * Compare specific element screenshot against baseline.
+     */
+    async compareElement(
+        locator: Locator,
+        options: VisualCompareOptions = {}
+    ): Promise<void> {
+        const name = options.name || 'element';
+        
+        await AllureUtil.step(`Visual Check: ${name}`, async () => {
+            try {
+                await expect(locator).toHaveScreenshot(`${name}.png`, {
+                    maxDiffPixelRatio: options.threshold ?? 0.01,
+                });
+                AllureUtil.attachText('Visual Check', `✅ Passed: ${name}`);
+            } catch (error) {
+                AllureUtil.attachText('Visual Check', `❌ Failed: ${name}`);
+                throw error;
+            }
+        });
+    }
+
+    /**
+     * Compare viewport screenshot (visible area only).
+     */
+    async compareViewport(options: VisualCompareOptions = {}): Promise<void> {
+        const name = options.name || 'viewport';
+        
+        await AllureUtil.step(`Visual Check: ${name}`, async () => {
+            try {
+                await expect(this.page).toHaveScreenshot(`${name}.png`, {
+                    fullPage: false,
+                    mask: options.mask,
+                    maxDiffPixelRatio: options.threshold ?? 0.01,
+                });
+                AllureUtil.attachText('Visual Check', `✅ Passed: ${name}`);
+            } catch (error) {
+                AllureUtil.attachText('Visual Check', `❌ Failed: ${name}`);
+                throw error;
+            }
+        });
+    }
+
+    /**
+     * Take baseline screenshot (use --update-snapshots flag to update).
+     */
+    async captureBaseline(name: string, fullPage = true): Promise<void> {
+        await AllureUtil.step(`Capture Baseline: ${name}`, async () => {
+            const screenshot = await this.page.screenshot({ fullPage });
+            AllureUtil.attachImage('Baseline', screenshot);
+        });
+    }
+}

package/src/core/wrappers/ElementWrapper.ts

@@ -0,0 +1,211 @@
+import { Locator } from '@playwright/test';
+import { ActionOrchestrator } from '../selfhealing/ActionOrchestrator';
+import { ConfigManager } from '../config/ConfigManager';
+
+/**
+ * Resilient wrapper around Playwright Locator.
+ * Provides all standard interaction methods with integrated self-healing.
+ */
+export class ElementWrapper {
+  private healingEnabled: boolean;
+
+  constructor(
+    private locator: Locator,
+    private orchestrator: ActionOrchestrator,
+    healingEnabled?: boolean
+  ) {
+    // Default to the value in framework.config.json if not specified
+    this.healingEnabled = healingEnabled !== undefined
+      ? healingEnabled
+      : ConfigManager.getConfig().healingEnabled;
+  }
+
+  /**
+   * Enables or disables self-healing for this element instance or action chain.
+   * @param enabled Whether healing should be enabled
+   */
+  withHealing(enabled: boolean): ElementWrapper {
+    this.healingEnabled = enabled;
+    return this;
+  }
+
+  /**
+   * Internal executor that delegates to the healing orchestrator.
+   */
+  private async exec(
+    action: (l: Locator) => Promise<any>,
+    intent: string
+  ) {
+    await this.orchestrator.runWithHealing(this.locator, intent, action, this.healingEnabled);
+  }
+
+  /* ===============================
+   * Interaction API
+   * =============================== */
+
+  async click(intent = 'click') {
+    await this.exec(l => l.click(), intent);
+  }
+
+  async dblClick(intent = 'double click') {
+    await this.exec(l => l.dblclick(), intent);
+  }
+
+  async rightClick(intent = 'right click') {
+    await this.exec(l => l.click({ button: 'right' }), intent);
+  }
+
+  async fill(value: string, intent?: string) {
+    await this.exec(l => l.fill(value), intent || `fill: ${value}`);
+  }
+
+  async type(text: string, intent?: string) {
+    await this.exec(
+      l => l.pressSequentially(text),
+      intent || `type: ${text}`
+    );
+  }
+
+  async press(key: string, intent?: string) {
+    await this.exec(
+      l => l.press(key),
+      intent || `press: ${key}`
+    );
+  }
+
+  async check(intent = 'check') {
+    await this.exec(l => l.check(), intent);
+  }
+
+  async uncheck(intent = 'uncheck') {
+    await this.exec(l => l.uncheck(), intent);
+  }
+
+  async hover(intent = 'hover') {
+    await this.exec(l => l.hover(), intent);
+  }
+
+  async selectOption(value: string | string[], intent?: string) {
+    await this.exec(
+      l => l.selectOption(value),
+      intent || `selectOption: ${value}`
+    );
+  }
+
+  /* ===============================
+   * Retrieval API
+   * =============================== */
+
+  async getText(intent = 'getText'): Promise<string> {
+    let text = '';
+    await this.exec(async l => {
+      text = (await l.textContent()) ?? '';
+    }, intent);
+    return text;
+  }
+
+  async getInnerText(intent = 'getInnerText'): Promise<string> {
+    let text = '';
+    await this.exec(async l => {
+      text = await l.innerText();
+    }, intent);
+    return text;
+  }
+
+  async getAllTextContents(): Promise<string[]> {
+    return await this.locator.allTextContents();
+  }
+
+  async getAttribute(name: string): Promise<string | null> {
+    return await this.locator.getAttribute(name);
+  }
+
+  async getValue(): Promise<string> {
+    return await this.locator.inputValue();
+  }
+
+  /* ===============================
+   * State API
+   * =============================== */
+
+  async isVisible(): Promise<boolean> {
+    return await this.locator.isVisible();
+  }
+
+  async isHidden(): Promise<boolean> {
+    return await this.locator.isHidden();
+  }
+
+  async isEnabled(): Promise<boolean> {
+    return await this.locator.isEnabled();
+  }
+
+  async isDisabled(): Promise<boolean> {
+    return await this.locator.isDisabled();
+  }
+
+  async isChecked(): Promise<boolean> {
+    return await this.locator.isChecked();
+  }
+
+  async isEditable(): Promise<boolean> {
+    return await this.locator.isEditable();
+  }
+
+  /* ===============================
+   * Wait API
+   * =============================== */
+
+  async waitForVisible(timeout = 5000) {
+    await this.exec(
+      l => l.waitFor({ state: 'visible', timeout }),
+      'waitForVisible'
+    );
+  }
+
+  async waitForHidden(timeout = 5000) {
+    await this.exec(
+      l => l.waitFor({ state: 'hidden', timeout }),
+      'waitForHidden'
+    );
+  }
+
+  async waitForEnabled(timeout = 5000) {
+    await this.exec(
+      async l => {
+        await l.waitFor({ state: 'attached', timeout });
+        await l.isEnabled();
+      },
+      'waitForEnabled'
+    );
+  }
+
+  async waitForDetached(timeout = 5000) {
+    await this.exec(
+      l => l.waitFor({ state: 'detached', timeout }),
+      'waitForDetached'
+    );
+  }
+
+  /* ===============================
+   * Misc
+   * =============================== */
+
+  async scrollIntoView(intent = 'scrollIntoView') {
+    await this.exec(
+      l => l.scrollIntoViewIfNeeded(),
+      intent
+    );
+  }
+
+  async focus(intent = 'focus') {
+    await this.exec(l => l.focus(), intent);
+  }
+
+  async blur(intent = 'blur') {
+    await this.exec(
+      l => l.evaluate(e => (e as HTMLElement).blur()),
+      intent
+    );
+  }
+}

package/src/fixtures/fixtures.ts

@@ -0,0 +1,90 @@
+import { test as base } from '@playwright/test';
+import { ActionOrchestrator } from '../core/selfhealing/ActionOrchestrator';
+import { ApiClient } from '../core/api/ApiClient';
+import { AllureUtil } from '../core/reporting/AllureUtil';
+import { LoginPage } from '../quality/pages/LoginPage';
+
+/**
+ * Defines the custom fixtures available in the framework.
+ */
+export type FrameworkFixtures = {
+    /** High-fidelity UI action orchestrator with AI healing */
+    orchestrator: ActionOrchestrator;
+    /** Robust API client with reporting and auth support */
+    apiClient: ApiClient;
+    /** Pre-instantiated LoginPage */
+    loginPage: LoginPage;
+    /** The current test locale */
+    locale: string;
+    /** Information about the current test retry state */
+    retryInfo: { current: number; max: number };
+};
+
+/**
+ * Extended Playwright test object with enterprise fixtures.
+ */
+export const test = base.extend<FrameworkFixtures>({
+    /* ----------------------------------------
+     * UI Orchestrator
+     * ---------------------------------------- */
+    orchestrator: async ({ page }, use, testInfo) => {
+        const orchestrator = new ActionOrchestrator(page, {
+            pageName: testInfo.title // Initially use test title as context
+        });
+        await use(orchestrator);
+    },
+
+    /* ----------------------------------------
+     * API Client
+     * ---------------------------------------- */
+    apiClient: async ({ }, use) => {
+        const client = new ApiClient(process.env.API_BASE_URL || '');
+        await client.init();
+        await use(client);
+        await client.dispose();
+    },
+
+    /* ----------------------------------------
+     * Page Objects
+     * ---------------------------------------- */
+    loginPage: async ({ page, orchestrator }, use) => {
+        await use(new LoginPage(page, orchestrator));
+    },
+
+    /* ----------------------------------------
+     * Metadata & State
+     * ---------------------------------------- */
+    locale: async ({ }, use) => {
+        const locale = process.env.LOCALE || 'en';
+        await use(locale);
+    },
+
+    retryInfo: async ({ }, use, testInfo) => {
+        await use({
+            current: testInfo.retry,
+            max: testInfo.project.retries
+        });
+    }
+});
+
+/**
+ * Automatic global hooks for reporting and telemetry.
+ */
+test.afterEach(({ retryInfo }, testInfo) => {
+    // 📊 Auto-attach failure info to Allure
+    if (testInfo.status !== testInfo.expectedStatus) {
+        AllureUtil.attachText(
+            'Test Failure Details',
+            `Error: ${testInfo.error?.message || 'Unknown'}\nStack: ${testInfo.error?.stack || 'N/A'}`
+        );
+    }
+
+    // 🔄 Log flaky test telemetry
+    if (retryInfo.current > 0) {
+        AllureUtil.attachText(
+            'Retry Telemetry',
+            `This test is being retried. Attempt: ${retryInfo.current} / ${retryInfo.max}`
+        );
+        console.warn(`⚠️ Flaky test detected: "${testInfo.title}" (Retry ${retryInfo.current})`);
+    }
+});

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from './core/api/auth/CookieAuth';
+export * from './core/api/auth/AuthStrategy';
+export * from './core/api/auth/OAuth2Auth';
+export * from './core/api/ApiClient';
+export * from './core/reporting/AllureUtil';
+export * from './core/i18n/Localization';
+export * from './core/pages/BasePage';
+export * from './core/wrappers/ElementWrapper';
+export * from './core/selfhealing/LocatorHealing';
+export * from './core/selfhealing/ElementProfileStore';
+export * from './core/selfhealing/ActionOrchestrator';
+export * from './core/config/ConfigManager';
+export * from './core/utils/ErrorUtils';
+export * from './core/utils/Logger';
+export * from './core/visual/VisualTesting';
+export * from './quality/pages/LoginPage';
+export * from './fixtures/fixtures';

package/src/quality/pages/LoginPage.ts

@@ -0,0 +1,36 @@
+import { Page } from '@playwright/test';
+import { BasePage } from '../../core/pages/BasePage';
+import { ActionOrchestrator } from '../../core/selfhealing/ActionOrchestrator';
+
+/**
+ * Example Page Object (LoginPage) using the Resilient ElementWrapper architecture.
+ * Elements are self-healing objects created via this.element().
+ * Supports Dependency Injection for use in Fixtures.
+ */
+export class LoginPage extends BasePage {
+    constructor(page: Page, orchestrator?: ActionOrchestrator) {
+        super(page, { pageName: 'LoginPage', orchestrator });
+    }
+
+    // Define elements as Resilient ElementWrappers
+    private readonly usernameInput = this.element('#username');
+    private readonly passwordInput = this.element('#password');
+    private readonly loginButton = this.element('button[type="submit"]');
+    private readonly errorMessage = this.element('.error-message');
+
+    /**
+     * Performs login. Actions are naturally resilient.
+     */
+    async login(user: string, pass: string) {
+        await this.usernameInput.fill(user, 'Enter Username');
+        await this.passwordInput.fill(pass, 'Enter Password');
+        await this.loginButton.click('Click Login Button');
+    }
+
+    /**
+     * Returns error message.
+     */
+    async getErrorMessage(): Promise<string> {
+        return await this.errorMessage.getText('Get Login Error Message');
+    }
+}

package/src/tests/visual.spec.ts

@@ -0,0 +1,38 @@
+import { test } from '@playwright/test';
+import { VisualTesting } from '../core/visual/VisualTesting';
+
+test.describe('Visual Regression Examples', () => {
+    test('Full page comparison', async ({ page }) => {
+        const visual = new VisualTesting(page);
+        
+        await page.goto('https://playwright.dev');
+        await page.waitForLoadState('networkidle');
+        
+        await visual.compareFullPage({ 
+            name: 'playwright-homepage',
+            threshold: 0.01 
+        });
+    });
+
+    test('Element comparison', async ({ page }) => {
+        const visual = new VisualTesting(page);
+        
+        await page.goto('https://playwright.dev');
+        const header = page.locator('header');
+        
+        await visual.compareElement(header, { 
+            name: 'header-element' 
+        });
+    });
+
+    test('Viewport comparison with masking', async ({ page }) => {
+        const visual = new VisualTesting(page);
+        
+        await page.goto('https://playwright.dev');
+        
+        await visual.compareViewport({
+            name: 'viewport-masked',
+            mask: [page.locator('.theme-toggle')]
+        });
+    });
+});