qa360 2.2.1 → 2.2.13

package/cli/dist/core/crawler/selector-generator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * QA360 Selector Generator
+ *
+ * Generates stable, resilient CSS selectors for web elements
+ */
+import type { ElementInfo } from './types.js';
+/**
+ * Generate optimal selector for an element
+ */
+export declare function generateSelector(element: {
+    tagName?: string;
+    id?: string;
+    className?: string;
+    attributes?: Record<string, string>;
+    textContent?: string;
+    role?: string;
+    name?: string;
+}): string;
+/**
+ * Generate selector from Playwright element handle
+ */
+export declare function generateSelectorFromElement(element: any, page: any): Promise<ElementInfo>;
+/**
+ * Optimize selector for resiliency
+ */
+export declare function optimizeSelector(selector: string): string;
+/**
+ * Generate fallback selectors for resilience
+ */
+export declare function generateFallbackSelectors(primarySelector: string): string[];
+/**
+ * Score selector quality (0-100)
+ */
+export declare function scoreSelector(selector: string): number;

package/cli/dist/core/crawler/selector-generator.js

@@ -0,0 +1,309 @@
+/**
+ * QA360 Selector Generator
+ *
+ * Generates stable, resilient CSS selectors for web elements
+ */
+/**
+ * Selector priority (most stable first)
+ */
+const SELECTOR_PRIORITY = [
+    'data-testid', // Best: explicit test attribute
+    'data-cy', // Cypress convention
+    'data-test', // Common convention
+    'data-test-id', // Common convention
+    'id', // Good if stable
+    'aria-label', // Accessible, usually stable
+    'name', // Form field names
+    'role + aria-label', // ARIA combo
+    'class', // Less stable, use as fallback
+    'tag + text', // Content-based
+    'nth-child', // Last resort
+];
+/**
+ * Generate optimal selector for an element
+ */
+export function generateSelector(element) {
+    const { tagName, id, className, attributes = {}, textContent, role, name } = element;
+    // 1. Best: data-testid or similar test attributes
+    for (const attr of ['data-testid', 'data-cy', 'data-test', 'data-test-id']) {
+        if (attributes[attr]) {
+            return `[${attr}="${attributes[attr]}"]`;
+        }
+    }
+    // 2. ID (if not auto-generated)
+    if (id && !isGeneratedId(id)) {
+        return `#${escapeCss(id)}`;
+    }
+    // 3. aria-label (accessible and stable)
+    if (attributes['aria-label']) {
+        return `[aria-label="${escapeCss(attributes['aria-label'])}"]`;
+    }
+    // 4. Form field name
+    if (name) {
+        return `[name="${escapeCss(name)}"]`;
+    }
+    // 5. Role + label combination
+    if (role && attributes['aria-label']) {
+        return `[role="${role}"][aria-label="${escapeCss(attributes['aria-label'])}"]`;
+    }
+    // 6. Class (avoid if too generic)
+    if (className && !isGenericClass(className)) {
+        const classes = className.split(' ').filter(c => !isGenericClass(c));
+        if (classes.length > 0) {
+            // Smart class selection: prioritize meaningful classes
+            const meaningfulClasses = selectMeaningfulClasses(classes);
+            const classSelector = meaningfulClasses.map(c => `.${escapeCss(c)}`).join('');
+            // Limit total selector length
+            const qualifiedSelector = tagName ? `${tagName}${classSelector}` : classSelector;
+            return truncateSelector(qualifiedSelector, 200);
+        }
+    }
+    // 7. Tag + text content (for buttons, links)
+    if (tagName && textContent && textContent.trim()) {
+        const text = textContent.trim().slice(0, 50);
+        return `${tagName}:has-text("${escapeCss(text)}")`;
+    }
+    // 8. Tag only (last resort)
+    return tagName || '*';
+}
+/**
+ * Generate selector from Playwright element handle
+ */
+export async function generateSelectorFromElement(element, page) {
+    try {
+        // Get all attributes
+        const attributes = await element.evaluate((el) => {
+            const attrs = {};
+            for (const attr of el.attributes || []) {
+                attrs[attr.name] = attr.value;
+            }
+            return attrs;
+        });
+        // Get basic info
+        const tagName = await element.evaluate((el) => el.tagName?.toLowerCase());
+        const textContent = await element.evaluate((el) => el.textContent?.trim());
+        const className = attributes.class || attributes.className;
+        const id = attributes.id;
+        const role = attributes.role || attributes['role'];
+        const name = attributes.name;
+        // Generate selector
+        const selector = generateSelector({
+            tagName,
+            id,
+            className,
+            attributes,
+            textContent,
+            role,
+            name,
+        });
+        // Determine stability
+        const stable = isSelectorStable(selector);
+        return {
+            selector,
+            text: textContent || undefined,
+            ariaLabel: attributes['aria-label'],
+            testId: attributes['data-testid'] || attributes['data-cy'] || attributes['data-test'],
+            role: role || undefined,
+            type: tagName || 'unknown',
+            stable,
+        };
+    }
+    catch (error) {
+        // Fallback
+        return {
+            selector: 'unknown',
+            type: 'unknown',
+            stable: false,
+        };
+    }
+}
+/**
+ * Check if ID is auto-generated (not stable)
+ */
+function isGeneratedId(id) {
+    // Patterns indicating auto-generated IDs
+    const generatedPatterns = [
+        /^\w+_\d+$/, // react_123, vue_456
+        /^(ember|ember)\d+$/, // ember1234
+        /^yui_[^_]+_\d+$/, // yui_gen_123
+        /^\w+-\w+-\w+$/, // random-hash patterns
+        /^[a-f0-9]{8,}$/, // hex hashes
+    ];
+    return generatedPatterns.some(pattern => pattern.test(id));
+}
+/**
+ * Check if class is too generic
+ */
+function isGenericClass(className) {
+    const genericClasses = [
+        'active', 'inactive', 'selected', 'disabled', 'enabled',
+        'hidden', 'visible', 'show', 'hide', 'open', 'closed',
+        'first', 'last', 'odd', 'even',
+        'container', 'wrapper', 'content', 'section',
+        'btn', 'button', 'input', 'form', 'field',
+        'row', 'col', 'column', 'grid',
+    ];
+    const classes = className.split(' ');
+    return classes.every(c => genericClasses.includes(c));
+}
+/**
+ * Check if selector is considered stable
+ */
+function isSelectorStable(selector) {
+    // Stable selectors: data-testid, aria-label, stable IDs
+    const stablePatterns = [
+        /\[data-(testid|test|test-id|cy)/,
+        /\[aria-label=/,
+        /\[name=/,
+        /#\w[\w-]*\w/, // ID with word chars
+    ];
+    // Unstable selectors: nth-child, generated classes
+    const unstablePatterns = [
+        /:nth-child/,
+        /:\w+-\w+-\w+/, // hash-like classes
+    ];
+    const hasStable = stablePatterns.some(p => p.test(selector));
+    const hasUnstable = unstablePatterns.some(p => p.test(selector));
+    return hasStable || !hasUnstable;
+}
+/**
+ * Escape special CSS characters
+ */
+function escapeCss(str) {
+    return str.replace(/(["\\])/g, '\\$1').replace(/"/g, '\\"');
+}
+/**
+ * Select the most meaningful classes from a class list
+ * Prioritizes: unique identifiers, component names, action-oriented classes
+ * Deprioritizes: utility classes (spacing, colors, sizing)
+ */
+function selectMeaningfulClasses(classes) {
+    // Tailwind and other utility class patterns to deprioritize
+    const utilityPatterns = [
+        /^(p|m|px|py|pt|pb|pl|pr)-/, // spacing
+        /^(mt|mb|ml|mr)-/, // margin spacing
+        /^(text|bg|border)-/, // colors
+        /^(w|h)-/, // sizing
+        /^(flex|grid|block|inline)/, // display
+        /^(justify|items|self)/, // flexbox/grid
+        /^(rounded|shadow|opacity)/, // styling
+        /^gap-/, // flex gap
+        /^(line-)?height-/, // height
+        /^(font|weight|size)/, // typography
+    ];
+    // Score each class by "meaningfulness"
+    const scored = classes.map(cls => {
+        let score = 50; // base score
+        // Bonus: component-like names (contain meaningful words)
+        if (/[A-Z][a-z]+/.test(cls))
+            score += 30; // CamelCase components
+        if (/button|btn|input|form|card|modal|nav|header|footer|sidebar|menu|dropdown/i.test(cls))
+            score += 25;
+        // Bonus: contains numbers (likely unique)
+        if (/\d+/.test(cls))
+            score += 15;
+        // Penalty: utility classes
+        for (const pattern of utilityPatterns) {
+            if (pattern.test(cls)) {
+                score -= 40;
+                break;
+            }
+        }
+        return { class: cls, score };
+    });
+    // Sort by score (descending) and take top 5
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, 5).map(s => s.class);
+}
+/**
+ * Truncate selector to max length while keeping it valid
+ * Preserves the most specific parts
+ */
+function truncateSelector(selector, maxLength) {
+    if (selector.length <= maxLength)
+        return selector;
+    // For class-based selectors, remove classes from the middle
+    const classMatch = selector.match(/^(\w+)((\.[\w-]+)+)$/);
+    if (classMatch) {
+        const tag = classMatch[1];
+        const classes = classMatch[2].split('.').filter(c => c); // Remove empty strings
+        // Keep first 2 and last 2 classes (most specific)
+        if (classes.length > 4) {
+            const kept = [...classes.slice(0, 2), ...classes.slice(-2)];
+            const truncated = `${tag}.${kept.join('.')}`;
+            if (truncated.length <= maxLength)
+                return truncated;
+        }
+    }
+    // Final fallback: just truncate (may not be valid CSS but prevents overflow)
+    return selector.substring(0, maxLength - 3) + '...';
+}
+/**
+ * Optimize selector for resiliency
+ */
+export function optimizeSelector(selector) {
+    // Remove unnecessary descendants
+    let optimized = selector.replace(/\s*>\s*/g, ' > ');
+    // Use :has() for more specific targeting
+    if (optimized.includes(' ')) {
+        const parts = optimized.split(' ');
+        if (parts.length > 3) {
+            // Keep only the last 3 parts for specificity
+            optimized = parts.slice(-3).join(' ');
+        }
+    }
+    return optimized;
+}
+/**
+ * Generate fallback selectors for resilience
+ */
+export function generateFallbackSelectors(primarySelector) {
+    const fallbacks = [];
+    // If primary is data-testid, add aria-label fallback
+    if (primarySelector.includes('[data-testid')) {
+        const testId = primarySelector.match(/\[data-testid="([^"]+)"\]/)?.[1];
+        if (testId) {
+            // Try aria-label with similar text
+            fallbacks.push(`[aria-label="${testId}"]`);
+        }
+    }
+    // If primary is ID, add name fallback
+    if (primarySelector.startsWith('#')) {
+        const id = primarySelector.slice(1);
+        fallbacks.push(`[name="${id}"]`);
+    }
+    // Add generic fallback based on tag
+    const tagMatch = primarySelector.match(/^(\w+)/);
+    if (tagMatch) {
+        fallbacks.push(tagMatch[1]);
+    }
+    return fallbacks;
+}
+/**
+ * Score selector quality (0-100)
+ */
+export function scoreSelector(selector) {
+    let score = 50; // Base score
+    // Bonus for test attributes
+    if (selector.includes('[data-testid'))
+        score += 40;
+    else if (selector.includes('[data-test'))
+        score += 35;
+    else if (selector.includes('[data-cy'))
+        score += 30;
+    else if (selector.includes('[aria-label'))
+        score += 25;
+    else if (selector.startsWith('#'))
+        score += 20;
+    else if (selector.includes('[name='))
+        score += 15;
+    // Penalty for unstable patterns
+    if (selector.includes(':nth-child'))
+        score -= 30;
+    if (selector.includes(':has-text'))
+        score -= 10;
+    // Bonus for specificity balance
+    if (!selector.includes(' '))
+        score += 5; // Simple selector
+    return Math.max(0, Math.min(100, score));
+}

package/cli/dist/core/crawler/types.d.ts

@@ -0,0 +1,353 @@
+/**
+ * QA360 Web Crawler - Type Definitions
+ *
+ * Automatically discovers and analyzes web applications for E2E test generation
+ */
+/**
+ * Crawler configuration options
+ */
+export interface CrawlOptions {
+    /** Base URL to start crawling */
+    baseUrl: string;
+    /** Maximum depth to follow links (default: 3) */
+    maxDepth?: number;
+    /** Maximum number of pages to crawl (default: 50) */
+    maxPages?: number;
+    /** Follow internal links (default: true) */
+    followLinks?: boolean;
+    /** Discover and analyze forms (default: true) */
+    discoverForms?: boolean;
+    /** Discover buttons and actions (default: true) */
+    discoverButtons?: boolean;
+    /** Regex patterns to exclude (e.g., ['/admin', '/logout', '/api']) */
+    excludePatterns?: string[];
+    /** Authentication for protected areas */
+    auth?: CrawlAuth;
+    /** Timeout per page in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Whether to take screenshots (default: false) */
+    screenshots?: boolean;
+    /** Headless mode (default: true) */
+    headless?: boolean;
+    /** Wait for network idle before analysis (default: true) */
+    waitForNetworkIdle?: boolean;
+}
+/**
+ * Authentication for crawling
+ */
+export interface CrawlAuth {
+    /** Type of authentication */
+    type: 'basic' | 'form' | 'bearer' | 'cookie';
+    /** URL for login form (for type: 'form') */
+    loginUrl?: string;
+    /** Username */
+    username?: string;
+    /** Password */
+    password?: string;
+    /** Username selector (for type: 'form') */
+    usernameSelector?: string;
+    /** Password selector (for type: 'form') */
+    passwordSelector?: string;
+    /** Submit button selector (for type: 'form') */
+    submitSelector?: string;
+    /** Bearer token (for type: 'bearer') */
+    token?: string;
+    /** Cookies (for type: 'cookie') */
+    cookies?: Array<{
+        name: string;
+        value: string;
+        domain?: string;
+    }>;
+}
+/**
+ * Element information discovered on a page
+ */
+export interface ElementInfo {
+    /** CSS selector (optimized for stability) */
+    selector: string;
+    /** Text content */
+    text?: string;
+    /** aria-label if present */
+    ariaLabel?: string;
+    /** data-testid if present */
+    testId?: string;
+    /** Element role */
+    role?: string;
+    /** Element type */
+    type: string;
+    /** Whether selector is considered stable */
+    stable: boolean;
+}
+/**
+ * Form field information
+ */
+export interface FieldInfo extends ElementInfo {
+    /** Field input type */
+    inputType: string;
+    /** Field name */
+    name?: string;
+    /** Whether field is required */
+    required: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Options for select elements */
+    options?: string[];
+    /** Validation attributes */
+    validation?: {
+        min?: number | string;
+        max?: number | string;
+        pattern?: string;
+        minLength?: number;
+        maxLength?: number;
+    };
+}
+/**
+ * Form definition discovered on a page
+ */
+export interface FormInfo {
+    /** Form action/endpoint */
+    action?: string;
+    /** Form method */
+    method?: string;
+    /** Stable selector for the form */
+    selector: string;
+    /** Form purpose (detected) */
+    purpose: 'login' | 'signup' | 'search' | 'contact' | 'checkout' | 'filter' | 'other';
+    /** All fields in the form */
+    fields: FieldInfo[];
+    /** Submit button */
+    submitButton?: ElementInfo;
+    /** Confidence score for purpose detection (0-1) */
+    confidence: number;
+}
+/**
+ * Link information
+ */
+export interface LinkInfo extends ElementInfo {
+    /** href URL */
+    url: string;
+    /** Whether link is internal to the domain */
+    internal: boolean;
+    /** Whether link was visited */
+    visited: boolean;
+}
+/**
+ * Page definition after crawling
+ */
+export interface PageDefinition {
+    /** Full URL */
+    url: string;
+    /** Path relative to base */
+    path: string;
+    /** Page title */
+    title: string;
+    /** Depth from base URL */
+    depth: number;
+    /** HTTP status code */
+    status: number;
+    /** Load time in milliseconds */
+    loadTime: number;
+    /** Content type */
+    contentType?: string;
+    /** Meta description */
+    description?: string;
+    /** All discovered elements */
+    elements: {
+        /** Buttons on the page */
+        buttons: ElementInfo[];
+        /** Links on the page */
+        links: LinkInfo[];
+        /** Forms on the page */
+        forms: FormInfo[];
+        /** Input fields (standalone) */
+        inputs: FieldInfo[];
+        /** Select dropdowns */
+        selects: FieldInfo[];
+        /** Checkboxes */
+        checkboxes: ElementInfo[];
+        /** Radio buttons */
+        radios: ElementInfo[];
+    };
+    /** Navigation elements detected */
+    navigation: {
+        /** Main navigation menu */
+        main?: {
+            selector: string;
+            items: LinkInfo[];
+        };
+        /** Breadcrumb */
+        breadcrumb?: {
+            selector: string;
+            items: Array<{
+                text: string;
+                url: string;
+            }>;
+        };
+        /** Pagination */
+        pagination?: {
+            selector: string;
+            nextPage?: LinkInfo;
+            prevPage?: LinkInfo;
+        };
+        /** Footer links */
+        footer?: {
+            selector: string;
+            items: LinkInfo[];
+        };
+    };
+    /** Screenshot (base64) */
+    screenshot?: string;
+    /** Accessibility snapshot */
+    accessibility?: A11ySnapshot;
+    /** Page type detected */
+    pageType: 'homepage' | 'listing' | 'detail' | 'form' | 'dashboard' | 'login' | 'signup' | 'other';
+    /** Confidence for page type (0-1) */
+    pageTypeConfidence: number;
+}
+/**
+ * Accessibility snapshot from axe-core
+ */
+export interface A11ySnapshot {
+    /** Accessibility score (0-100) */
+    score: number;
+    /** Violations found */
+    violations: Array<{
+        id: string;
+        impact: 'critical' | 'serious' | 'moderate' | 'minor';
+        description: string;
+        nodes: number;
+        selectors: string[];
+    }>;
+    /** Pass count */
+    passes: number;
+    /** Incomplete checks */
+    incomplete: number;
+}
+/**
+ * User journey discovered
+ */
+export interface UserJourney {
+    /** Journey name */
+    name: string;
+    /** Journey description */
+    description: string;
+    /** Journey type */
+    type: 'authentication' | 'navigation' | 'transaction' | 'search' | 'form-submission' | 'other';
+    /** Steps in the journey */
+    steps: JourneyStep[];
+    /** Entry point URL */
+    entryPoint: string;
+    /** Expected final URL */
+    finalUrl?: string;
+    /** Estimated duration in seconds */
+    estimatedDuration: number;
+}
+/**
+ * Single step in a user journey
+ */
+export interface JourneyStep {
+    /** Step order */
+    order: number;
+    /** Step description */
+    description: string;
+    /** Action to perform */
+    action: JourneyAction;
+    /** Target selector */
+    selector?: string;
+    /** Value to input (for fill actions) */
+    value?: string;
+    /** Expected outcome */
+    expected?: {
+        /** Expected URL after action */
+        url?: string;
+        /** Expected visible element */
+        visible?: string;
+        /** Expected text content */
+        text?: string;
+    };
+    /** Wait time in ms */
+    wait?: number;
+}
+/**
+ * Journey action types
+ */
+export type JourneyAction = 'navigate' | 'click' | 'fill' | 'select' | 'check' | 'uncheck' | 'upload' | 'hover' | 'press' | 'waitFor' | 'waitForNavigation' | 'scroll';
+/**
+ * Site map structure
+ */
+export interface SiteMap {
+    /** Base URL */
+    baseUrl: string;
+    /** All discovered pages */
+    pages: PageDefinition[];
+    /** Pages by depth */
+    pagesByDepth: Record<number, PageDefinition[]>;
+    /** Orphan pages (no links to them) */
+    orphans: PageDefinition[];
+    /** Page type distribution */
+    pageTypeDistribution: Record<string, number>;
+    /** Total unique links */
+    totalLinks: number;
+    /** Total forms */
+    totalForms: number;
+    /** Crawl metadata */
+    metadata: {
+        /** Pages crawled */
+        pagesCrawled: number;
+        /** Pages skipped (excluded) */
+        pagesSkipped: number;
+        /** Pages failed */
+        pagesFailed: number;
+        /** Total duration in ms */
+        duration: number;
+        /** Average page load time */
+        avgLoadTime: number;
+        /** Max depth reached */
+        maxDepth: number;
+    };
+}
+/**
+ * Complete crawl result
+ */
+export interface CrawlResult {
+    /** Success status */
+    success: boolean;
+    /** Site map */
+    siteMap: SiteMap;
+    /** Discovered user journeys */
+    userJourneys: UserJourney[];
+    /** Forms requiring testing */
+    forms: FormInfo[];
+    /** Pages requiring accessibility testing */
+    accessibilityIssues: Array<{
+        page: string;
+        score: number;
+        violations: A11ySnapshot['violations'];
+    }>;
+    /** Warnings */
+    warnings: string[];
+    /** Errors */
+    errors: Array<{
+        page: string;
+        error: string;
+    }>;
+}
+/**
+ * Crawler progress callback
+ */
+export interface CrawlProgress {
+    /** Current page being crawled */
+    currentPage: string;
+    /** Pages completed */
+    completed: number;
+    /** Total pages to crawl */
+    total: number;
+    /** Percentage complete */
+    progress: number;
+    /** Current depth */
+    depth: number;
+}
+/**
+ * Crawler events
+ */
+export type CrawlEventHandler = (event: 'page-start' | 'page-complete' | 'page-error' | 'journey-discovered' | 'complete', data: CrawlProgress | PageDefinition | UserJourney | CrawlResult) => void;

package/cli/dist/core/crawler/types.js

@@ -0,0 +1,6 @@
+/**
+ * QA360 Web Crawler - Type Definitions
+ *
+ * Automatically discovers and analyzes web applications for E2E test generation
+ */
+export {};