qa360 2.1.7 → 2.2.0

package/core/src/pom/loader.ts

@@ -0,0 +1,480 @@
+/**
+ * QA360 Page Object Model (POM) - Loader
+ *
+ * Dynamically loads Page Objects from TypeScript/JavaScript files.
+ *
+ * @see https://qa360.dev/docs/pom
+ */
+
+import { readdir, readFile, stat } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, relative, resolve, extname } from 'path';
+import { pathToFileURL } from 'url';
+
+import type {
+  IPageObject,
+  PageObjectCollection,
+  PageObjectLoaderOptions,
+  PageObjectMetadata,
+  PageObjectRegistry,
+  PageObjectValidationResult,
+} from './types.js';
+
+/**
+ * Default glob pattern for page files
+ */
+const DEFAULT_PATTERN = '**/*.page.{ts,js,mjs,cjs}';
+
+/**
+ * Page Object Loader
+ *
+ * Loads and manages Page Objects from external files.
+ */
+export class PageObjectLoader implements PageObjectRegistry {
+  private cwd: string;
+  private baseUrl: string;
+  private cacheEnabled: boolean;
+  private timeout: number;
+
+  // Registry storage
+  private pages: Map<string, IPageObject> = new Map();
+  private metadata: Map<string, PageObjectMetadata> = new Map();
+
+  // Compiled regex pattern cache
+  private patternCache: Map<string, RegExp> = new Map();
+
+  constructor(options: PageObjectLoaderOptions = {}) {
+    this.cwd = options.cwd || process.cwd();
+    this.baseUrl = options.baseUrl || '';
+    this.cacheEnabled = options.cache !== false;
+    this.timeout = options.timeout || 5000;
+  }
+
+  /**
+   * Get page by name
+   */
+  get(name: string): IPageObject | undefined {
+    return this.pages.get(name);
+  }
+
+  /**
+   * Get page metadata
+   */
+  getMetadata(name: string): PageObjectMetadata | undefined {
+    return this.metadata.get(name);
+  }
+
+  /**
+   * Register a page
+   */
+  register(name: string, page: IPageObject, metadata: PageObjectMetadata): void {
+    this.pages.set(name, page);
+    this.metadata.set(name, metadata);
+  }
+
+  /**
+   * List all registered pages
+   */
+  list(): string[] {
+    return Array.from(this.pages.keys());
+  }
+
+  /**
+   * Clear registry
+   */
+  clear(): void {
+    this.pages.clear();
+    this.metadata.clear();
+  }
+
+  /**
+   * Load page objects from a directory
+   */
+  async loadFromDirectory(
+    directory: string,
+    options: { pattern?: string; recursive?: boolean } = {}
+  ): Promise<PageObjectValidationResult> {
+    const result: PageObjectValidationResult = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      pagesCount: 0,
+    };
+
+    const dirPath = resolve(this.cwd, directory);
+
+    if (!existsSync(dirPath)) {
+      result.valid = false;
+      result.errors.push(`Directory not found: ${dirPath}`);
+      return result;
+    }
+
+    const pattern = options.pattern || DEFAULT_PATTERN;
+    const recursive = options.recursive !== false;
+
+    try {
+      const files = await this.findPageFiles(dirPath, pattern, recursive);
+
+      for (const filePath of files) {
+        const loadResult = await this.loadFromFile(filePath);
+        if (!loadResult.valid) {
+          result.valid = false;
+          result.errors.push(...loadResult.errors);
+        }
+        if (loadResult.warnings.length > 0) {
+          result.warnings.push(...loadResult.warnings);
+        }
+        result.pagesCount += loadResult.loadedCount;
+      }
+    } catch (error) {
+      result.valid = false;
+      result.errors.push(`Failed to load pages: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    return result;
+  }
+
+  /**
+   * Load page objects from a collection config
+   */
+  async loadFromCollection(collection: PageObjectCollection): Promise<PageObjectValidationResult> {
+    // Override baseUrl if provided in collection
+    if (collection.baseUrl) {
+      this.baseUrl = collection.baseUrl;
+    }
+
+    return this.loadFromDirectory(collection.directory, {
+      pattern: collection.pattern,
+      recursive: true,
+    });
+  }
+
+  /**
+   * Load a single page from a file
+   */
+  async loadFromFile(filePath: string): Promise<{
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    loadedCount: number;
+  }> {
+    const result = {
+      valid: true,
+      errors: [] as string[],
+      warnings: [] as string[],
+      loadedCount: 0,
+    };
+
+    const absolutePath = resolve(this.cwd, filePath);
+
+    if (!existsSync(absolutePath)) {
+      result.valid = false;
+      result.errors.push(`File not found: ${absolutePath}`);
+      return result;
+    }
+
+    try {
+      // Clear require cache if not caching
+      if (!this.cacheEnabled) {
+        this.clearRequireCache(absolutePath);
+      }
+
+      // Dynamic import using file:// URL for ES modules
+      const fileUrl = pathToFileURL(absolutePath).href;
+      const module = await import(fileUrl);
+
+      // Extract page classes from the module
+      const loadedCount = this.extractPagesFromModule(module, absolutePath);
+      result.loadedCount = loadedCount;
+
+      if (loadedCount === 0) {
+        result.warnings.push(`No page objects found in: ${filePath}`);
+      }
+    } catch (error) {
+      result.valid = false;
+      result.errors.push(
+        `Failed to load ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * Extract page classes from a module
+   */
+  private extractPagesFromModule(module: any, filePath: string): number {
+    let count = 0;
+
+    for (const [exportName, exportValue] of Object.entries(module)) {
+      // Skip default exports and non-constructor exports
+      if (exportName === 'default' || typeof exportValue !== 'function') {
+        continue;
+      }
+
+      // Check if export is a Page Object class
+      if (this.isPageObjectClass(exportValue)) {
+        try {
+          // Create instance to extract metadata
+          // Use a type assertion for constructor
+          const ctor = exportValue as new (baseUrl?: string) => IPageObject;
+          const instance = new ctor(this.baseUrl);
+
+          if (this.isValidPageObject(instance)) {
+            const metadata = this.extractMetadata(instance, exportName, filePath);
+            this.register(metadata.name, instance, metadata);
+            count++;
+          }
+        } catch (error) {
+          // Failed to instantiate - skip this page
+          console.warn(`Failed to instantiate ${exportName}: ${error}`);
+        }
+      }
+    }
+
+    return count;
+  }
+
+  /**
+   * Check if a class is a Page Object class
+   */
+  private isPageObjectClass(ctor: any): ctor is new (baseUrl?: string) => IPageObject {
+    // Check if constructor has Page Object characteristics
+    const prototype = ctor.prototype;
+
+    // Check for required methods
+    const hasNavigate = typeof prototype.navigate === 'function';
+    const hasUrl = typeof prototype.url === 'string' || typeof prototype.getUrl === 'function';
+
+    return hasNavigate && hasUrl;
+  }
+
+  /**
+   * Check if instance implements IPageObject
+   */
+  private isValidPageObject(instance: any): instance is IPageObject {
+    return (
+      typeof instance.name === 'string' &&
+      typeof instance.url === 'string' &&
+      typeof instance.navigate === 'function' &&
+      typeof instance.selectors === 'object' &&
+      instance.selectors !== null
+    );
+  }
+
+  /**
+   * Extract metadata from page instance
+   */
+  private extractMetadata(
+    instance: IPageObject,
+    className: string,
+    filePath: string
+  ): PageObjectMetadata {
+    const methods: string[] = [];
+
+    // Get all method names from prototype
+    const prototype = Object.getPrototypeOf(instance);
+    for (const key of Object.getOwnPropertyNames(prototype)) {
+      if (key !== 'constructor' && typeof prototype[key] === 'function') {
+        methods.push(key);
+      }
+    }
+
+    return {
+      name: instance.name,
+      filePath,
+      url: instance.url,
+      selectors: { ...instance.selectors },
+      methods,
+      description: (instance as any).description,
+    };
+  }
+
+  /**
+   * Find page files matching pattern
+   */
+  private async findPageFiles(
+    directory: string,
+    pattern: string,
+    recursive: boolean
+  ): Promise<string[]> {
+    const files: string[] = [];
+
+    // Convert glob pattern to regex
+    const regex = this.globToRegex(pattern);
+
+    const entries = await readdir(directory, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(directory, entry.name);
+
+      if (entry.isDirectory() && recursive) {
+        // Recurse into subdirectories
+        const subFiles = await this.findPageFiles(fullPath, pattern, recursive);
+        files.push(...subFiles);
+      } else if (entry.isFile()) {
+        // Check if file matches pattern
+        const relativePath = relative(directory, fullPath);
+        if (regex.test(relativePath)) {
+          files.push(fullPath);
+        }
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Convert glob pattern to regex
+   */
+  private globToRegex(pattern: string): RegExp {
+    // Check cache
+    if (this.patternCache.has(pattern)) {
+      return this.patternCache.get(pattern)!;
+    }
+
+    let regex = pattern
+      // Escape special regex characters except *, ?, **
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      // ** matches any number of directories
+      .replace(/\*\*/g, '.*')
+      // * matches any characters except /
+      .replace(/(?<!\.)\*/g, '[^/]*')
+      // ? matches single character
+      .replace(/\?/g, '.')
+      // {ext1,ext2} syntax
+      .replace(/\{([^}]+)\}/g, (_, alternatives) => {
+        return `(${alternatives.split(',').join('|')})`;
+      });
+
+    regex = `^${regex}$`;
+    const regexObj = new RegExp(regex, 'i');
+
+    this.patternCache.set(pattern, regexObj);
+    return regexObj;
+  }
+
+  /**
+   * Clear require cache for a file
+   */
+  private clearRequireCache(filePath: string): void {
+    const absolutePath = resolve(filePath);
+    const fileUrl = pathToFileURL(absolutePath).href;
+
+    // Clear from import cache
+    // Note: This doesn't work perfectly with ES modules in Node
+    // but helps with some cases
+    try {
+      // @ts-ignore - undocumented API
+      if (require.cache) {
+        delete require.cache[require.resolve(absolutePath)];
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  /**
+   * Validate a page object
+   */
+  async validate(pageName: string): Promise<{
+    valid: boolean;
+    errors: string[];
+  }> {
+    const page = this.get(pageName);
+    const metadata = this.getMetadata(pageName);
+
+    if (!page || !metadata) {
+      return {
+        valid: false,
+        errors: [`Page object not found: ${pageName}`],
+      };
+    }
+
+    const errors: string[] = [];
+
+    // Validate required properties
+    if (!page.name || typeof page.name !== 'string') {
+      errors.push('Page must have a valid "name" property');
+    }
+
+    if (!page.url || typeof page.url !== 'string') {
+      errors.push('Page must have a valid "url" property');
+    }
+
+    if (!page.selectors || typeof page.selectors !== 'object') {
+      errors.push('Page must have a "selectors" object');
+    }
+
+    // Validate required methods
+    if (typeof page.navigate !== 'function') {
+      errors.push('Page must implement "navigate()" method');
+    }
+
+    if (typeof page.waitForReady !== 'function') {
+      errors.push('Page must implement "waitForReady()" method');
+    }
+
+    if (typeof page.isDisplayed !== 'function') {
+      errors.push('Page must implement "isDisplayed()" method');
+    }
+
+    if (typeof page.getUrl !== 'function') {
+      errors.push('Page must implement "getUrl()" method');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Get all page metadata
+   */
+  getAllMetadata(): PageObjectMetadata[] {
+    return Array.from(this.metadata.values());
+  }
+
+  /**
+   * Export pages as JSON (for debugging)
+   */
+  toJSON(): Record<string, PageObjectMetadata> {
+    const obj: Record<string, PageObjectMetadata> = {};
+    for (const [name, metadata] of this.metadata) {
+      obj[name] = metadata;
+    }
+    return obj;
+  }
+}
+
+/**
+ * Create a Page Object Loader
+ */
+export function createPageObjectLoader(
+  options?: PageObjectLoaderOptions
+): PageObjectLoader {
+  return new PageObjectLoader(options);
+}
+
+/**
+ * Default singleton loader instance
+ */
+let defaultLoader: PageObjectLoader | null = null;
+
+/**
+ * Get or create default loader
+ */
+export function getDefaultLoader(options?: PageObjectLoaderOptions): PageObjectLoader {
+  if (!defaultLoader) {
+    defaultLoader = new PageObjectLoader(options);
+  }
+  return defaultLoader;
+}
+
+/**
+ * Reset default loader (useful for testing)
+ */
+export function resetDefaultLoader(): void {
+  defaultLoader = null;
+}

package/core/src/pom/types.ts

@@ -0,0 +1,146 @@
+/**
+ * QA360 Page Object Model (POM) - Types
+ *
+ * Support for importing Page Objects from TypeScript/JavaScript files
+ * to be referenced in YAML pack configurations.
+ *
+ * @see https://qa360.dev/docs/pom
+ */
+
+/**
+ * Page Object class interface
+ * All page objects must implement this interface
+ */
+export interface IPageObject {
+  /** Unique page identifier */
+  readonly name: string;
+
+  /** Page URL (relative or absolute) */
+  readonly url: string;
+
+  /** Page selectors for elements */
+  readonly selectors: Record<string, string>;
+
+  /** Navigate to this page */
+  navigate(): Promise<void>;
+
+  /** Wait for page to be ready */
+  waitForReady(): Promise<void>;
+
+  /** Check if page is displayed */
+  isDisplayed(): Promise<boolean>;
+
+  /** Get page URL */
+  getUrl(): string;
+}
+
+/**
+ * Page Object metadata (extracted from class)
+ */
+export interface PageObjectMetadata {
+  /** Page name */
+  name: string;
+
+  /** File path where page is defined */
+  filePath: string;
+
+  /** Page URL pattern */
+  url: string;
+
+  /** Available selectors */
+  selectors: Record<string, string>;
+
+  /** Available methods */
+  methods: string[];
+
+  /** Description */
+  description?: string;
+}
+
+/**
+ * Page Object reference in YAML
+ */
+export interface PageObjectReference {
+  /** Page object name (class name) */
+  name: string;
+
+  /** Optional alias in pack */
+  as?: string;
+
+  /** Override URL if needed */
+  url?: string;
+
+  /** Override selectors if needed */
+  selectors?: Record<string, string>;
+}
+
+/**
+ * POM Collection configuration
+ */
+export interface PageObjectCollection {
+  /** Directory containing page objects */
+  directory: string;
+
+  /** Page objects to load */
+  pages: string[];
+
+  /** Base URL for relative URLs */
+  baseUrl?: string;
+
+  /** Glob pattern for matching page files */
+  pattern?: string;
+}
+
+/**
+ * Loaded Page Object Registry
+ */
+export interface PageObjectRegistry {
+  /** Get page by name */
+  get(name: string): IPageObject | undefined;
+
+  /** Get page metadata */
+  getMetadata(name: string): PageObjectMetadata | undefined;
+
+  /** Register a page */
+  register(name: string, page: IPageObject, metadata: PageObjectMetadata): void;
+
+  /** List all pages */
+  list(): string[];
+}
+
+/**
+ * POM Loader options
+ */
+export interface PageObjectLoaderOptions {
+  /** Working directory */
+  cwd?: string;
+
+  /** Base URL for resolving relative URLs */
+  baseUrl?: string;
+
+  /** Whether to cache loaded pages */
+  cache?: boolean;
+
+  /** Custom pattern for page files */
+  pattern?: string;
+
+  /** Timeout for page initialization */
+  timeout?: number;
+}
+
+/**
+ * POM Validation result
+ */
+export interface PageObjectValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+
+  /** Validation errors */
+  errors: string[];
+
+  /** Validation warnings */
+  warnings: string[];
+
+  /** Loaded pages count */
+  pagesCount: number;
+}