@sridharkikkeri/playwright-common 1.0.19 → 1.0.22

package/src/core/api/ApiClient.ts

@@ -0,0 +1,289 @@
+import { APIRequestContext, request, APIResponse } from '@playwright/test';
+import { AuthStrategy } from './auth/AuthStrategy';
+import { AllureUtil } from '../reporting/AllureUtil';
+import { Logger } from '../utils/Logger';
+import * as path from 'path';
+import * as fs from 'fs';
+
+/* ======================================================
+ * Types
+ * ====================================================== */
+
+/**
+ * HTTP methods supported by the ApiClient.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/**
+ * Represents a file attachment for multipart requests.
+ */
+export interface FileAttachment {
+  /** The name of the form field. */
+  fieldName: string;
+  /** The absolute or relative path to the file. */
+  filePath: string;
+  /** Optional MIME type of the file. */
+  contentType?: string;
+}
+
+/**
+ * Configuration options for an API request.
+ */
+export interface ApiRequestOptions {
+  /** Custom headers to include in the request. */
+  headers?: Record<string, string>;
+  /** URL query parameters. */
+  queryParams?: Record<string, string | number>;
+  /** Request body for POST, PUT, and PATCH requests. */
+  body?: any;
+  /** Optional files for multipart/form-data requests. */
+  files?: FileAttachment[];
+  /** Timeout in milliseconds for this specific request. */
+  timeoutMs?: number;
+  /** Number of times to retry the request if it fails. */
+  retries?: number;
+}
+
+/**
+ * Standardized API response structure.
+ * @template T The expected type of the response body.
+ */
+export interface ApiResponse<T> {
+  /** HTTP status code. */
+  status: number;
+  /** Response headers. */
+  headers: Record<string, string>;
+  /** Decoded response body or null if parsing fails. */
+  body: T | null;
+  /** The raw Playwright APIResponse object. */
+  raw: APIResponse;
+  /** Time taken for the request in milliseconds. */
+  durationMs: number;
+}
+
+/* ======================================================
+ * ApiClient
+ * ====================================================== */
+
+/**
+ * A generic API client built on top of Playwright's APIRequestContext.
+ * Provides features like automatic authentication, retries, and Allure reporting.
+ */
+export class ApiClient {
+  private context!: APIRequestContext;
+
+  /**
+   * @param baseUrl The base URL for all requests.
+   * @param auth Optional authentication strategy.
+   * @param defaultTimeoutMs Default timeout for requests (default 30s).
+   * @param defaultRetries Default number of retries for failed requests (default 0).
+   */
+  constructor(
+    private readonly baseUrl: string,
+    private readonly auth?: AuthStrategy,
+    private readonly defaultTimeoutMs = 30_000,
+    private readonly defaultRetries = 0
+  ) { }
+
+  /* ------------------------------------------------------
+   * Lifecycle
+   * ------------------------------------------------------ */
+
+  /**
+   * Initializes the API context and applies the authentication strategy if provided.
+   */
+  async init(): Promise<void> {
+    this.context = await request.newContext({
+      baseURL: this.baseUrl
+    });
+
+    if (this.auth) {
+      await this.auth.apply(this.context);
+    }
+  }
+
+  /**
+   * Disposes of the API context, cleaning up resources.
+   */
+  async dispose(): Promise<void> {
+    if (this.context) {
+      await this.context.dispose();
+    }
+  }
+
+  /* ------------------------------------------------------
+   * Public HTTP methods
+   * ------------------------------------------------------ */
+
+  /**
+   * Performs a GET request.
+   */
+  get<T>(url: string, options?: ApiRequestOptions) {
+    return this.request<T>('GET', url, options);
+  }
+
+  /**
+   * Performs a POST request.
+   */
+  post<T>(url: string, body?: any, options?: ApiRequestOptions) {
+    return this.request<T>('POST', url, { ...options, body });
+  }
+
+  /**
+   * Performs a PUT request.
+   */
+  put<T>(url: string, body?: any, options?: ApiRequestOptions) {
+    return this.request<T>('PUT', url, { ...options, body });
+  }
+
+  /**
+   * Performs a PATCH request.
+   */
+  patch<T>(url: string, body?: any, options?: ApiRequestOptions) {
+    return this.request<T>('PATCH', url, { ...options, body });
+  }
+
+  /**
+   * Performs a DELETE request.
+   */
+  delete<T>(url: string, options?: ApiRequestOptions) {
+    return this.request<T>('DELETE', url, options);
+  }
+
+  /* ------------------------------------------------------
+   * Core request executor
+   * ------------------------------------------------------ */
+
+  /**
+   * Core method to execute an HTTP request with retry logic.
+   * @param method The HTTP method to use.
+   * @param url The endpoint URL (relative to baseUrl).
+   * @param options Request configuration options.
+   * @returns A promise that resolves to an ApiResponse.
+   */
+  async request<T>(
+    method: HttpMethod,
+    url: string,
+    options: ApiRequestOptions = {}
+  ): Promise<ApiResponse<T>> {
+
+    const retries = options.retries ?? this.defaultRetries;
+    const timeout = options.timeoutMs ?? this.defaultTimeoutMs;
+
+    let lastError: any;
+
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        return await this.executeOnce<T>(method, url, options, timeout);
+      } catch (error) {
+        lastError = error;
+        Logger.error(
+          `[API] ${method} ${url} failed (attempt ${attempt + 1})`
+        );
+        if (attempt === retries) throw error;
+      }
+    }
+
+    throw lastError;
+  }
+
+  /* ------------------------------------------------------
+   * Single attempt execution
+   * ------------------------------------------------------ */
+
+  private async executeOnce<T>(
+    method: HttpMethod,
+    url: string,
+    options: ApiRequestOptions,
+    timeout: number
+  ): Promise<ApiResponse<T>> {
+
+    const start = Date.now();
+
+    const isMultipart = !!options.files?.length;
+
+    const response = await this.context.fetch(url, {
+      method,
+      headers: options.headers,
+      params: options.queryParams,
+      timeout,
+      data: isMultipart ? undefined : options.body,
+      multipart: isMultipart ? this.buildMultipart(options) : undefined
+    });
+
+    const duration = Date.now() - start;
+
+    const body = await this.safeParseBody<T>(response);
+
+    // ---------- Allure Logging ----------
+    AllureUtil.attachJson('API Request', {
+      method,
+      url,
+      headers: options.headers,
+      queryParams: options.queryParams,
+      body: options.body,
+      multipart: isMultipart
+    });
+
+    AllureUtil.attachJson('API Response', {
+      status: response.status(),
+      durationMs: duration,
+      body
+    });
+
+    if (response.status() >= 400) {
+      throw new Error(
+        `API failed ${response.status()} ${method} ${url}`
+      );
+    }
+
+    return {
+      status: response.status(),
+      headers: response.headers(),
+      body,
+      raw: response,
+      durationMs: duration
+    };
+  }
+
+  /* ------------------------------------------------------
+   * Helpers
+   * ------------------------------------------------------ */
+
+  private buildMultipart(options: ApiRequestOptions) {
+    const parts: Record<string, any> = {};
+
+    if (options.body) {
+      Object.entries(options.body).forEach(([key, value]) => {
+        parts[key] = String(value);
+      });
+    }
+
+    options.files?.forEach(file => {
+      parts[file.fieldName] = fs.createReadStream(path.resolve(file.filePath));
+    });
+
+    return parts;
+  }
+
+  private async safeParseBody<T>(
+    response: APIResponse
+  ): Promise<T | null> {
+    const contentType = response.headers()['content-type'] || '';
+
+    try {
+      if (contentType.includes('application/json')) {
+        return (await response.json()) as T;
+      }
+
+      if (contentType.includes('text')) {
+        return (await response.text()) as unknown as T;
+      }
+
+      // binary / empty
+      return null;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/core/api/auth/AuthStrategy.ts

@@ -0,0 +1,11 @@
+
+import { APIRequestContext } from '@playwright/test';
+/**
+ * Interface for authentication strategies that can be applied to an APIRequestContext.
+ */
+export interface AuthStrategy {
+  /**
+   * Applies the authentication (e.g., setting headers or cookies) to the given context.
+   */
+  apply(context: APIRequestContext): Promise<void>;
+}

package/src/core/api/auth/CookieAuth.ts

@@ -0,0 +1,36 @@
+
+import { request } from '@playwright/test';
+import { AuthStrategy } from './AuthStrategy';
+
+/**
+ * Authentication strategy using session cookies.
+ * Logs in via a provided URL and saves the session cookies.
+ */
+export class CookieAuth implements AuthStrategy {
+  private cookies: any[] = [];
+
+  constructor(
+    private loginUrl: string,
+    private credentials: Record<string, string>
+  ) { }
+
+  /**
+   * Internal method to perform login and capture cookies.
+   */
+  private async login() {
+    const ctx = await request.newContext();
+    await ctx.post(this.loginUrl, { data: this.credentials });
+    const storage = await ctx.storageState();
+    this.cookies = storage.cookies;
+  }
+
+  /**
+   * Applies the captured cookies to the request context.
+   */
+  async apply(context: any) {
+    if (!this.cookies.length) {
+      await this.login();
+    }
+    await context.addCookies(this.cookies);
+  }
+}

package/src/core/api/auth/OAuth2Auth.ts

@@ -0,0 +1,46 @@
+
+import { request } from '@playwright/test';
+import { AuthStrategy } from './AuthStrategy';
+
+/**
+ * Authentication strategy using OAuth2 Client Credentials flow.
+ */
+export class OAuth2Auth implements AuthStrategy {
+  private token?: string;
+  private expiry = 0;
+
+  constructor(
+    private tokenUrl: string,
+    private clientId: string,
+    private clientSecret: string
+  ) { }
+
+  /**
+   * Fetches a new access token using client credentials.
+   */
+  private async fetchToken() {
+    const ctx = await request.newContext();
+    const res = await ctx.post(this.tokenUrl, {
+      form: {
+        grant_type: 'client_credentials',
+        client_id: this.clientId,
+        client_secret: this.clientSecret
+      }
+    });
+    const body = await res.json();
+    this.token = body.access_token;
+    this.expiry = Date.now() + body.expires_in * 1000;
+  }
+
+  /**
+   * Applies the OAuth2 Bearer token to the request context headers.
+   */
+  async apply(context: any) {
+    if (!this.token || Date.now() > this.expiry) {
+      await this.fetchToken();
+    }
+    await context.setExtraHTTPHeaders({
+      Authorization: `Bearer ${this.token}`
+    });
+  }
+}

package/src/core/config/ConfigManager.ts

@@ -0,0 +1,72 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Interface representing the framework configuration structure.
+ */
+export interface FrameworkConfig {
+    /** Global default for AI self-healing. */
+    healingEnabled: boolean;
+    /** Environment name (dev, staging, prod). */
+    environment?: string;
+    /** Base URL for the application. */
+    baseUrl?: string;
+    /** API base URL. */
+    apiUrl?: string;
+    /** Default timeout in milliseconds. */
+    timeout?: number;
+    /** Number of retries for failed tests. */
+    retries?: number;
+}
+
+/**
+ * Singleton manager for framework-level configuration.
+ * Reads settings from framework.config.json at the project root.
+ */
+export class ConfigManager {
+    private static config: FrameworkConfig | null = null;
+
+    /**
+     * Retrieves the current configuration. Loads it from disk if not already cached.
+     */
+    public static getConfig(): FrameworkConfig {
+        if (!this.config) {
+            this.loadConfig();
+        }
+        return this.config!;
+    }
+
+    /**
+     * Loads the configuration from the framework.config.json file.
+     * Supports environment-specific configs via ENV variable: framework.config.{env}.json
+     * Fallbacks to defaults if the file is missing or invalid.
+     */
+    private static loadConfig(): void {
+        const env = process.env.TEST_ENV || process.env.NODE_ENV || 'dev';
+        const envConfigPath = path.resolve(process.cwd(), `framework.config.${env}.json`);
+        const defaultConfigPath = path.resolve(process.cwd(), 'framework.config.json');
+        const defaultConfig: FrameworkConfig = { healingEnabled: true };
+
+        try {
+            let configPath = defaultConfigPath;
+            
+            // Prefer environment-specific config if exists
+            if (fs.existsSync(envConfigPath)) {
+                configPath = envConfigPath;
+                console.log(`✅ Loaded config for environment: ${env}`);
+            } else if (fs.existsSync(defaultConfigPath)) {
+                console.log(`✅ Loaded default config (no ${env}-specific config found)`);
+            } else {
+                console.warn(`⚠️ No configuration file found. Using defaults.`);
+                this.config = defaultConfig;
+                return;
+            }
+
+            const fileContent = fs.readFileSync(configPath, 'utf8');
+            this.config = { ...defaultConfig, ...JSON.parse(fileContent) };
+        } catch (error) {
+            console.error(`❌ Failed to load framework configuration: ${error}`);
+            this.config = defaultConfig;
+        }
+    }
+}

package/src/core/i18n/Localization.ts

@@ -0,0 +1,34 @@
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Handles localization and internationalization by reading translation files.
+ */
+export class Localization {
+  private static cache: Record<string, any> = {};
+
+  /**
+   * Translates a key using the loaded messages for the given locale.
+   * @param key The translation key.
+   * @param locale The locale to use (default 'en').
+   * @returns The translated message or the key if not found.
+   */
+  static get(key: string, locale = 'en'): string {
+    const data = this.load(locale);
+    return data[key] ?? key;
+  }
+
+  /**
+   * Internal method to load a translation JSON file.
+   * @param locale The locale to load.
+   * @returns The parsed translation data.
+   */
+  private static load(locale: string) {
+    if (!this.cache[locale]) {
+      const file = path.join(__dirname, `${locale}.json`);
+      this.cache[locale] = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    return this.cache[locale];
+  }
+}

package/src/core/i18n/en.json

@@ -0,0 +1,5 @@
+
+{
+  "login.success": "Login successful",
+  "login.error": "Invalid username or password"
+}

package/src/core/pages/BasePage.ts

@@ -0,0 +1,47 @@
+import { Page, Locator } from '@playwright/test';
+import { ActionOrchestrator } from '../selfhealing/ActionOrchestrator';
+import { ElementWrapper } from '../wrappers/ElementWrapper';
+import { ConfigManager } from '../config/ConfigManager';
+
+/**
+ * Base class for all Page Objects.
+ * Provides the 'element()' factory for creating self-healing elements.
+ */
+export abstract class BasePage {
+    protected orchestrator: ActionOrchestrator;
+    protected pageName: string;
+
+    constructor(protected readonly page: Page, options: { pageName?: string; orchestrator?: ActionOrchestrator } = {}) {
+        this.pageName = options.pageName || 'UnknownPage';
+
+        // Support Dependency Injection via constructor (for Fixtures)
+        // Fallback to internal creation (for Manual usage)
+        this.orchestrator = options.orchestrator || new ActionOrchestrator(page);
+
+        // Ensure the orchestrator knows the current page context
+        this.orchestrator.setPageContext(this.pageName);
+    }
+
+    /**
+     * Factory method to create a resilient ElementWrapper.
+     * Elements created via this method are automatically self-healing by default (controlled via framework.config.json).
+     */
+    protected element(selector: string | Locator, healingEnabled: boolean = ConfigManager.getConfig().healingEnabled): ElementWrapper {
+        const loc = typeof selector === 'string' ? this.page.locator(selector) : selector;
+        return new ElementWrapper(loc, this.orchestrator, healingEnabled);
+    }
+
+    /**
+     * Navigates to a URL.
+     */
+    async navigate(url: string) {
+        await this.page.goto(url);
+    }
+
+    /**
+     * Returns current page title.
+     */
+    async title(): Promise<string> {
+        return await this.page.title();
+    }
+}

package/src/core/reporting/AllureUtil.ts

@@ -0,0 +1,35 @@
+
+import { allure } from 'allure-playwright';
+
+/**
+ * Utility for Allure reporting integration.
+ * Provides methods for attaching data and wrapping steps.
+ */
+export class AllureUtil {
+  /**
+   * Attaches JSON data to the Allure report.
+   */
+  static attachJson(name: string, value: any) {
+    void allure.attachment(name, JSON.stringify(value, null, 2), 'application/json');
+  }
+  /**
+   * Attaches plain text to the Allure report.
+   */
+  static attachText(name: string, value: string) {
+    void allure.attachment(name, value, 'text/plain');
+  }
+  /**
+   * Attaches image buffer to the Allure report.
+   */
+  static attachImage(name: string, buffer: Buffer) {
+    void allure.attachment(name, buffer, 'image/png');
+  }
+  /**
+   * Wraps a function in an Allure step.
+   * @param name Name of the step.
+   * @param fn Function to execute.
+   */
+  static step<T>(name: string, fn: () => Promise<T>): Promise<T> {
+    return allure.step(name, fn as () => Promise<void>) as unknown as Promise<T>;
+  }
+}

package/src/core/selfhealing/ActionOrchestrator.ts

@@ -0,0 +1,117 @@
+import { Page, Locator } from '@playwright/test';
+import { LocatorHealing } from './LocatorHealing';
+import { ElementProfileStore } from './ElementProfileStore';
+import { ErrorUtils } from '../utils/ErrorUtils';
+
+/**
+ * Orchestrates UI actions with advanced AI-powered self-healing.
+ * Centralizing this logic ensures SRP and eliminates code duplication.
+ */
+export class ActionOrchestrator {
+    private healing: LocatorHealing;
+    private profileStore: ElementProfileStore;
+    private pageName: string;
+
+    constructor(
+        private page: Page,
+        options: {
+            pageName?: string;
+            healing?: LocatorHealing;
+            profileStore?: ElementProfileStore;
+        } = {}
+    ) {
+        this.pageName = options.pageName || 'DefaultPage';
+        this.healing = options.healing || new LocatorHealing(page);
+        this.profileStore = options.profileStore || new ElementProfileStore();
+    }
+
+    /**
+     * Updates the contextual page name for logging and AI profiling.
+     */
+    setPageContext(pageName: string): void {
+        this.pageName = pageName;
+    }
+
+    /**
+     * Core orchestration logic for self-healing actions.
+     * Exposed for consumption by ElementWrapper.
+     */
+    async runWithHealing(
+        locator: Locator,
+        intent: string,
+        action: (loc: Locator) => Promise<any>,
+        healingEnabled: boolean = true
+    ): Promise<void> {
+        const originalSelector = locator.toString();
+        let originalError: Error | null = null;
+
+        try {
+            await action(locator);
+            // ✅ Success: Capture element profile for future healing
+            await this.profileStore.captureProfile(locator, this.pageName, intent);
+            return;
+        } catch (error) {
+            originalError = ErrorUtils.toError(error);
+            const message = ErrorUtils.getErrorMessage(error);
+            console.log(`❌ Action failed (${intent}): ${message}`);
+
+            if (!healingEnabled) {
+                console.log(`🚫 Self-healing is disabled for this action. Throwing original error.`);
+                throw originalError;
+            }
+        }
+
+        // Step 1: Stability Wait
+        if ((await locator.count()) === 0) {
+            console.log('⏳ Waiting for element to appear...');
+            try {
+                await locator.waitFor({ state: 'attached', timeout: 3000 });
+                await action(locator);
+                console.log('✅ Element recovered via waiting');
+                return;
+            } catch { /* proceed to healing */ }
+        }
+
+        // Step 2: Check failure history
+        if (this.profileStore.hasHealingFailed(this.pageName, intent)) {
+            console.log('❌ Healing previously failed for this element. Skipping AI.');
+            throw originalError;
+        }
+
+        // Step 3: Cached Healed Selector
+        const cached = this.profileStore.getHealedSelector(this.pageName, intent);
+        if (cached) {
+            console.log(`💾 Trying cached healed selector: ${cached}`);
+            try {
+                const healedLoc = this.healing.evaluateLocatorPublic(cached);
+                if ((await healedLoc.count()) === 1) {
+                    await action(healedLoc);
+                    console.log('✅ Recovered via cached selector');
+                    return;
+                }
+            } catch { /* proceed to AI */ }
+        }
+
+        // Step 4: AI Healing
+        const profile = this.profileStore.getProfile(this.pageName, intent);
+        const healedSelector = await this.healing.healWithAI(
+            originalSelector,
+            intent,
+            originalError,
+            profile
+        );
+
+        if (healedSelector) {
+            const healedLoc = this.healing.evaluateLocatorPublic(healedSelector);
+            await action(healedLoc);
+
+            this.profileStore.updateHealedSelector(this.pageName, intent, healedSelector);
+            await this.profileStore.captureProfile(healedLoc, this.pageName, intent);
+            console.log('✅ Recovered via AI Healing');
+            return;
+        }
+
+        this.profileStore.markHealingFailed(this.pageName, intent, this.healing.lastFailureType || 'UNKNOWN');
+        throw originalError;
+    }
+}