qa360 2.2.20 → 2.3.1

package/dist/core/crawler/download-handler.js

@@ -0,0 +1,370 @@
+/**
+ * Download Handler
+ *
+ * P1 - File download management
+ *
+ * Supports:
+ * - Click and wait for download
+ * - Download verification
+ * - Multiple downloads handling
+ * - Download timeout
+ * - File size validation
+ *
+ * @see https://playwright.dev/docs/downloads
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+/**
+ * Download Handler class
+ */
+export class DownloadHandler {
+    downloads = new Map();
+    downloadDir;
+    defaultTimeout;
+    saveFiles;
+    stats = {
+        totalDownloads: 0,
+        successfulDownloads: 0,
+        failedDownloads: 0,
+        totalSize: 0,
+    };
+    constructor(config = {}) {
+        this.downloadDir = config.downloadDir || '/tmp/qa360-downloads';
+        this.defaultTimeout = config.timeout || 30000;
+        this.saveFiles = config.saveFiles !== false;
+        // Ensure download directory exists
+        this.ensureDownloadDir();
+    }
+    async ensureDownloadDir() {
+        try {
+            await fs.mkdir(this.downloadDir, { recursive: true });
+        }
+        catch {
+            // Directory might already exist
+        }
+    }
+    /**
+     * Setup download handling for a page
+     */
+    setupDownloadHandler(page) {
+        page.on('download', async (download) => {
+            const filename = download.suggestedFilename();
+            const path = join(this.downloadDir, filename);
+            const info = {
+                filename,
+                path,
+                url: download.url(),
+                mimeType: download.contentType(),
+                timestamp: Date.now(),
+            };
+            if (this.saveFiles) {
+                try {
+                    await download.saveAs(path);
+                    const stats = await fs.stat(path);
+                    info.size = stats.size;
+                }
+                catch (e) {
+                    console.error(`Failed to save download: ${e}`);
+                }
+            }
+            this.downloads.set(filename, info);
+            console.log(`📥 Download: ${filename} (${info.size ? info.size + ' bytes' : 'size unknown'})`);
+        });
+    }
+    /**
+     * Click element and wait for download
+     */
+    async clickAndWaitForDownload(page, selector, options = {}) {
+        const timeout = options.timeout || this.defaultTimeout;
+        const action = options.action || 'click';
+        this.stats.totalDownloads++;
+        this.setupDownloadHandler(page);
+        try {
+            // Start waiting for download before clicking
+            const downloadPromise = page.waitForEvent('download', { timeout });
+            // Perform the action
+            const element = page.locator(selector).first();
+            await element.waitFor({ state: 'visible', timeout: 5000 });
+            switch (action) {
+                case 'click':
+                    await element.click();
+                    break;
+                case 'dblclick':
+                    await element.dblclick();
+                    break;
+                case 'hover':
+                    await element.hover();
+                    break;
+            }
+            // Wait for download to start
+            const download = await downloadPromise;
+            const filename = download.suggestedFilename();
+            const path = join(this.downloadDir, filename);
+            const info = {
+                filename,
+                path,
+                url: download.url(),
+                mimeType: download.contentType(),
+                timestamp: Date.now(),
+            };
+            if (this.saveFiles && options.waitForCompletion !== false) {
+                await download.saveAs(path);
+                const stats = await fs.stat(path);
+                info.size = stats.size;
+                this.stats.totalSize += stats.size;
+            }
+            this.downloads.set(filename, info);
+            this.stats.successfulDownloads++;
+            // Return both the info and the raw download object for tests
+            return {
+                success: true,
+                download: info,
+                // Include raw download object for tests that expect download.suggestedFilename()
+                rawDownload: download,
+            };
+        }
+        catch (e) {
+            this.stats.failedDownloads++;
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    }
+    /**
+     * Click multiple elements and wait for downloads
+     */
+    async clickAndWaitForDownloads(page, selectors, options = {}) {
+        const results = [];
+        for (const selector of selectors) {
+            const result = await this.clickAndWaitForDownload(page, selector, options);
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Wait for download by filename pattern
+     */
+    async waitForDownload(page, filenamePattern, timeout = this.defaultTimeout) {
+        const startTime = Date.now();
+        return new Promise((resolve) => {
+            const checkInterval = setInterval(() => {
+                const downloads = Array.from(this.downloads.values());
+                for (const download of downloads) {
+                    const matches = typeof filenamePattern === 'string'
+                        ? download.filename.includes(filenamePattern)
+                        : filenamePattern.test(download.filename);
+                    if (matches) {
+                        clearInterval(checkInterval);
+                        resolve({ success: true, download });
+                        return;
+                    }
+                }
+                if (Date.now() - startTime > timeout) {
+                    clearInterval(checkInterval);
+                    resolve({ success: false, error: `Timeout waiting for download matching: ${filenamePattern}` });
+                }
+            }, 100);
+        });
+    }
+    /**
+     * Verify a download
+     */
+    async verifyDownload(download, verification) {
+        // Handle both raw Download object and DownloadInfo
+        const filename = download.suggestedFilename ? download.suggestedFilename() : download.filename;
+        const size = download.size || (download._failure ? undefined : download.size);
+        const errors = [];
+        let filenameMatch = true;
+        let sizeMatch = true;
+        let mimeTypeMatch = true;
+        let contentMatch = true;
+        // Filename verification
+        if (verification.filename) {
+            const matches = typeof verification.filename === 'string'
+                ? filename === verification.filename
+                : verification.filename.test(filename);
+            filenameMatch = matches;
+            if (!matches) {
+                errors.push('Filename mismatch');
+            }
+        }
+        else if (verification.filenamePattern) {
+            const pattern = verification.filenamePattern;
+            const matches = typeof pattern === 'string'
+                ? filename.includes(pattern)
+                : pattern.test(filename);
+            if (!matches) {
+                errors.push('Filename mismatch');
+            }
+        }
+        // Size verification
+        if (verification.minSize && size !== undefined && size < verification.minSize) {
+            sizeMatch = false;
+            errors.push('File size mismatch');
+        }
+        if (verification.maxSize && size !== undefined && size > verification.maxSize) {
+            sizeMatch = false;
+            errors.push('File size mismatch');
+        }
+        // MIME type verification
+        if (verification.mimeType) {
+            const mimeType = download.contentType ? download.contentType() : download.mimeType;
+            const matches = typeof verification.mimeType === 'string'
+                ? mimeType === verification.mimeType
+                : (verification.mimeType instanceof RegExp
+                    ? verification.mimeType.test(mimeType)
+                    : mimeType.includes(verification.mimeType.replace('*', '')));
+            mimeTypeMatch = matches;
+            if (!matches) {
+                errors.push('MIME type mismatch');
+            }
+        }
+        // Content verification (requires reading file)
+        if (verification.content || verification.contentPattern) {
+            if (download.path) {
+                try {
+                    const fileContent = await fs.readFile(download.path, 'utf-8');
+                    if (verification.content) {
+                        contentMatch = fileContent.includes(verification.content);
+                    }
+                    else if (verification.contentPattern) {
+                        contentMatch = verification.contentPattern.test(fileContent);
+                    }
+                    if (!contentMatch) {
+                        errors.push('Content mismatch');
+                    }
+                }
+                catch {
+                    contentMatch = false;
+                    errors.push('Content mismatch');
+                }
+            }
+        }
+        return {
+            valid: filenameMatch && sizeMatch && mimeTypeMatch && contentMatch,
+            filenameMatch,
+            sizeMatch,
+            mimeTypeMatch,
+            contentMatch,
+            actualSize: size,
+            errors,
+        };
+    }
+    /**
+     * Get all downloads
+     */
+    getAllDownloads() {
+        return Array.from(this.downloads.values());
+    }
+    /**
+     * Get download by filename
+     */
+    getDownload(filename) {
+        return this.downloads.get(filename);
+    }
+    /**
+     * Get last download
+     */
+    getLastDownload() {
+        const downloads = Array.from(this.downloads.values());
+        if (downloads.length === 0)
+            return undefined;
+        return downloads.sort((a, b) => b.timestamp - a.timestamp)[0];
+    }
+    /**
+     * Clear all downloads
+     */
+    clearDownloads() {
+        this.downloads.clear();
+    }
+    /**
+     * Delete downloaded files
+     */
+    async clearDownloadFiles() {
+        const files = await fs.readdir(this.downloadDir).catch(() => []);
+        for (const file of files) {
+            const path = join(this.downloadDir, file);
+            await fs.unlink(path).catch(() => {
+                // File might not exist or be deletable
+            });
+        }
+    }
+    /**
+     * Get download directory
+     */
+    getDownloadDir() {
+        return this.downloadDir;
+    }
+    /**
+     * Set download directory
+     */
+    setDownloadDir(dir) {
+        this.downloadDir = dir;
+        this.ensureDownloadDir();
+    }
+    /**
+     * Get download count
+     */
+    get downloadCount() {
+        return this.downloads.size;
+    }
+    /**
+     * Assert download exists
+     */
+    assertDownloadExists(filenamePattern) {
+        const downloads = Array.from(this.downloads.values());
+        for (const download of downloads) {
+            const matches = typeof filenamePattern === 'string'
+                ? download.filename.includes(filenamePattern)
+                : filenamePattern.test(download.filename);
+            if (matches) {
+                return { success: true, download };
+            }
+        }
+        return {
+            success: false,
+            error: `No download found matching pattern: ${filenamePattern}`,
+        };
+    }
+    /**
+     * Get download statistics
+     */
+    getStats() {
+        const downloads = this.getAllDownloads();
+        const averageSize = this.stats.totalDownloads > 0
+            ? this.stats.totalSize / this.stats.successfulDownloads
+            : 0;
+        return {
+            totalDownloads: this.stats.totalDownloads,
+            successfulDownloads: this.stats.successfulDownloads,
+            failedDownloads: this.stats.failedDownloads,
+            totalSize: this.stats.totalSize,
+            averageSize,
+        };
+    }
+    /**
+     * Get download history
+     */
+    getHistory() {
+        return this.getAllDownloads();
+    }
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.stats = {
+            totalDownloads: 0,
+            successfulDownloads: 0,
+            failedDownloads: 0,
+            totalSize: 0,
+        };
+    }
+}
+/**
+ * Factory function to create Download Handler
+ */
+export function createDownloadHandler(config) {
+    return new DownloadHandler(config);
+}
+export default DownloadHandler;

package/dist/core/crawler/email-testing-handler.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Email Testing Handler
+ *
+ * P1 - Email testing for applications that send emails
+ *
+ * Supports:
+ * - Mailhog integration
+ * - Mailtrap integration
+ * - Mailgun API
+ * - SendGrid API
+ * - Generic IMAP/POP3 access
+ * - Email parsing and validation
+ * - Link extraction from emails
+ * - Attachment handling
+ *
+ * @see https://github.com/mailhog/MailHog
+ */
+export interface EmailConfig {
+    /** Mailhog API base URL (e.g., http://localhost:8025) */
+    mailhogUrl?: string;
+    /** Mailtrap API token */
+    mailtrapToken?: string;
+    /** Mailgun API key */
+    mailgunApiKey?: string;
+    /** SendGrid API key */
+    sendgridApiKey?: string;
+    /** Default timeout for email operations (ms) */
+    timeout?: number;
+}
+export interface EmailMessage {
+    /** Message ID */
+    id: string;
+    /** From address */
+    from: string;
+    /** To addresses */
+    to: string[];
+    /** CC addresses */
+    cc?: string[];
+    /** Subject */
+    subject: string;
+    /** Plain text body */
+    text?: string;
+    /** HTML body */
+    html?: string;
+    /** Received timestamp */
+    received: Date;
+    /** Attachments */
+    attachments?: EmailAttachment[];
+    /** Custom headers */
+    headers?: Record<string, string>;
+}
+export interface EmailAttachment {
+    /** Filename */
+    filename: string;
+    /** Content type */
+    contentType: string;
+    /** Size in bytes */
+    size: number;
+    /** Download URL (if available) */
+    downloadUrl?: string;
+}
+export interface EmailSearchOptions {
+    /** Filter by recipient */
+    to?: string;
+    /** Filter by sender */
+    from?: string;
+    /** Filter by subject (partial match) */
+    subject?: string;
+    /** Filter by content (partial match) */
+    contains?: string;
+    /** Minimum received date */
+    after?: Date;
+    /** Maximum received date */
+    before?: Date;
+}
+/**
+ * Email Testing Handler class
+ */
+export declare class EmailTestingHandler {
+    private mailhogUrl;
+    private timeout;
+    private mailtrapToken?;
+    private mailgunApiKey?;
+    private sendgridApiKey?;
+    constructor(config?: EmailConfig);
+    /**
+     * Fetch all messages from Mailhog
+     */
+    fetchMessages(): Promise<EmailMessage[]>;
+    /**
+     * Delete all messages from Mailhog
+     */
+    deleteAllMessages(): Promise<void>;
+    /**
+     * Get a specific message by ID
+     */
+    getMessage(id: string): Promise<EmailMessage | null>;
+    /**
+     * Wait for a new email matching criteria
+     */
+    waitForEmail(options?: EmailSearchOptions, timeout?: number): Promise<EmailMessage | null>;
+    /**
+     * Search for messages matching criteria
+     */
+    searchMessages(options: EmailSearchOptions): Promise<EmailMessage[]>;
+    /**
+     * Get the most recent email matching criteria
+     */
+    getLatestEmail(options?: EmailSearchOptions): Promise<EmailMessage | null>;
+    /**
+     * Extract all links from an email
+     */
+    extractLinks(message: EmailMessage): {
+        textLinks: string[];
+        htmlLinks: string[];
+        allLinks: string[];
+    };
+    /**
+     * Extract verification links (common patterns)
+     */
+    extractVerificationLinks(message: EmailMessage): {
+        verifyEmail: string[];
+        resetPassword: string[];
+        unsubscribe: string[];
+        other: string[];
+    };
+    /**
+     * Extract OTP/code from email
+     */
+    extractCode(message: EmailMessage): {
+        code?: string;
+        type?: 'numeric' | 'alphanumeric';
+        confidence: number;
+    };
+    /**
+     * Parse a Mailhog message
+     */
+    private parseMailhogMessage;
+    /**
+     * Parse email address from string
+     */
+    private parseEmailAddress;
+    /**
+     * Parse attachments from Mailhog format
+     */
+    private parseAttachments;
+    /**
+     * Check if message matches search criteria
+     */
+    private matchesCriteria;
+    /**
+     * Assert email was received
+     */
+    assertEmailReceived(options: EmailSearchOptions, timeout?: number): Promise<{
+        received: boolean;
+        email?: EmailMessage;
+        error?: string;
+    }>;
+    /**
+     * Assert email contains link
+     */
+    assertEmailContainsLink(message: EmailMessage, linkPattern: string | RegExp): {
+        contains: boolean;
+        foundLinks: string[];
+    };
+    /**
+     * Get Mailhog status
+     */
+    getMailhogStatus(): Promise<{
+        available: boolean;
+        error?: string;
+    }>;
+    private sleep;
+    /**
+     * Fetch messages from Mailtrap (alternative to Mailhog)
+     */
+    fetchMailtrapMessages(inboxId?: string): Promise<EmailMessage[]>;
+    /**
+     * Parse Mailtrap message
+     */
+    private parseMailtrapMessage;
+    /**
+     * Create email testing utilities for test helpers
+     */
+    createTestHelpers(): {
+        waitForEmail: (options?: EmailSearchOptions, timeout?: number) => Promise<EmailMessage | null>;
+        getLatestEmail: (options?: EmailSearchOptions) => Promise<EmailMessage | null>;
+        extractLinks: (message: EmailMessage) => {
+            textLinks: string[];
+            htmlLinks: string[];
+            allLinks: string[];
+        };
+        extractCode: (message: EmailMessage) => {
+            code?: string;
+            type?: "numeric" | "alphanumeric";
+            confidence: number;
+        };
+        deleteAll: () => Promise<void>;
+        assertEmailReceived: (options: EmailSearchOptions, timeout?: number) => Promise<{
+            received: boolean;
+            email?: EmailMessage;
+            error?: string;
+        }>;
+    };
+}
+/**
+ * Factory function to create Email Testing Handler
+ */
+export declare function createEmailTestingHandler(config?: EmailConfig): EmailTestingHandler;
+/**
+ * Quick function to wait for email
+ */
+export declare function waitForEmail(config: EmailConfig, options: EmailSearchOptions, timeout?: number): Promise<EmailMessage | null>;
+export default EmailTestingHandler;