qa360 2.2.20 → 2.3.1

package/dist/core/sharding/test-sharding.d.ts

@@ -0,0 +1,137 @@
+/**
+ * QA360 Test Sharding Module
+ *
+ * P0: Split test execution across multiple workers/machines
+ * - Consistent hashing for test distribution
+ * - Dynamic shard allocation
+ * - Load balancing across workers
+ * - CI-friendly shard configuration
+ */
+/**
+ * Shard configuration
+ */
+export interface ShardConfig {
+    /** Total number of shards */
+    totalShards: number;
+    /** Current shard index (1-based) */
+    shardIndex: number;
+    /** Optional shard seed for reproducibility */
+    seed?: string;
+}
+/**
+ * Test metadata for sharding
+ */
+export interface TestMetadata {
+    /** Unique test identifier */
+    testId: string;
+    /** Test file path */
+    filePath: string;
+    /** Test name */
+    testName: string;
+    /** Optional test tags/categories */
+    tags?: string[];
+    /** Optional estimated duration (ms) */
+    duration?: number;
+}
+/**
+ * Shard allocation result
+ */
+export interface ShardAllocation {
+    /** Assigned shard index (1-based) */
+    shardIndex: number;
+    /** Total number of shards */
+    totalShards: number;
+    /** Tests assigned to this shard */
+    tests: TestMetadata[];
+}
+/**
+ * Test Sharding Manager
+ */
+export declare class TestSharding {
+    private config;
+    private seed;
+    constructor(config: ShardConfig);
+    /**
+     * Determine which shard a test belongs to
+     * Uses consistent hashing for reproducible distribution
+     */
+    getShardForTest(test: TestMetadata): number;
+    /**
+     * Check if a test should run in current shard
+     */
+    shouldRunTest(test: TestMetadata): boolean;
+    /**
+     * Filter tests to only those in current shard
+     */
+    filterTests(tests: TestMetadata[]): TestMetadata[];
+    /**
+     * Allocate tests across all shards
+     * Returns distribution stats for all shards
+     */
+    allocateTests(tests: TestMetadata[]): Map<number, TestMetadata[]>;
+    /**
+     * Get shard information for display/logging
+     */
+    getShardInfo(): {
+        shardIndex: number;
+        totalShards: number;
+        shardId: string;
+    };
+    /**
+     * Hash test metadata to a consistent number
+     */
+    private hashTest;
+    /**
+     * Create shard configuration from environment variables
+     * CI-friendly: reads SHARD_TOTAL and SHARD_INDEX
+     */
+    static fromEnv(): ShardConfig | null;
+    /**
+     * Check if sharding is enabled via environment
+     */
+    static isEnabled(): boolean;
+    /**
+     * Get environment variable with multiple possible names
+     */
+    private static getEnvVar;
+    /**
+     * Parse shard config from string format "index/total"
+     * Example: "1/4" -> shardIndex: 1, totalShards: 4
+     */
+    static parseShardString(shardStr: string): ShardConfig;
+    /**
+     * Get recommended shard count based on test count
+     */
+    static getRecommendedShardCount(testCount: number, maxShards?: number): number;
+    /**
+     * Get optimal shard count based on CPU cores
+     */
+    static getOptimalShardCount(): number;
+}
+/**
+ * Create a test sharding manager
+ */
+export declare function createTestSharding(config: ShardConfig): TestSharding;
+/**
+ * Create sharding from environment if enabled
+ */
+export declare function createShardingFromEnv(): TestSharding | null;
+/**
+ * Vitest filter function for sharding
+ * Usage: vitest.config.ts -> test.exclude = [..., createShardingExclude()]
+ */
+export declare function createShardingExclude(): RegExp[] | ((file: string) => boolean);
+/**
+ * Setup sharding for Vitest
+ * Returns a function that can be used to filter tests
+ */
+export declare function setupVitestSharding(): ((testId: string) => boolean) | null;
+/**
+ * Get shard-specific suffix for output files
+ * Prevents overwriting artifacts between shards
+ */
+export declare function getShardSuffix(): string;
+/**
+ * Create shard-specific report filename
+ */
+export declare function getShardedFilename(baseName: string): string;

