@silasfmartins/testhub 1.0.0

package/dist/src/utils/XPathCatalog.js

@@ -0,0 +1,350 @@
+/**
+ * XPath Catalog (v2.7.44 - items 17, 18, 19 & 21)
+ *
+ * Mantém catálogo de XPaths por página, atualizado via `extract_page_structure`,
+ * e oferece resolução inteligente para métodos de ação (click, fill, select…).
+ *
+ * Item 17 — `extractPageStructure` como base para catálogo
+ * Item 18 — `getCurrentXPathCatalog` + resolver interno
+ * Item 19 — Geração de `.autocore/xpaths.generated.ts` para IntelliSense
+ * Item 21 — `pushToBackend` para execuções Azure sem agente de IA
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { Logger } from './Logger.js';
+let _extractor = null;
+const DEFAULT_TTL_MS = 60_000;
+/** Normaliza URL para chave de cache (remove query/hash) */
+function normalizePageKey(url) {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${u.pathname}`.replace(/\/+$/, '').toLowerCase();
+    }
+    catch {
+        return url.toLowerCase().replace(/[?#].*$/, '').replace(/\/+$/, '');
+    }
+}
+// Cache interno
+const _cache = new Map();
+// ---------------------------------------------------------------------------
+// XPathCatalog
+// ---------------------------------------------------------------------------
+export class XPathCatalog {
+    /** Injeta extrator de estrutura de página (obrigatório antes de usar) */
+    static setExtractor(fn) {
+        _extractor = fn;
+    }
+    /**
+     * Obtém catálogo de XPaths para a página fornecida (ou a página atual).
+     *
+     * @param currentPageUrl URL da página atual (usada quando opts.page não informado)
+     * @param opts Opções de consulta
+     */
+    static async getCatalog(currentPageUrl, opts) {
+        const pageUrl = opts?.page || currentPageUrl;
+        const pageKey = normalizePageKey(pageUrl);
+        const strictPage = opts?.strictPage ?? true;
+        const maxItems = opts?.maxItems ?? 200;
+        // Verificar cache (se não forçar refresh)
+        if (!opts?.refresh) {
+            const cached = _cache.get(pageKey);
+            if (cached && Date.now() - cached.updatedAt < DEFAULT_TTL_MS) {
+                return XPathCatalog.applyFilter(cached.items, opts?.filter, maxItems);
+            }
+        }
+        // Extrair estrutura da página
+        const items = await XPathCatalog.refresh(pageUrl);
+        // Filtrar
+        let result = XPathCatalog.applyFilter(items, opts?.filter, maxItems);
+        // Cross-page fallback
+        if (result.length === 0 && !strictPage && opts?.filter) {
+            for (const [, entry] of _cache) {
+                const crossItems = XPathCatalog.applyFilter(entry.items, opts.filter, maxItems);
+                if (crossItems.length > 0) {
+                    result = crossItems;
+                    break;
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Recarrega a estrutura da página e atualiza o cache.
+     */
+    static async refresh(pageUrl) {
+        if (!_extractor) {
+            Logger.warning('[XPathCatalog] Extrator de página não configurado. Use XPathCatalog.setExtractor().');
+            return [];
+        }
+        const raw = await _extractor(pageUrl);
+        const items = XPathCatalog.flatten(raw);
+        const key = normalizePageKey(pageUrl);
+        _cache.set(key, { items, updatedAt: Date.now() });
+        return items;
+    }
+    /**
+     * Resolve um alvo (texto/xpath/id/name/placeholder) para o melhor XPath do catálogo.
+     * Retorna undefined se não encontrar match aceitável.
+     */
+    static resolveFromCatalog(target, pageUrl) {
+        const key = normalizePageKey(pageUrl);
+        const cached = _cache.get(key);
+        if (!cached)
+            return undefined;
+        // Se o alvo já é um XPath válido, verificar se existe no catálogo
+        if (target.startsWith('//') || target.startsWith('(//') || target.startsWith('xpath=')) {
+            return undefined; // Não resolver XPaths explícitos via catálogo
+        }
+        // Procurar match por texto/id/name/placeholder/ariaLabel
+        const scored = XPathCatalog.applyFilter(cached.items, target, 5);
+        if (scored.length > 0 && scored[0].score && scored[0].score >= 0.6) {
+            return scored[0].xpath;
+        }
+        return undefined;
+    }
+    /** Limpa cache de uma página específica ou todo o cache */
+    static clearCache(pageUrl) {
+        if (pageUrl) {
+            _cache.delete(normalizePageKey(pageUrl));
+        }
+        else {
+            _cache.clear();
+        }
+    }
+    // ---------- Item 21 — Azure DOM push ----------
+    /**
+     * Envia DOM/pageStructure capturado localmente para o backend processar.
+     *
+     * Usado em execuções Azure/CI onde o backend **não** tem acesso de rede
+     * à página alvo. O framework captura `pageHtml` e/ou `pageStructure`
+     * e envia para `POST /api/xpath-catalog/extract`.
+     *
+     * O backend enriquece com hints Redis e retorna catálogo + xpaths.
+     * O resultado alimenta o cache local por página.
+     *
+     * @param request Payload com URL, pageHtml/pageStructure e filtro opcional
+     * @param authToken JWT ou chave de automação (header Authorization)
+     * @returns Resposta do backend com catálogo enriquecido
+     *
+     * @example
+     * ```ts
+     * const html = await page.content()
+     * const result = await XPathCatalog.pushToBackend({
+     *   url: page.url(),
+     *   pageHtml: html,
+     *   filter: 'cliente',
+     * })
+     * if (result?.catalog) {
+     *   // catálogo já está no cache; usar via getCatalog()
+     * }
+     * ```
+     */
+    static async pushToBackend(request, authToken) {
+        const backendUrl = (process.env.AUTOCORE_HUB_URL ||
+            process.env.AUTOCORE_HUB_IP ||
+            '').replace(/\/$/, '');
+        if (!backendUrl) {
+            Logger.warning('[XPathCatalog] AUTOCORE_HUB_URL não configurado; pushToBackend ignorado.');
+            return null;
+        }
+        const headers = {
+            'Content-Type': 'application/json',
+            'x-automation-key': process.env.AUTOCORE_AUTOMATION_KEY || 'd8f3c4a9be7f29d1c6e04fa1a39c2e7bd91f57c8a3de45eb91c4f7a2d0e3b8fa',
+        };
+        if (authToken) {
+            headers['Authorization'] = authToken.startsWith('Bearer ') ? authToken : `Bearer ${authToken}`;
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const res = await fetch(`${backendUrl}/api/xpath-catalog/extract`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(request),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                Logger.warning(`[XPathCatalog] pushToBackend falhou: HTTP ${res.status} — ${text}`);
+                return { success: false, error: `HTTP ${res.status}` };
+            }
+            const data = (await res.json());
+            // Alimentar cache local com catálogo retornado
+            if (data.success && data.catalog?.length) {
+                const key = normalizePageKey(request.url);
+                _cache.set(key, { items: data.catalog, updatedAt: Date.now() });
+                Logger.info(`[XPathCatalog] pushToBackend: ${data.catalog.length} itens recebidos para ${request.url}`);
+            }
+            return data;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            Logger.warning(`[XPathCatalog] pushToBackend erro: ${msg}`);
+            return { success: false, error: msg };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    // ---------- IntelliSense file generation (Item 19) ----------
+    /**
+     * Gera arquivo `.autocore/xpaths.generated.ts` com constantes tipadas por tela.
+     *
+     * @param outputDir Diretório de saída (default: `.autocore` na raiz do projeto)
+     */
+    static generateIntelliSenseFile(outputDir) {
+        const dir = outputDir || path.resolve(process.cwd(), '.autocore');
+        const filePath = path.join(dir, 'xpaths.generated.ts');
+        if (_cache.size === 0) {
+            Logger.info('[XPathCatalog] Nenhum catálogo em cache; IntelliSense não gerado.');
+            return;
+        }
+        const lines = [
+            '// Auto-generated by @silasfmartins/testhub XPathCatalog',
+            '// Do not edit manually — regenerated a cada extract_page_structure',
+            '',
+        ];
+        for (const [pageKey, entry] of _cache) {
+            const blockName = XPathCatalog.pageKeyToConstName(pageKey);
+            lines.push(`export const ${blockName} = {`);
+            const seen = new Set();
+            for (const item of entry.items) {
+                if (!item.xpath)
+                    continue;
+                const propName = XPathCatalog.itemToPropName(item);
+                if (seen.has(propName))
+                    continue;
+                seen.add(propName);
+                const safeXPath = item.xpath.replace(/'/g, "\\'");
+                lines.push(`  ${propName}: '${safeXPath}',`);
+            }
+            lines.push('} as const');
+            lines.push('');
+        }
+        try {
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(filePath, lines.join('\n'), 'utf-8');
+            Logger.info(`[XPathCatalog] IntelliSense gerado: ${filePath}`);
+        }
+        catch (err) {
+            Logger.warning(`[XPathCatalog] Falha ao gerar IntelliSense: ${err}`);
+        }
+    }
+    // ---------- Utilitários internos ----------
+    /** Converte estrutura bruta em lista flat de XPathCatalogItem */
+    static flatten(raw) {
+        const items = [];
+        const push = (arr) => {
+            if (!arr)
+                return;
+            for (const el of arr) {
+                if (el.xpath)
+                    items.push(el);
+            }
+        };
+        push(raw.inputs);
+        push(raw.buttons);
+        push(raw.links);
+        push(raw.headings);
+        push(raw.elements);
+        return items;
+    }
+    /** Aplica filtro textual e ordena por relevância */
+    static applyFilter(items, filter, max) {
+        if (!filter || filter.trim() === '') {
+            return items.slice(0, max);
+        }
+        const tokens = filter.toLowerCase().split(/\s+/);
+        const scored = [];
+        for (const item of items) {
+            const haystack = [
+                item.text,
+                item.id,
+                item.name,
+                item.placeholder,
+                item.ariaLabel,
+                item.title,
+                item.role,
+                item.dataTestId,
+                item.className,
+                item.tag,
+            ]
+                .filter(Boolean)
+                .join(' ')
+                .toLowerCase();
+            let matched = 0;
+            for (const t of tokens) {
+                if (haystack.includes(t))
+                    matched++;
+            }
+            if (matched > 0) {
+                const score = matched / tokens.length;
+                scored.push({ ...item, score });
+            }
+        }
+        // Ordenar: maior score primeiro; em empate, inputs > buttons > links
+        scored.sort((a, b) => {
+            const sa = a.score ?? 0;
+            const sb = b.score ?? 0;
+            if (sb !== sa)
+                return sb - sa;
+            return tagPriority(a.tag) - tagPriority(b.tag);
+        });
+        return scored.slice(0, max);
+    }
+    /** Converte pageKey em nome de constante TypeScript */
+    static pageKeyToConstName(pageKey) {
+        // Ex: "https://app.example.com/catalogo/ofertas" → "XPATH_CATALOGO_OFERTAS"
+        const segments = pageKey
+            .replace(/^https?:\/\/[^/]+/, '')
+            .replace(/^\//, '')
+            .split('/')
+            .filter(Boolean);
+        if (segments.length === 0)
+            return 'XPATH_HOME';
+        return ('XPATH_' +
+            segments
+                .map((s) => s
+                .replace(/[^a-zA-Z0-9_]/g, '_')
+                .replace(/_+/g, '_')
+                .toUpperCase())
+                .join('_'));
+    }
+    /** Converte item em nome de propriedade para IntelliSense */
+    static itemToPropName(item) {
+        const tag = (item.tag || 'EL').toUpperCase();
+        const label = item.id ||
+            item.dataTestId ||
+            item.name ||
+            item.ariaLabel ||
+            item.placeholder ||
+            item.title ||
+            item.text ||
+            '';
+        const clean = label
+            .substring(0, 40)
+            .replace(/[^a-zA-Z0-9]/g, '_')
+            .replace(/_+/g, '_')
+            .replace(/^_|_$/g, '')
+            .toUpperCase();
+        return clean ? `${tag}_${clean}` : `${tag}_${Math.random().toString(36).slice(2, 6).toUpperCase()}`;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function tagPriority(tag) {
+    switch (tag?.toLowerCase()) {
+        case 'input':
+        case 'textarea':
+        case 'select':
+            return 0;
+        case 'button':
+            return 1;
+        case 'a':
+            return 2;
+        default:
+            return 3;
+    }
+}

package/dist/src/utils/generators.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Geradores de dados para testes seguindo padrões DDD
+ * @module Utils/Generators
+ *
+ * 🎯 OBJETIVO: Generators de dados de teste padronizados
+ * - ✅ Geradores compatíveis com schemas de validação
+ * - ✅ Dados determinísticos para testes reproduzíveis
+ * - ✅ Integração com Domain Entities (TestExecution, TestReport)
+ * - ✅ Suporte a dados complexos para APIs e formulários
+ *
+ * 🏗️ ARQUITETURA DDD:
+ * - Domain Layer: Value Objects (CPF, CNPJ, Email)
+ * - Application Layer: Casos de uso específicos (generateApiTestData)
+ * - Infrastructure Layer: Implementações específicas de geradores
+ *
+ * EXEMPLO USO SIMPLES:
+ * ```typescript
+ * const id = generateRandomAlphanumeric(10)
+ * const email = generateEmail()
+ * ```
+ *
+ * EXEMPLO USO AVANÇADO:
+ * ```typescript
+ * const testData = generateCompleteFormData({
+ *   includeOptional: true,
+ *   locale: 'pt-BR'
+ * })
+ * ```
+ */
+/**
+ * Gera UUID alfanumérico de tamanho específico
+ * @param length Comprimento desejado
+ * @returns String alfanumérica baseada em UUID
+ */
+export declare function generateRandomAlphanumericUUID(length: number): string;
+/**
+ * Gera ID externo complexo para simulação de sistemas legados
+ * @returns ID no formato system1-system2-0xhexadecimal
+ */
+export declare function generateComplexExternalId(): string;
+/**
+ * Gera string alfanumérica aleatória
+ * @param length Comprimento desejado
+ * @returns String alfanumérica
+ */
+export declare function generateRandomAlphanumeric(length: number): string;
+/**
+ * Gera string numérica aleatória
+ * @param length Comprimento desejado
+ * @returns String numérica
+ */
+export declare function generateRandomNumeric(length: number): string;
+/**
+ * 🆕 DDD: Gera email válido para testes
+ * @param domain Domínio opcional (padrão: 'test.com')
+ * @returns Email válido para testes
+ */
+export declare function generateEmail(domain?: string): string;
+/**
+ * 🆕 DDD: Gera CPF válido para testes (apenas dígitos)
+ * @returns CPF válido no formato 11111111111
+ */
+export declare function generateCPF(): string;
+/**
+ * 🆕 DDD: Gera telefone brasileiro válido
+ * @param withAreaCode Se deve incluir código de área
+ * @returns Telefone no formato 11999999999 ou 999999999
+ */
+export declare function generatePhoneBR(withAreaCode?: boolean): string;
+/**
+ * 🆕 DDD: Gera dados completos para formulários
+ * @param options Opções de geração
+ * @returns Objeto com dados completos para teste
+ */
+export declare function generateCompleteFormData(options?: {
+    includeOptional?: boolean;
+    locale?: 'pt-BR' | 'en-US';
+}): {
+    name: string;
+    email: string;
+    phone: string;
+    document: string;
+    address?: {
+        street: string;
+        number: string;
+        city: string;
+        zipCode: string;
+    };
+};
+export declare function generateServiceNowTaskId(): string;

package/dist/src/utils/generators.js

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Geradores de dados para testes seguindo padrões DDD
+ * @module Utils/Generators
+ *
+ * 🎯 OBJETIVO: Generators de dados de teste padronizados
+ * - ✅ Geradores compatíveis com schemas de validação
+ * - ✅ Dados determinísticos para testes reproduzíveis
+ * - ✅ Integração com Domain Entities (TestExecution, TestReport)
+ * - ✅ Suporte a dados complexos para APIs e formulários
+ *
+ * 🏗️ ARQUITETURA DDD:
+ * - Domain Layer: Value Objects (CPF, CNPJ, Email)
+ * - Application Layer: Casos de uso específicos (generateApiTestData)
+ * - Infrastructure Layer: Implementações específicas de geradores
+ *
+ * EXEMPLO USO SIMPLES:
+ * ```typescript
+ * const id = generateRandomAlphanumeric(10)
+ * const email = generateEmail()
+ * ```
+ *
+ * EXEMPLO USO AVANÇADO:
+ * ```typescript
+ * const testData = generateCompleteFormData({
+ *   includeOptional: true,
+ *   locale: 'pt-BR'
+ * })
+ * ```
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * Gera UUID alfanumérico de tamanho específico
+ * @param length Comprimento desejado
+ * @returns String alfanumérica baseada em UUID
+ */
+export function generateRandomAlphanumericUUID(length) {
+    // Gera um UUID e remove os hífens para ter mais caracteres disponíveis
+    const uuid = randomUUID().replace(/-/g, '');
+    // Se o comprimento solicitado for maior que o UUID disponível,
+    // repete o processo até ter caracteres suficientes
+    let result = uuid;
+    while (result.length < length) {
+        result += randomUUID().replace(/-/g, '');
+    }
+    // Retorna apenas a quantidade de caracteres solicitada
+    return result.substring(0, length);
+}
+/**
+ * Gera ID externo complexo para simulação de sistemas legados
+ * @returns ID no formato system1-system2-0xhexadecimal
+ */
+export function generateComplexExternalId() {
+    const hex = 'abcdef0123456789';
+    const randomHex = (length) => Array.from({ length }, () => hex[Math.floor(Math.random() * hex.length)]).join('');
+    const part1 = randomHex(32);
+    const part2 = randomHex(32);
+    const part3 = '0x' +
+        randomHex(30) +
+        String.fromCharCode(97 + Math.floor(Math.random() * 26)); // adiciona uma letra no final
+    return `${part1}-${part2}${part3}`;
+}
+/**
+ * Gera string alfanumérica aleatória
+ * @param length Comprimento desejado
+ * @returns String alfanumérica
+ */
+export function generateRandomAlphanumeric(length) {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    let result = '';
+    for (let i = 0; i < length; i++) {
+        result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+}
+/**
+ * Gera string numérica aleatória
+ * @param length Comprimento desejado
+ * @returns String numérica
+ */
+export function generateRandomNumeric(length) {
+    const digits = '0123456789';
+    let result = '';
+    for (let i = 0; i < length; i++) {
+        result += digits.charAt(Math.floor(Math.random() * digits.length));
+    }
+    return result;
+}
+/**
+ * 🆕 DDD: Gera email válido para testes
+ * @param domain Domínio opcional (padrão: 'test.com')
+ * @returns Email válido para testes
+ */
+export function generateEmail(domain = 'test.com') {
+    const username = generateRandomAlphanumeric(8).toLowerCase();
+    return `${username}@${domain}`;
+}
+/**
+ * 🆕 DDD: Gera CPF válido para testes (apenas dígitos)
+ * @returns CPF válido no formato 11111111111
+ */
+export function generateCPF() {
+    // Gera os 9 primeiros dígitos
+    const nineDegits = Array.from({ length: 9 }, () => Math.floor(Math.random() * 10));
+    // Calcula o primeiro dígito verificador
+    let sum = 0;
+    for (let i = 0; i < 9; i++) {
+        sum += nineDegits[i] * (10 - i);
+    }
+    const firstDigit = (sum * 10) % 11;
+    const firstVerifier = firstDigit < 10 ? firstDigit : 0;
+    // Calcula o segundo dígito verificador
+    sum = 0;
+    for (let i = 0; i < 9; i++) {
+        sum += nineDegits[i] * (11 - i);
+    }
+    sum += firstVerifier * 2;
+    const secondDigit = (sum * 10) % 11;
+    const secondVerifier = secondDigit < 10 ? secondDigit : 0;
+    return [...nineDegits, firstVerifier, secondVerifier].join('');
+}
+/**
+ * 🆕 DDD: Gera telefone brasileiro válido
+ * @param withAreaCode Se deve incluir código de área
+ * @returns Telefone no formato 11999999999 ou 999999999
+ */
+export function generatePhoneBR(withAreaCode = true) {
+    const areaCode = withAreaCode ? generateRandomNumeric(2) : '';
+    const firstDigit = '9'; // Celular sempre inicia com 9
+    const restDigits = generateRandomNumeric(8);
+    return `${areaCode}${firstDigit}${restDigits}`;
+}
+/**
+ * 🆕 DDD: Gera dados completos para formulários
+ * @param options Opções de geração
+ * @returns Objeto com dados completos para teste
+ */
+export function generateCompleteFormData(options) {
+    const locale = options?.locale || 'pt-BR';
+    const includeOptional = options?.includeOptional;
+    const data = {
+        name: `Test User ${generateRandomAlphanumeric(4)}`,
+        email: generateEmail(),
+        phone: locale === 'pt-BR' ? generatePhoneBR() : generateRandomNumeric(10),
+        document: locale === 'pt-BR' ? generateCPF() : generateRandomNumeric(9),
+    };
+    if (includeOptional) {
+        return {
+            ...data,
+            address: {
+                street: `Test Street ${generateRandomAlphanumeric(3)}`,
+                number: generateRandomNumeric(3),
+                city: 'Test City',
+                zipCode: locale === 'pt-BR'
+                    ? generateRandomNumeric(8)
+                    : generateRandomNumeric(5),
+            },
+        };
+    }
+    return data;
+}
+export function generateServiceNowTaskId() {
+    const hex = 'abcdef0123456789';
+    const randomHex = (length) => Array.from({ length }, () => hex[Math.floor(Math.random() * hex.length)]).join('');
+    const part1 = randomHex(32);
+    const part2 = randomHex(31);
+    return `${part1}x${part2}`;
+}