package/dist/core/sharding/test-sharding.js

@@ -0,0 +1,233 @@
+/**
+ * QA360 Test Sharding Module
+ *
+ * P0: Split test execution across multiple workers/machines
+ * - Consistent hashing for test distribution
+ * - Dynamic shard allocation
+ * - Load balancing across workers
+ * - CI-friendly shard configuration
+ */
+import { createHash } from 'crypto';
+/**
+ * Test Sharding Manager
+ */
+export class TestSharding {
+    config;
+    seed;
+    constructor(config) {
+        this.config = config;
+        this.seed = config.seed || 'qa360-default-seed';
+    }
+    /**
+     * Determine which shard a test belongs to
+     * Uses consistent hashing for reproducible distribution
+     */
+    getShardForTest(test) {
+        // Create a hash from test ID and seed
+        const hash = this.hashTest(test);
+        // Map hash to shard (1-based)
+        return (hash % this.config.totalShards) + 1;
+    }
+    /**
+     * Check if a test should run in current shard
+     */
+    shouldRunTest(test) {
+        const shard = this.getShardForTest(test);
+        return shard === this.config.shardIndex;
+    }
+    /**
+     * Filter tests to only those in current shard
+     */
+    filterTests(tests) {
+        return tests.filter(test => this.shouldRunTest(test));
+    }
+    /**
+     * Allocate tests across all shards
+     * Returns distribution stats for all shards
+     */
+    allocateTests(tests) {
+        const allocation = new Map();
+        // Initialize all shards
+        for (let i = 1; i <= this.config.totalShards; i++) {
+            allocation.set(i, []);
+        }
+        // Distribute tests
+        for (const test of tests) {
+            const shard = this.getShardForTest(test);
+            allocation.get(shard).push(test);
+        }
+        return allocation;
+    }
+    /**
+     * Get shard information for display/logging
+     */
+    getShardInfo() {
+        return {
+            shardIndex: this.config.shardIndex,
+            totalShards: this.config.totalShards,
+            shardId: `${this.config.shardIndex}/${this.config.totalShards}`,
+        };
+    }
+    /**
+     * Hash test metadata to a consistent number
+     */
+    hashTest(test) {
+        const input = `${this.seed}:${test.filePath}:${test.testName}`;
+        const hash = createHash('sha256').update(input).digest('hex');
+        // Convert first 8 chars to number
+        return parseInt(hash.substring(0, 8), 16);
+    }
+    /**
+     * Create shard configuration from environment variables
+     * CI-friendly: reads SHARD_TOTAL and SHARD_INDEX
+     */
+    static fromEnv() {
+        const totalShards = this.getEnvVar('SHARD_TOTAL');
+        const shardIndex = this.getEnvVar('SHARD_INDEX');
+        if (!totalShards || !shardIndex) {
+            return null;
+        }
+        const total = parseInt(totalShards, 10);
+        const index = parseInt(shardIndex, 10);
+        if (isNaN(total) || isNaN(index) || index < 1 || index > total) {
+            throw new Error(`Invalid shard configuration: SHARD_TOTAL=${totalShards}, SHARD_INDEX=${shardIndex}`);
+        }
+        return {
+            totalShards: total,
+            shardIndex: index,
+            seed: this.getEnvVar('SHARD_SEED'),
+        };
+    }
+    /**
+     * Check if sharding is enabled via environment
+     */
+    static isEnabled() {
+        return !!this.getEnvVar('SHARD_TOTAL');
+    }
+    /**
+     * Get environment variable with multiple possible names
+     */
+    static getEnvVar(name) {
+        // Try common CI variable naming conventions
+        // e.g., SHARD_TOTAL, shard_total, shard-total
+        const vars = [
+            name, // SHARD_TOTAL
+            name.toLowerCase(), // shard_total
+            name.replace(/_/g, '-'), // SHARD-TOTAL
+            name.toLowerCase().replace(/_/g, '-'), // shard-total
+        ];
+        for (const v of vars) {
+            if (process.env[v]) {
+                return process.env[v];
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Parse shard config from string format "index/total"
+     * Example: "1/4" -> shardIndex: 1, totalShards: 4
+     */
+    static parseShardString(shardStr) {
+        const match = shardStr.match(/^(\d+)\/(\d+)$/);
+        if (!match) {
+            throw new Error(`Invalid shard string format: "${shardStr}". Expected "index/total" (e.g., "1/4")`);
+        }
+        const shardIndex = parseInt(match[1], 10);
+        const totalShards = parseInt(match[2], 10);
+        if (shardIndex < 1 || shardIndex > totalShards) {
+            throw new Error(`Shard index must be between 1 and total: ${shardIndex}/${totalShards}`);
+        }
+        return { shardIndex, totalShards };
+    }
+    /**
+     * Get recommended shard count based on test count
+     */
+    static getRecommendedShardCount(testCount, maxShards = 16) {
+        if (testCount < 10)
+            return 1;
+        if (testCount < 50)
+            return 2;
+        if (testCount < 100)
+            return 4;
+        if (testCount < 500)
+            return 8;
+        return Math.min(maxShards, Math.ceil(testCount / 100));
+    }
+    /**
+     * Get optimal shard count based on CPU cores
+     */
+    static getOptimalShardCount() {
+        const cpuCount = require('os').cpus().length;
+        // Leave one core for main process
+        return Math.max(1, cpuCount - 1);
+    }
+}
+/**
+ * Create a test sharding manager
+ */
+export function createTestSharding(config) {
+    return new TestSharding(config);
+}
+/**
+ * Create sharding from environment if enabled
+ */
+export function createShardingFromEnv() {
+    const config = TestSharding.fromEnv();
+    return config ? createTestSharding(config) : null;
+}
+/**
+ * Vitest filter function for sharding
+ * Usage: vitest.config.ts -> test.exclude = [..., createShardingExclude()]
+ */
+export function createShardingExclude() {
+    const sharding = createShardingFromEnv();
+    if (!sharding) {
+        return [];
+    }
+    // This doesn't work well with exclude, but we provide it for completeness
+    // Real filtering happens in the test suite
+    return [];
+}
+/**
+ * Setup sharding for Vitest
+ * Returns a function that can be used to filter tests
+ */
+export function setupVitestSharding() {
+    const sharding = createShardingFromEnv();
+    if (!sharding) {
+        return null;
+    }
+    const info = sharding.getShardInfo();
+    console.log(`🔪 Sharding enabled: shard ${info.shardId}`);
+    return (testId) => {
+        // Parse test ID (format: "filePath > testName")
+        const [filePath, testName] = testId.split(' > ');
+        const test = {
+            testId,
+            filePath: filePath || testId,
+            testName: testName || '',
+        };
+        return sharding.shouldRunTest(test);
+    };
+}
+/**
+ * Get shard-specific suffix for output files
+ * Prevents overwriting artifacts between shards
+ */
+export function getShardSuffix() {
+    const sharding = createShardingFromEnv();
+    if (!sharding) {
+        return '';
+    }
+    const info = sharding.getShardInfo();
+    return `.shard-${info.shardIndex}`;
+}
+/**
+ * Create shard-specific report filename
+ */
+export function getShardedFilename(baseName) {
+    const suffix = getShardSuffix();
+    const ext = baseName.match(/\.[^.]+$/)?.[0] || '';
+    const nameWithoutExt = baseName.replace(ext, '');
+    return `${nameWithoutExt}${suffix}${ext}`;
+}

package/dist/core/storage/cookie-manager.d.ts

@@ -0,0 +1,160 @@
+/**
+ * QA360 Cookie Manager Module
+ *
+ * P0: Cookie manipulation helpers
+ * - Get/set/delete cookies with type safety
+ * - Cookie filtering and searching
+ * - Domain/path scoping
+ * - Expiration handling
+ */
+import type { BrowserContext, Page } from '@playwright/test';
+import type { Cookie } from '@playwright/test';
+/**
+ * Cookie creation options
+ */
+export interface CookieSetOptions {
+    /** Cookie name */
+    name: string;
+    /** Cookie value */
+    value: string;
+    /** Cookie domain (defaults to current page domain) */
+    domain?: string;
+    /** Cookie path (defaults to /) */
+    path?: string;
+    /** Expiration date (Unix timestamp) or maxAge in seconds */
+    expires?: number;
+    /** Max age in seconds (alternative to expires) */
+    maxAge?: number;
+    /** Whether cookie is HTTP-only */
+    httpOnly?: boolean;
+    /** Whether cookie is secure (HTTPS only) */
+    secure?: boolean;
+    /** SameSite attribute */
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    /** URL for setting cookie (used for domain inference) */
+    url?: string;
+}
+/**
+ * Cookie filter options
+ */
+export interface CookieFilterOptions {
+    /** Filter by name (supports wildcards) */
+    name?: string;
+    /** Filter by domain */
+    domain?: string;
+    /** Filter by path */
+    path?: string;
+    /** Filter by secure flag */
+    secure?: boolean;
+    /** Filter by httpOnly flag */
+    httpOnly?: boolean;
+    /** Filter by sameSite attribute */
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * Cookie Manager
+ */
+export declare class CookieManager {
+    private context;
+    constructor(context: BrowserContext);
+    /**
+     * Get all cookies
+     */
+    all(): Promise<Cookie[]>;
+    /**
+     * Get cookies matching filter criteria
+     */
+    filter(options: CookieFilterOptions): Promise<Cookie[]>;
+    /**
+     * Get a specific cookie by name
+     */
+    get(name: string): Promise<Cookie | undefined>;
+    /**
+     * Get a cookie value by name
+     */
+    getValue(name: string): Promise<string | undefined>;
+    /**
+     * Check if a cookie exists
+     */
+    has(name: string): Promise<boolean>;
+    /**
+     * Set a cookie
+     */
+    set(options: CookieSetOptions): Promise<void>;
+    /**
+     * Set multiple cookies at once
+     */
+    setMany(cookies: CookieSetOptions[]): Promise<void>;
+    /**
+     * Update an existing cookie
+     */
+    update(name: string, updates: Partial<CookieSetOptions>): Promise<void>;
+    /**
+     * Delete a cookie by name
+     */
+    delete(name: string): Promise<void>;
+    /**
+     * Delete multiple cookies by name
+     */
+    deleteMany(names: string[]): Promise<void>;
+    /**
+     * Delete cookies matching filter criteria
+     */
+    deleteFilter(options: CookieFilterOptions): Promise<void>;
+    /**
+     * Clear all cookies
+     */
+    clear(): Promise<void>;
+    /**
+     * Clear cookies for a specific domain
+     */
+    clearDomain(domain: string): Promise<void>;
+    /**
+     * Get cookies count
+     */
+    count(): Promise<number>;
+    /**
+     * Export cookies as JSON string
+     */
+    export(): Promise<string>;
+    /**
+     * Import cookies from JSON string or array
+     */
+    import(data: string | Cookie[]): Promise<void>;
+    /**
+     * Get cookies grouped by domain
+     */
+    byDomain(): Promise<Record<string, Cookie[]>>;
+    /**
+     * Set a session cookie (no expiration)
+     */
+    setSession(name: string, value: string, options?: Partial<CookieSetOptions>): Promise<void>;
+    /**
+     * Set a cookie with max-age (in seconds)
+     */
+    setWithMaxAge(name: string, value: string, maxAge: number, options?: Partial<CookieSetOptions>): Promise<void>;
+    /**
+     * Set a cookie that expires in days
+     */
+    setExpiringIn(name: string, value: string, days: number, options?: Partial<CookieSetOptions>): Promise<void>;
+    /**
+     * Normalize cookie options to Playwright format
+     */
+    private normalizeCookieOptions;
+    /**
+     * Check if cookie matches filter criteria
+     */
+    private matchesFilter;
+    /**
+     * Simple wildcard matching
+     */
+    private wildcardMatch;
+}
+/**
+ * Convenience function to create cookie manager
+ */
+export declare function cookies(context: BrowserContext): CookieManager;
+/**
+ * Convenience function to create cookie manager from page
+ */
+export declare function cookiesFromPage(page: Page): CookieManager;