@silasfmartins/testhub 1.0.0

package/dist/src/utils/testRecovery/TestRecoveryClient.js

@@ -0,0 +1,1415 @@
+/** Lista de actionTypes válidos para validação */
+export const VALID_ACTION_TYPES = [
+    "click",
+    "fill",
+    "select",
+    "hover",
+    "check",
+    "uncheck",
+    "press",
+    "wait",
+    "navigate",
+    "doubleClick",
+];
+/**
+ * Mapeamento de nomes de métodos WebActions para actionTypes do Test Recovery
+ * Usado para normalizar o actionType quando vem do wrapper automático
+ */
+export const METHOD_TO_ACTION_TYPE = {
+    // Fill/Input
+    setText: "fill",
+    fill: "fill",
+    type: "fill",
+    preencher: "fill",
+    // Click
+    click: "click",
+    clicar: "click",
+    // Double Click
+    doubleClick: "doubleClick",
+    dblclick: "doubleClick",
+    duploClique: "doubleClick",
+    // Select
+    selectOption: "select",
+    selectDropdown: "select",
+    selectFromList: "select",
+    selectTableOption: "select",
+    selecionarOpcao: "select",
+    // Hover
+    hover: "hover",
+    mouseOver: "hover",
+    // Press Key
+    pressKey: "press",
+    press: "press",
+    keyboard: "press",
+    // Check/Uncheck
+    check: "check",
+    uncheck: "uncheck",
+    marcarCheckbox: "check",
+    desmarcarCheckbox: "uncheck",
+    // Wait
+    waitForVisible: "wait",
+    waitForVisibleBoolean: "wait",
+    waitForNetworkIdle: "wait",
+    waitForSelector: "wait",
+    waitForHidden: "wait",
+    aguardarVisivel: "wait",
+    fixedWait: "wait",
+    // Navigate
+    navigateTo: "navigate",
+    goto: "navigate",
+    navigate: "navigate",
+    navegar: "navigate",
+    // Frame (mapeia para click como fallback)
+    switchTo: "click",
+    trocarFrame: "click",
+};
+/**
+ * Converte nome de método WebActions para actionType do Test Recovery
+ * @param methodName Nome do método (ex: 'setText', 'click', 'waitForVisible')
+ * @returns ActionType normalizado
+ */
+export function methodToActionType(methodName) {
+    const mapped = METHOD_TO_ACTION_TYPE[methodName];
+    if (mapped)
+        return mapped;
+    // Fallback: tentar inferir pelo nome
+    const lower = methodName.toLowerCase();
+    if (lower.includes("wait") || lower.includes("aguardar"))
+        return "wait";
+    if (lower.includes("fill") ||
+        lower.includes("text") ||
+        lower.includes("preencher"))
+        return "fill";
+    if (lower.includes("click") || lower.includes("clicar"))
+        return "click";
+    if (lower.includes("select") || lower.includes("selecionar"))
+        return "select";
+    if (lower.includes("hover"))
+        return "hover";
+    if (lower.includes("press") || lower.includes("key"))
+        return "press";
+    if (lower.includes("check"))
+        return "check";
+    if (lower.includes("navigate") ||
+        lower.includes("goto") ||
+        lower.includes("navegar"))
+        return "navigate";
+    // Default
+    return "click";
+}
+/** Lista de errorTypes válidos para validação */
+export const VALID_ERROR_TYPES = [
+    "not_found",
+    "multiple_elements",
+    "timeout",
+    "wrong_navigation",
+    "stale_element",
+];
+/**
+ * Valida se um actionType é válido
+ */
+export function isValidActionType(action) {
+    return !!action && VALID_ACTION_TYPES.includes(action);
+}
+/**
+ * Valida se um errorType é válido
+ */
+export function isValidErrorType(error) {
+    return !!error && VALID_ERROR_TYPES.includes(error);
+}
+/**
+ * Infere o actionType baseado no contexto do XPath ou elemento
+ * Útil quando o actionType não é fornecido explicitamente
+ */
+export function inferActionType(xpath, context) {
+    const xpathLower = xpath.toLowerCase();
+    const contextText = context?.text?.toLowerCase() ?? "";
+    const contextRole = context?.role?.toLowerCase() ?? "";
+    const contextType = context?.type?.toLowerCase() ?? "";
+    // Checkbox/radio → check
+    if (xpathLower.includes("checkbox") ||
+        xpathLower.includes('type="checkbox"') ||
+        xpathLower.includes('type="radio"') ||
+        contextType === "checkbox" ||
+        contextType === "radio" ||
+        contextRole === "checkbox" ||
+        contextRole === "radio") {
+        return "check";
+    }
+    // Select/dropdown → select
+    if (xpathLower.includes("select") ||
+        xpathLower.includes("dropdown") ||
+        xpathLower.includes("combobox") ||
+        xpathLower.includes("listbox") ||
+        contextRole === "combobox" ||
+        contextRole === "listbox" ||
+        contextRole === "option") {
+        return "select";
+    }
+    // Input/textarea → fill
+    if (xpathLower.includes("input") ||
+        xpathLower.includes("textarea") ||
+        xpathLower.includes('type="text"') ||
+        xpathLower.includes('type="password"') ||
+        xpathLower.includes('type="email"') ||
+        xpathLower.includes('type="number"') ||
+        xpathLower.includes('type="search"') ||
+        xpathLower.includes('type="tel"') ||
+        xpathLower.includes('type="url"') ||
+        contextRole === "textbox" ||
+        contextType === "text" ||
+        contextType === "password" ||
+        contextType === "email") {
+        return "fill";
+    }
+    // Hover keywords
+    if (contextText.includes("menu") ||
+        contextText.includes("tooltip") ||
+        xpathLower.includes("menu") ||
+        xpathLower.includes("tooltip") ||
+        xpathLower.includes("dropdown-toggle")) {
+        return "hover";
+    }
+    // Keyboard/press
+    if (contextText.includes("enter") ||
+        contextText.includes("escape") ||
+        contextText.includes("tab")) {
+        return "press";
+    }
+    // Default: click (botões, links, etc)
+    return "click";
+}
+// Adapted host resolution and resilient fetch (inspired by TestHubClient)
+import * as os from "os";
+import { Logger } from "../Logger.js";
+import { TestContext } from "../../testContext/TestContext.js";
+function isAzureEnvironment() {
+    // Forçar modo LOCAL via variável de ambiente (override explícito)
+    if (process.env.AUTOCORE_FORCE_LOCAL === "true")
+        return false;
+    // Variáveis exclusivas do Azure Pipelines / CI
+    if (process.env.TF_BUILD === "True" || process.env.AGENT_NAME)
+        return true;
+    if (process.env.CI === "true" || process.env.BUILD_BUILDID)
+        return true;
+    // NOTA: os.platform() foi removido propositalmente.
+    // macOS (darwin) e Linux são plataformas de desenvolvimento local válidas.
+    // Apenas variáveis de CI/CD indicam execução remota.
+    return false;
+}
+function isLikelyTestFileEntry(value) {
+    const lowered = value.toLowerCase();
+    return (lowered.includes(".spec.") ||
+        lowered.includes(".test.") ||
+        lowered.endsWith(".feature") ||
+        lowered.includes("/") ||
+        lowered.includes("\\"));
+}
+function parseCnCtFromTitlePath(testInfo) {
+    try {
+        const rawPath = Array.isArray(testInfo?.titlePath)
+            ? testInfo.titlePath
+            : [];
+        const cleaned = rawPath
+            .map((entry) => String(entry || "").trim())
+            .filter((entry) => !!entry && !isLikelyTestFileEntry(entry));
+        if (cleaned.length >= 2) {
+            const ctName = cleaned[cleaned.length - 1];
+            const cnName = cleaned[cleaned.length - 2];
+            return {
+                cnName,
+                ctName,
+                methodName: ctName,
+            };
+        }
+        const fallbackTitle = String(testInfo?.title || "").trim();
+        if (fallbackTitle) {
+            return {
+                cnName: fallbackTitle,
+                ctName: fallbackTitle,
+                methodName: fallbackTitle,
+            };
+        }
+    }
+    catch {
+        // no-op
+    }
+    return {};
+}
+/**
+ * Obtém metadados de recovery a partir de variáveis de ambiente e TestContext (v2.7.43)
+ * - executionSource: detecta automaticamente LOCAL vs AZURE
+ * - testCaseName/testCaseId/testMethodName: obtém do TestContext.testInfo quando disponível
+ */
+export function getRecoveryMetadata() {
+    const executionSource = isAzureEnvironment()
+        ? "AZURE"
+        : "LOCAL";
+    let testCaseName;
+    let testCaseId;
+    let testMethodName;
+    // Obter do env (podem ser setados pelo runner/CI)
+    testCaseName = process.env.AUTOCORE_TEST_CASE_NAME || undefined;
+    testCaseId = process.env.AUTOCORE_TEST_CASE_ID || undefined;
+    testMethodName = process.env.AUTOCORE_TEST_METHOD_NAME || undefined;
+    // Tentar obter do TestContext.testInfo (Playwright) sem require dinâmico.
+    try {
+        const testInfo = TestContext?.testInfo || TestContext?.getSafeTestInfo?.();
+        if (testInfo) {
+            const parsed = parseCnCtFromTitlePath(testInfo);
+            if (!testCaseName) {
+                testCaseName = parsed.cnName || testInfo.title || undefined;
+            }
+            if (!testMethodName) {
+                testMethodName =
+                    parsed.methodName || parsed.ctName || testInfo.title || undefined;
+            }
+            if (!testCaseId) {
+                const ctCandidate = parsed.ctName || testInfo.title || "";
+                const ctMatch = ctCandidate.match(/\b(CT[-_]?\d+)\b/i);
+                testCaseId = ctMatch?.[1] || ctCandidate || undefined;
+            }
+        }
+    }
+    catch {
+        // TestContext pode não estar disponível
+    }
+    if (!testCaseName)
+        testCaseName = process.env.AUTOCORE_CN_NAME || undefined;
+    if (!testCaseId)
+        testCaseId = process.env.AUTOCORE_CT_NAME || undefined;
+    if (!testMethodName)
+        testMethodName =
+            process.env.AUTOCORE_TEST_METHOD || testCaseId || undefined;
+    return { executionSource, testCaseName, testCaseId, testMethodName };
+}
+const HUB_URL_HOSTNAME = "http://brtlvlty0559pl:3333";
+const HUB_URL_IP = "http://10.129.170.238:3333";
+function getAutoCorehubUrl() {
+    if (process.env.AUTOCORE_HUB_URL?.trim()) {
+        return process.env.AUTOCORE_HUB_URL.trim();
+    }
+    if (process.env.AUTOCORE_HUB_IP?.trim()) {
+        return process.env.AUTOCORE_HUB_IP.trim();
+    }
+    if (isAzureEnvironment())
+        return HUB_URL_IP;
+    return HUB_URL_HOSTNAME;
+}
+function getFallbackHubUrl(currentUrl) {
+    if (currentUrl === HUB_URL_HOSTNAME)
+        return HUB_URL_IP;
+    return null;
+}
+async function fetchWithTimeout(url, options = {}) {
+    const { timeout = 60000, ...fetchOptions } = options;
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), timeout);
+    try {
+        const res = await fetch(url, {
+            ...fetchOptions,
+            signal: controller.signal,
+        });
+        return res;
+    }
+    finally {
+        clearTimeout(id);
+    }
+}
+/**
+ * Constrói headers padrão para requisições ao AutoCore Hub
+ * Usa o mesmo x-automation-key do TestHubClient
+ */
+function authHeaders() {
+    return {
+        "Content-Type": "application/json",
+        "x-automation-key": "d8f3c4a9be7f29d1c6e04fa1a39c2e7bd91f57c8a3de45eb91c4f7a2d0e3b8fa",
+    };
+}
+async function postJsonWithFallback(path, body, timeout = 60000, extraHeaders) {
+    const base = getAutoCorehubUrl();
+    const fallback = getFallbackHubUrl(base);
+    const headers = { ...authHeaders(), ...extraHeaders };
+    // Se não houver fallback, fazer apenas uma requisição
+    if (!fallback) {
+        return await fetchWithTimeout(`${base}${path}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            timeout,
+        });
+    }
+    // ✅ Promise.all: Tentar ambas URLs em paralelo (primary + fallback)
+    const [primaryResult, fallbackResult] = await Promise.allSettled([
+        fetchWithTimeout(`${base}${path}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            timeout,
+        }),
+        fetchWithTimeout(`${fallback}${path}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            timeout,
+        }),
+    ]);
+    // Priorizar resultado primário se sucesso
+    if (primaryResult.status === "fulfilled" && primaryResult.value.ok) {
+        return primaryResult.value;
+    }
+    // Usar fallback se primário falhou
+    if (fallbackResult.status === "fulfilled" && fallbackResult.value.ok) {
+        return fallbackResult.value;
+    }
+    // Se ambos falharam, retornar o erro do primário
+    if (primaryResult.status === "fulfilled") {
+        return primaryResult.value;
+    }
+    throw primaryResult.reason;
+}
+async function getJsonWithFallback(path, timeout = 60000) {
+    const base = getAutoCorehubUrl();
+    const fallback = getFallbackHubUrl(base);
+    // Se não houver fallback, fazer apenas uma requisição
+    if (!fallback) {
+        return await fetchWithTimeout(`${base}${path}`, {
+            method: "GET",
+            headers: authHeaders(),
+            timeout,
+        });
+    }
+    // ✅ Promise.all: Tentar ambas URLs em paralelo (primary + fallback)
+    const [primaryResult, fallbackResult] = await Promise.allSettled([
+        fetchWithTimeout(`${base}${path}`, {
+            method: "GET",
+            headers: authHeaders(),
+            timeout,
+        }),
+        fetchWithTimeout(`${fallback}${path}`, {
+            method: "GET",
+            headers: authHeaders(),
+            timeout,
+        }),
+    ]);
+    // Priorizar resultado primário se sucesso
+    if (primaryResult.status === "fulfilled" && primaryResult.value.ok) {
+        return primaryResult.value;
+    }
+    // Usar fallback se primário falhou
+    if (fallbackResult.status === "fulfilled" && fallbackResult.value.ok) {
+        return fallbackResult.value;
+    }
+    // Se ambos falharam, retornar o erro do primário
+    if (primaryResult.status === "fulfilled") {
+        return primaryResult.value;
+    }
+    throw primaryResult.reason;
+}
+export async function getRecurringFailures(params = {}) {
+    const days = params.days ?? 7;
+    const minOccurrences = params.minOccurrences ?? 3;
+    const limit = params.limit ?? 20;
+    const q = `?days=${encodeURIComponent(String(days))}&minOccurrences=${encodeURIComponent(String(minOccurrences))}&limit=${encodeURIComponent(String(limit))}`;
+    try {
+        const res = await getJsonWithFallback(`/api/auto-healing/recurring-failures${q}`);
+        if (!res || !res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+export async function suggestRefactor(xpath) {
+    try {
+        const res = await getJsonWithFallback(`/api/auto-healing/suggest-refactor?xpath=${encodeURIComponent(xpath)}`);
+        if (!res || !res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+export async function impactAnalysis(xpath) {
+    try {
+        const res = await getJsonWithFallback(`/api/auto-healing/impact-analysis/${encodeURIComponent(xpath)}`);
+        if (!res || !res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Valida se o payload tem estrutura de página (obrigatório para análise)
+ */
+function hasPageContext(body) {
+    // pageStructure com pelo menos um array preenchido
+    if (body.pageStructure) {
+        const { buttons, inputs, links, elements, headings } = body.pageStructure;
+        if ((buttons && buttons.length > 0) ||
+            (inputs && inputs.length > 0) ||
+            (links && links.length > 0) ||
+            (elements && elements.length > 0) ||
+            (headings && headings.length > 0)) {
+            return true;
+        }
+    }
+    // pageHtml com conteúdo
+    if (body.pageHtml && body.pageHtml.length > 100) {
+        return true;
+    }
+    return false;
+}
+export async function analyzeFailure(body) {
+    try {
+        // Auto-enriquecer com metadados de recovery quando não fornecidos (v2.7.43)
+        const meta = getRecoveryMetadata();
+        // Validar e preparar payload
+        // Construir actor a partir de UserHeaders se não fornecido explicitamente (item 23 v2.7.44)
+        const resolvedActor = body.actor || buildActorFromEnv();
+        const payload = {
+            ...body,
+            actionType: body.actionType,
+            errorType: body.errorType,
+            executionSource: body.executionSource || meta.executionSource,
+            testCaseName: body.testCaseName || meta.testCaseName,
+            testCaseId: body.testCaseId || meta.testCaseId,
+            testMethodName: body.testMethodName || meta.testMethodName,
+            actor: resolvedActor,
+        };
+        // ⚠️ Validar pageStructure ou pageHtml (obrigatório conforme guia)
+        if (!hasPageContext(body)) {
+            Logger.warning("[TestRecoveryClient] ⚠️ AVISO: pageStructure ou pageHtml não fornecido. A análise pode ter baixa qualidade. Use extract_page_structure ou page.content() para capturar o contexto.");
+        }
+        // Validar/inferir actionType
+        if (!isValidActionType(payload.actionType)) {
+            const contextForInference = body.context
+                ? {
+                    text: body.context.text,
+                    role: body.context.role,
+                    type: body.context.type,
+                }
+                : undefined;
+            const inferred = inferActionType(body.failedXPath, contextForInference);
+            Logger.warning(`[TestRecoveryClient] actionType "${body.actionType}" inválido ou ausente. Inferido: "${inferred}" baseado no XPath/contexto.`);
+            payload.actionType = inferred;
+        }
+        // Validar errorType
+        if (!isValidErrorType(payload.errorType)) {
+            Logger.warning(`[TestRecoveryClient] errorType "${body.errorType}" inválido. Usando "not_found" como fallback.`);
+            payload.errorType = "not_found";
+        }
+        // (v2.7.44 - item 14) Enriquecer selectorAliases para fill de username/login
+        const actionStr = String(payload.actionType);
+        if ((actionStr === "fill" || actionStr === "type") &&
+            payload.failedXPath &&
+            !payload.context?.selectorAliases) {
+            const xp = payload.failedXPath;
+            if (!payload.context)
+                payload.context = {};
+            payload.context.selectorAliases = {
+                selector: xp,
+                ref: xp,
+                xpath: xp,
+            };
+        }
+        // 📤 LOG SIMPLIFICADO DA REQUISIÇÃO
+        Logger.info(`[TestRecoveryClient] 📤 Analisando falha no XPath: ${payload.failedXPath}`);
+        // CN/CT/Method + executionSource headers (v2.7.44 - item 10)
+        const analyzeHeaders = getSingletonUserHeaders();
+        if (payload.testCaseName) {
+            analyzeHeaders["x-test-case-name"] = payload.testCaseName;
+            analyzeHeaders["x-cn"] = payload.testCaseName;
+            analyzeHeaders["x-test-name"] = payload.testCaseName;
+            analyzeHeaders["x-cn-name"] = payload.testCaseName;
+        }
+        if (payload.testCaseId) {
+            analyzeHeaders["x-test-case-id"] = payload.testCaseId;
+            analyzeHeaders["x-ct"] = payload.testCaseId;
+            analyzeHeaders["x-test-id"] = payload.testCaseId;
+            analyzeHeaders["x-ct-id"] = payload.testCaseId;
+        }
+        if (payload.testMethodName) {
+            analyzeHeaders["x-test-method-name"] = payload.testMethodName;
+            analyzeHeaders["x-method"] = payload.testMethodName;
+        }
+        if (payload.executionSource) {
+            analyzeHeaders["x-execution-source"] = payload.executionSource;
+            analyzeHeaders["x-execution-origin"] = payload.executionSource;
+        }
+        const res = await postJsonWithFallback("/api/test-recovery/analyze-failure", payload, 60000, analyzeHeaders);
+        // 📥 Tratar resposta 202 (fila assíncrona) - v2.7.43
+        if (res && res.status === 202) {
+            try {
+                const queuedData = (await res.json());
+                if (queuedData.queued && queuedData.requestId) {
+                    Logger.info(`[TestRecoveryClient] ⏳ Requisição enfileirada (posição ${queuedData.position ?? "?"}). Aguardando resultado...`);
+                    const queueResult = await pollQueueResult(queuedData.requestId);
+                    if (queueResult) {
+                        Logger.success(`[TestRecoveryClient] ✅ Resultado da fila recebido!`);
+                        return queueResult;
+                    }
+                    Logger.warning(`[TestRecoveryClient] ⚠️ Timeout/falha na fila assíncrona para requestId: ${queuedData.requestId}`);
+                    return null;
+                }
+            }
+            catch {
+                Logger.warning("[TestRecoveryClient] ⚠️ Erro ao processar resposta 202");
+            }
+            return null;
+        }
+        // 📥 LOG SIMPLIFICADO DA RESPOSTA
+        if (!res || !res.ok) {
+            Logger.error(`[TestRecoveryClient] ❌ Erro na requisição: Status HTTP ${res?.status ?? "no response"}`);
+            return null;
+        }
+        const responseData = (await res.json());
+        Logger.success(`[TestRecoveryClient] ✅ AutoHealing executado com sucesso!`);
+        Logger.info(`   📍 XPath anterior: ${payload.failedXPath}`);
+        Logger.info(`   ✨ XPath sugerido: ${responseData.analysis.suggestedXPath} (confiança: ${(responseData.analysis.confidence * 100).toFixed(0)}%)`);
+        if (responseData.logId) {
+            Logger.info(`   🆔 LogId: ${responseData.logId}`);
+        }
+        return responseData;
+    }
+    catch (err) {
+        Logger.error(`[TestRecoveryClient] ❌ Exceção: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+export async function fixInCode(payload) {
+    try {
+        const res = await postJsonWithFallback("/api/test-recovery/fix-in-code", payload, 60000, getSingletonUserHeaders());
+        if (!res || !res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+export async function markSuccess(sessionId, attemptNumber) {
+    try {
+        const res = await postJsonWithFallback("/api/test-recovery/mark-success", {
+            sessionId,
+            attemptNumber,
+        });
+        return !!res && res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeUserValue(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function resolveRuntimeUserDefaults() {
+    const id = normalizeUserValue(process.env.AUTOCORE_USER_ID || process.env.USER_ID || "");
+    const email = normalizeUserValue(process.env.AUTOCORE_USER_EMAIL ||
+        process.env.BUILD_REQUESTEDFOREMAIL ||
+        process.env.BUILD_REQUESTEDFOR_EMAIL ||
+        "");
+    const matricula = normalizeUserValue(process.env.AUTOCORE_USER_MATRICULA ||
+        process.env.USERNAME ||
+        process.env.USER ||
+        "");
+    let osUserName = "";
+    try {
+        osUserName = normalizeUserValue(os.userInfo().username);
+    }
+    catch {
+        // noop
+    }
+    const name = normalizeUserValue(process.env.AUTOCORE_USER_NAME ||
+        process.env.USER_FULLNAME ||
+        matricula ||
+        osUserName);
+    return {
+        id,
+        email,
+        matricula,
+        name,
+    };
+}
+/**
+ * Constrói objeto `actor` a partir de variáveis de ambiente e singleton (item 23 v2.7.44).
+ * Usado automaticamente em analyzeFailure/reportResult quando nenhum actor é fornecido.
+ */
+function buildActorFromEnv() {
+    const defaults = resolveRuntimeUserDefaults();
+    const id = normalizeUserValue(_singletonUserHeaders?.userId || defaults.id);
+    const name = normalizeUserValue(_singletonUserHeaders?.userName || defaults.name);
+    const email = normalizeUserValue(_singletonUserHeaders?.userEmail || defaults.email);
+    const matricula = normalizeUserValue(_singletonUserHeaders?.userMatricula || defaults.matricula);
+    if (!id && !name && !email && !matricula)
+        return undefined;
+    return {
+        ...(id ? { id } : {}),
+        ...(name ? { name } : {}),
+        ...(email ? { email } : {}),
+        ...(matricula ? { matricula } : {}),
+    };
+}
+/**
+ * Constrói headers extras de identificação do usuário (v2.7.44)
+ * Envia múltiplos aliases aceitos pelo backend para maximizar taxa de preenchimento
+ * Retorna apenas os headers de usuário (sem Content-Type/key)
+ */
+function userHeadersMap(user) {
+    const headers = {};
+    const defaults = resolveRuntimeUserDefaults();
+    // Resolver valores: priorizar user param, depois env vars
+    const userId = normalizeUserValue(user?.userId || defaults.id);
+    const userEmail = normalizeUserValue(user?.userEmail || defaults.email);
+    const userMatricula = normalizeUserValue(user?.userMatricula || defaults.matricula);
+    const userName = normalizeUserValue(user?.userName || defaults.name);
+    // Aliases primários (item 9)
+    if (userId) {
+        headers["x-automation-user-id"] = userId;
+        headers["x-user-id"] = userId;
+        headers["x-userid"] = userId;
+    }
+    if (userEmail) {
+        headers["x-automation-user-email"] = userEmail;
+        headers["x-user-email"] = userEmail;
+        headers["x-framework-user-email"] = userEmail;
+    }
+    if (userMatricula) {
+        headers["x-automation-user-matricula"] = userMatricula;
+        headers["x-user-matricula"] = userMatricula;
+        headers["x-matricula"] = userMatricula;
+        headers["x-framework-user-matricula"] = userMatricula;
+    }
+    if (userName) {
+        headers["x-automation-user-name"] = userName;
+        headers["x-user-name"] = userName;
+        headers["x-user"] = userName;
+        headers["x-framework-user-name"] = userName;
+    }
+    if (!userName && userMatricula) {
+        headers["x-automation-user-name"] = userMatricula;
+        headers["x-user-name"] = userMatricula;
+        headers["x-user"] = userMatricula;
+    }
+    return headers;
+}
+/**
+ * Constrói headers completos com identificação do usuário (opcional)
+ */
+function authHeadersWithUser(user) {
+    return { ...authHeaders(), ...userHeadersMap(user) };
+}
+/**
+ * Obtém user headers do singleton (para chamadas automáticas do framework)
+ */
+function getSingletonUserHeaders() {
+    // Lazy access: singleton é criado no final do arquivo
+    try {
+        return userHeadersMap(_singletonUserHeaders);
+    }
+    catch {
+        return {};
+    }
+}
+// Referência aos userHeaders do singleton - atualizada por setUserHeaders()
+let _singletonUserHeaders = {};
+/**
+ * Reporta resultado de tentativa de recovery
+ *
+ * ⚠️ OBRIGATÓRIO chamar após testar XPath sugerido (v2.6.9)
+ * Sem report-result, a tentativa fica como "pendente" no dashboard
+ *
+ * @param params Parâmetros do resultado
+ * @param user Headers opcionais de identificação do usuário
+ * @returns Resposta do servidor
+ *
+ * @example
+ * ```typescript
+ * // Após testar XPath sugerido
+ * await reportResult({
+ *   logId: result.logId,
+ *   success: true,
+ *   autoFixed: true,
+ *   executionSource: 'AZURE',
+ *   recoverySource: 'framework',
+ *   testCaseName: 'Login Test',
+ *   testCaseId: 'CT-001',
+ *   testMethodName: 'testLogin'
+ * });
+ * ```
+ */
+export async function reportResult(params, user) {
+    try {
+        // Auto-enriquecer com metadados quando ausentes (v2.7.44)
+        const meta = getRecoveryMetadata();
+        const enriched = {
+            ...params,
+            executionSource: params.executionSource || meta.executionSource,
+            testCaseName: params.testCaseName || meta.testCaseName,
+            testCaseId: params.testCaseId || meta.testCaseId,
+            testMethodName: params.testMethodName || meta.testMethodName,
+            actor: params.actor || buildActorFromEnv(),
+        };
+        const base = getAutoCorehubUrl();
+        const fallback = getFallbackHubUrl(base);
+        const userH = user || _singletonUserHeaders;
+        const headers = authHeadersWithUser(userH);
+        // CN/CT/Method headers (v2.7.44 - item 10)
+        if (enriched.testCaseName) {
+            headers["x-test-case-name"] = enriched.testCaseName;
+            headers["x-cn"] = enriched.testCaseName;
+            headers["x-test-name"] = enriched.testCaseName;
+            headers["x-cn-name"] = enriched.testCaseName;
+        }
+        if (enriched.testCaseId) {
+            headers["x-test-case-id"] = enriched.testCaseId;
+            headers["x-ct"] = enriched.testCaseId;
+            headers["x-test-id"] = enriched.testCaseId;
+            headers["x-ct-id"] = enriched.testCaseId;
+        }
+        if (enriched.testMethodName) {
+            headers["x-test-method-name"] = enriched.testMethodName;
+            headers["x-method"] = enriched.testMethodName;
+        }
+        if (enriched.executionSource) {
+            headers["x-execution-source"] = enriched.executionSource;
+            headers["x-execution-origin"] = enriched.executionSource;
+        }
+        const body = JSON.stringify(enriched);
+        // Se não houver fallback, fazer apenas uma requisição
+        if (!fallback) {
+            const res = await fetchWithTimeout(`${base}/api/test-recovery/report-result`, {
+                method: "POST",
+                headers,
+                body,
+                timeout: 30000,
+            });
+            if (!res.ok)
+                return null;
+            return (await res.json());
+        }
+        // Promise.all: Tentar ambas URLs em paralelo
+        const [primaryResult, fallbackResult] = await Promise.allSettled([
+            fetchWithTimeout(`${base}/api/test-recovery/report-result`, {
+                method: "POST",
+                headers,
+                body,
+                timeout: 30000,
+            }),
+            fetchWithTimeout(`${fallback}/api/test-recovery/report-result`, {
+                method: "POST",
+                headers,
+                body,
+                timeout: 30000,
+            }),
+        ]);
+        // Priorizar resultado primário se sucesso
+        if (primaryResult.status === "fulfilled" && primaryResult.value.ok) {
+            return (await primaryResult.value.json());
+        }
+        // Usar fallback se primário falhou
+        if (fallbackResult.status === "fulfilled" && fallbackResult.value.ok) {
+            return (await fallbackResult.value.json());
+        }
+        return null;
+    }
+    catch (err) {
+        Logger.error(`[TestRecoveryClient] Erro ao reportar resultado: ${err instanceof Error ? err.message : String(err)}`, err);
+        return null;
+    }
+}
+export async function getRecoveryStats(params = {}) {
+    const queryParts = [];
+    if (params.userId)
+        queryParts.push(`userId=${encodeURIComponent(params.userId)}`);
+    if (params.startDate)
+        queryParts.push(`startDate=${encodeURIComponent(params.startDate)}`);
+    if (params.endDate)
+        queryParts.push(`endDate=${encodeURIComponent(params.endDate)}`);
+    const q = queryParts.length ? `?${queryParts.join("&")}` : "";
+    try {
+        const res = await getJsonWithFallback(`/api/test-recovery/stats${q}`);
+        if (!res || !res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+export async function getQueueStatus(requestId) {
+    try {
+        const res = await getJsonWithFallback(`/api/test-recovery/queue/status/${encodeURIComponent(requestId)}`);
+        if (!res || !res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Poll assíncrono para resultado de fila do analyze-failure (v2.7.44)
+ * Aguarda até o status ser 'completed' ou 'failed', com timeout de 90s
+ * Usa backoff progressivo: 1s, 2s, 3s, 5s, 8s... (item 25.2)
+ *
+ * @param requestId ID da requisição retornado pelo 202
+ * @param maxWaitMs Tempo máximo de espera em ms (default: 90000)
+ * @returns RecoveryResponse quando completado, null em timeout/falha
+ */
+async function pollQueueResult(requestId, maxWaitMs = 90000) {
+    const startTime = Date.now();
+    // Backoff progressivo (Fibonacci-like): 1s, 2s, 3s, 5s, 8s, 8s, 8s...
+    const backoffSchedule = [1000, 2000, 3000, 5000, 8000];
+    let pollIndex = 0;
+    while (Date.now() - startTime < maxWaitMs) {
+        const delay = backoffSchedule[Math.min(pollIndex, backoffSchedule.length - 1)];
+        try {
+            const status = await getQueueStatus(requestId);
+            if (!status) {
+                await new Promise((r) => setTimeout(r, delay));
+                pollIndex++;
+                continue;
+            }
+            if (status.status === "completed" && status.result) {
+                return status.result;
+            }
+            if (status.status === "failed" || status.status === "timeout") {
+                Logger.error(`[TestRecoveryClient] ❌ Fila ${status.status} para ${requestId}: ${status.error || "unknown"}`);
+                return null;
+            }
+            // pending ou processing - aguardar com backoff
+            await new Promise((r) => setTimeout(r, delay));
+            pollIndex++;
+        }
+        catch {
+            await new Promise((r) => setTimeout(r, delay));
+            pollIndex++;
+        }
+    }
+    Logger.warning(`[TestRecoveryClient] ⏱️ Timeout de ${maxWaitMs}ms ao aguardar fila para ${requestId}`);
+    return null;
+}
+/**
+ * Obtém logs de recuperação (histórico)
+ * GET /api/test-recovery/recovery-logs
+ */
+export async function getRecoveryLogs(params = {}) {
+    const queryParts = [];
+    if (params.sessionId)
+        queryParts.push(`sessionId=${encodeURIComponent(params.sessionId)}`);
+    if (params.limit)
+        queryParts.push(`limit=${encodeURIComponent(String(params.limit))}`);
+    const q = queryParts.length ? `?${queryParts.join("&")}` : "";
+    try {
+        const res = await getJsonWithFallback(`/api/test-recovery/recovery-logs${q}`);
+        if (!res || !res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+// ==========================================
+// TestRecoveryHelper - Classe helper para integração v2.6.1
+// ==========================================
+/**
+ * Classe helper para integração com Test Recovery
+ * Gerencia o estado de campos preenchidos e facilita a análise de falhas
+ *
+ * @example
+ * ```typescript
+ * const recovery = new TestRecoveryHelper();
+ *
+ * try {
+ *   await page.locator(xpath).fill(value);
+ *   recovery.markFieldFilled(xpath, 'fieldId');
+ * } catch (error) {
+ *   const pageStructure = await recovery.extractPageStructure(page);
+ *   const result = await recovery.analyzeFailure({
+ *     url: page.url(),
+ *     failedXPath: xpath,
+ *     errorType: 'timeout',
+ *     actionType: 'fill',
+ *     pageStructure,
+ *     value,
+ *   });
+ *
+ *   if (result?.analysis.confidence >= 0.5) {
+ *     await page.locator(result.analysis.suggestedXPath).fill(value);
+ *     recovery.markFieldFilled(result.analysis.suggestedXPath);
+ *   }
+ * }
+ * ```
+ */
+export class TestRecoveryHelper {
+    filledFields = [];
+    filledInputs = [];
+    sessionId;
+    userHeaders = {};
+    projectRoot;
+    /**
+     * Cria uma instância do TestRecoveryHelper
+     *
+     * @param sessionId ID da sessão para correlacionar requisições
+     * @param user Headers de identificação do usuário
+     * @param projectRoot Caminho absoluto do projeto (para auto-fix local)
+     */
+    constructor(sessionId, user, projectRoot) {
+        this.sessionId = sessionId;
+        if (user)
+            this.userHeaders = user;
+        this.projectRoot = projectRoot;
+    }
+    /**
+     * Define o projectRoot para auto-fix local (v2.7.1)
+     */
+    setProjectRoot(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    /**
+     * Obtém o projectRoot atual
+     */
+    getProjectRoot() {
+        return this.projectRoot;
+    }
+    /**
+     * Define o sessionId para manter contexto entre requisições
+     */
+    setSessionId(sessionId) {
+        this.sessionId = sessionId;
+    }
+    /**
+     * Obtém o sessionId atual
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Define headers de identificação do usuário (v2.6.9)
+     * Também atualiza headers globais para chamadas do framework
+     */
+    setUserHeaders(user) {
+        this.userHeaders = user;
+        _singletonUserHeaders = user;
+    }
+    /**
+     * Analisa falha e retorna XPath corrigido
+     * Envia automaticamente o contexto de campos já preenchidos
+     *
+     * @param params Parâmetros da análise (v2.6.9: inclui executionSource, recoverySource, testCase*)
+     */
+    async analyzeFailure(params) {
+        const request = {
+            url: params.url,
+            failedXPath: params.failedXPath,
+            errorType: params.errorType,
+            actionType: params.actionType,
+            pageStructure: params.pageStructure,
+            pageHtml: params.pageHtml,
+            sessionId: this.sessionId,
+            systemName: params.systemName,
+            environment: params.environment,
+            executionSource: params.executionSource,
+            recoverySource: params.recoverySource ?? "framework",
+            testCaseName: params.testCaseName,
+            testCaseId: params.testCaseId,
+            testMethodName: params.testMethodName,
+            context: {
+                value: params.value,
+                originalMethod: params.actionType,
+                filledInputs: [...this.filledInputs],
+                filledFields: [...this.filledFields],
+            },
+        };
+        return analyzeFailure(request);
+    }
+    /**
+     * Reporta resultado de tentativa de recovery
+     *
+     * ⚠️ OBRIGATÓRIO chamar após testar XPath sugerido (v2.6.9)
+     * Sem report-result, a tentativa fica como "pendente" no dashboard
+     *
+     * @param params Parâmetros do resultado
+     * @returns Resposta do servidor
+     */
+    async reportResult(params) {
+        return reportResult({
+            ...params,
+            sessionId: this.sessionId,
+            recoverySource: params.recoverySource ?? "framework",
+        }, this.userHeaders);
+    }
+    /**
+     * Marca campo como preenchido com sucesso
+     * Deve ser chamado após cada preenchimento bem-sucedido
+     *
+     * @param xpath XPath do elemento preenchido
+     * @param fieldId ID ou name do campo (opcional, melhora a análise)
+     */
+    markFieldFilled(xpath, fieldId) {
+        if (xpath && !this.filledInputs.includes(xpath)) {
+            this.filledInputs.push(xpath);
+        }
+        if (fieldId && !this.filledFields.includes(fieldId)) {
+            this.filledFields.push(fieldId);
+        }
+    }
+    /**
+     * Remove um campo da lista de preenchidos
+     * Útil quando um campo é limpo ou precisa ser repreenchido
+     */
+    unmarkFieldFilled(xpath, fieldId) {
+        const xpathIndex = this.filledInputs.indexOf(xpath);
+        if (xpathIndex > -1) {
+            this.filledInputs.splice(xpathIndex, 1);
+        }
+        if (fieldId) {
+            const fieldIndex = this.filledFields.indexOf(fieldId);
+            if (fieldIndex > -1) {
+                this.filledFields.splice(fieldIndex, 1);
+            }
+        }
+    }
+    /**
+     * Limpa histórico de campos preenchidos
+     * Deve ser chamado no início de cada novo teste ou ao mudar de página
+     */
+    clearFilledFields() {
+        this.filledInputs = [];
+        this.filledFields = [];
+    }
+    /**
+     * Obtém lista de XPaths preenchidos
+     */
+    getFilledInputs() {
+        return [...this.filledInputs];
+    }
+    /**
+     * Obtém lista de IDs/names preenchidos
+     */
+    getFilledFields() {
+        return [...this.filledFields];
+    }
+    /**
+     * Extrai estrutura da página usando Playwright Page
+     * Retorna objeto pronto para enviar ao Test Recovery
+     *
+     * @param page Instância de Page do Playwright
+     * @returns Estrutura da página com inputs, buttons, links e headings
+     */
+    async extractPageStructure(page) {
+        try {
+            const structure = await page.evaluate(() => {
+                const getXPath = (element) => {
+                    if (element.id) {
+                        return `//*[@id="${element.id}"]`;
+                    }
+                    const parent = element.parentElement;
+                    if (!parent)
+                        return "";
+                    const siblings = Array.from(parent.children).filter((child) => child.tagName === element.tagName);
+                    const index = siblings.indexOf(element) + 1;
+                    const tag = element.tagName.toLowerCase();
+                    const parentXPath = getXPath(parent);
+                    if (siblings.length === 1) {
+                        return `${parentXPath}/${tag}`;
+                    }
+                    return `${parentXPath}/${tag}[${index}]`;
+                };
+                const extractElement = (el) => ({
+                    tag: el.tagName.toLowerCase(),
+                    text: el.textContent?.trim().slice(0, 200) || "",
+                    xpath: getXPath(el),
+                    id: el.id || undefined,
+                    name: el.getAttribute("name") || undefined,
+                    className: el.className || undefined,
+                    type: el.getAttribute("type") || undefined,
+                    placeholder: el.getAttribute("placeholder") || undefined,
+                    ariaLabel: el.getAttribute("aria-label") || undefined,
+                    dataTestId: el.getAttribute("data-testid") || undefined,
+                    title: el.getAttribute("title") || undefined,
+                    role: el.getAttribute("role") || undefined,
+                    href: el.getAttribute("href") || undefined,
+                });
+                return {
+                    title: document.title,
+                    url: window.location.href,
+                    buttons: Array.from(document.querySelectorAll('button, input[type="button"], input[type="submit"], [role="button"]')).map(extractElement),
+                    inputs: Array.from(document.querySelectorAll('input:not([type="button"]):not([type="submit"]):not([type="hidden"]), textarea, select, [role="textbox"], [role="combobox"]')).map(extractElement),
+                    links: Array.from(document.querySelectorAll("a[href]")).map(extractElement),
+                    headings: Array.from(document.querySelectorAll("h1, h2, h3, h4, h5, h6")).map(extractElement),
+                };
+            });
+            return structure;
+        }
+        catch (err) {
+            Logger.warning(`[TestRecoveryHelper] Erro ao extrair estrutura da página: ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    }
+    /**
+     * Extrai ID ou name de um XPath sugerido
+     * Útil para marcar campo como preenchido após recovery
+     *
+     * @param xpath XPath para extrair o identificador
+     * @returns ID ou name encontrado, ou undefined
+     */
+    extractFieldIdFromXPath(xpath) {
+        // Tentar extrair @id="..."
+        const idMatch = xpath.match(/@id=["']([^"']+)["']/);
+        if (idMatch)
+            return idMatch[1];
+        // Tentar extrair @name="..."
+        const nameMatch = xpath.match(/@name=["']([^"']+)["']/);
+        if (nameMatch)
+            return nameMatch[1];
+        // Tentar extrair @data-testid="..."
+        const testIdMatch = xpath.match(/@data-testid=["']([^"']+)["']/);
+        if (testIdMatch)
+            return testIdMatch[1];
+        return undefined;
+    }
+    /**
+     * Helper para executar ação com recovery automático
+     * Se a ação falhar, tenta recuperar usando Test Recovery
+     *
+     * @param params Parâmetros da ação (v2.6.9: inclui executionSource, testCase*)
+     * @returns Resultado da ação com informações de recovery
+     */
+    async executeWithRecovery(params) {
+        const { page, xpath, actionType, value, timeout = 5000, minConfidence = 0.5, } = params;
+        const attemptNumber = 1;
+        // Tentar ação original
+        try {
+            if (actionType === "fill" && value !== undefined) {
+                await page.locator(xpath).fill(value, { timeout });
+            }
+            else if (actionType === "click") {
+                await page.locator(xpath).click({ timeout });
+            }
+            // Sucesso! Marcar como preenchido
+            const fieldId = this.extractFieldIdFromXPath(xpath);
+            this.markFieldFilled(xpath, fieldId);
+            return { success: true, usedXPath: xpath, wasRecovered: false };
+        }
+        catch {
+            Logger.info(`[TestRecoveryHelper] Falha na ação original (${xpath}), consultando Test Recovery...`);
+            // Extrair estrutura da página
+            const pageStructure = await this.extractPageStructure(page);
+            // Consultar Test Recovery
+            const result = await this.analyzeFailure({
+                url: page.url(),
+                failedXPath: xpath,
+                errorType: "timeout",
+                actionType,
+                pageStructure,
+                value,
+                systemName: params.systemName,
+                environment: params.environment,
+                executionSource: params.executionSource,
+                recoverySource: "framework",
+                testCaseName: params.testCaseName,
+                testCaseId: params.testCaseId,
+                testMethodName: params.testMethodName,
+            });
+            if (!result?.analysis?.suggestedXPath) {
+                Logger.error("[TestRecoveryHelper] Test Recovery não retornou sugestão");
+                return { success: false, usedXPath: xpath, wasRecovered: false };
+            }
+            const { suggestedXPath, confidence, reason } = result.analysis;
+            Logger.info(`[TestRecoveryHelper] Sugestão: ${suggestedXPath}`);
+            Logger.info(`[TestRecoveryHelper] Confiança: ${(confidence * 100).toFixed(1)}%`);
+            Logger.info(`[TestRecoveryHelper] Razão: ${reason}`);
+            if (confidence < minConfidence) {
+                Logger.warning(`[TestRecoveryHelper] Confiança muito baixa (${(confidence * 100).toFixed(1)}% < ${(minConfidence * 100).toFixed(1)}%)`);
+                // ⚠️ OBRIGATÓRIO: Reportar falha (v2.6.9)
+                await this.reportResult({
+                    xpath: suggestedXPath,
+                    attemptNumber,
+                    success: false,
+                    executionSource: params.executionSource,
+                    testCaseName: params.testCaseName,
+                    testCaseId: params.testCaseId,
+                    testMethodName: params.testMethodName,
+                });
+                return { success: false, usedXPath: xpath, wasRecovered: false };
+            }
+            // Tentar com XPath sugerido
+            try {
+                if (actionType === "fill" && value !== undefined) {
+                    await page.locator(suggestedXPath).fill(value, { timeout });
+                }
+                else if (actionType === "click") {
+                    await page.locator(suggestedXPath).click({ timeout });
+                }
+                // Sucesso com recovery!
+                const fieldId = this.extractFieldIdFromXPath(suggestedXPath);
+                this.markFieldFilled(suggestedXPath, fieldId);
+                // ✅ OBRIGATÓRIO: Reportar sucesso (v2.6.9)
+                await this.reportResult({
+                    xpath: suggestedXPath,
+                    attemptNumber,
+                    success: true,
+                    autoFixed: true,
+                    executionSource: params.executionSource,
+                    testCaseName: params.testCaseName,
+                    testCaseId: params.testCaseId,
+                    testMethodName: params.testMethodName,
+                });
+                return { success: true, usedXPath: suggestedXPath, wasRecovered: true };
+            }
+            catch (recoveryError) {
+                Logger.error(`[TestRecoveryHelper] Falha mesmo com XPath sugerido: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}`, recoveryError);
+                // ❌ OBRIGATÓRIO: Reportar falha (v2.6.9)
+                await this.reportResult({
+                    xpath: suggestedXPath,
+                    attemptNumber,
+                    success: false,
+                    executionSource: params.executionSource,
+                    testCaseName: params.testCaseName,
+                    testCaseId: params.testCaseId,
+                    testMethodName: params.testMethodName,
+                });
+                return {
+                    success: false,
+                    usedXPath: suggestedXPath,
+                    wasRecovered: false,
+                };
+            }
+        }
+    }
+    /**
+     * Aplica correção de XPath automaticamente nos arquivos do projeto (v2.7.1)
+     *
+     * ⚠️ Requisitos:
+     * - executionSource deve ser 'LOCAL' (não funciona em Azure/CI)
+     * - confidence deve ser >= 0.7 (segurança)
+     * - projectRoot deve ser válido e acessível
+     *
+     * @param params Parâmetros para auto-fix local
+     * @returns Resultado da operação com detalhes da correção
+     *
+     * @example
+     * ```typescript
+     * const recovery = new TestRecoveryHelper();
+     *
+     * // Após analyzeFailure retornar autoFixAvailable=true
+     * const result = await recovery.autoFixLocal({
+     *   projectRoot: '/home/user/projeto',
+     *   oldXPath: '//input[@id="email"]',
+     *   newXPath: '//input[@data-testid="email-input"]',
+     *   confidence: 0.85,
+     *   attributesFile: 'AttributesLogin.ts'
+     * });
+     *
+     * if (result.success) {
+     *   console.log(`Arquivo corrigido: ${result.fix?.filePath}`);
+     * }
+     * ```
+     */
+    async autoFixLocal(params) {
+        // Usa projectRoot do parâmetro ou da instância
+        const projectRoot = params.projectRoot || this.projectRoot;
+        const { oldXPath, newXPath, confidence, autoConfirm = true } = params;
+        // Validar confiança mínima
+        if (confidence < 0.7) {
+            return {
+                success: false,
+                message: `Confiança muito baixa (${(confidence * 100).toFixed(1)}% < 70%). Auto-fix requer mínimo 70% de confiança.`,
+                error: "LOW_CONFIDENCE",
+            };
+        }
+        // Validar que não está em ambiente CI/Azure
+        if (isAzureEnvironment()) {
+            return {
+                success: false,
+                message: "Auto-fix local não disponível em ambiente CI/Azure. Use executionSource=LOCAL.",
+                error: "INVALID_ENVIRONMENT",
+            };
+        }
+        // Validar projectRoot
+        if (!projectRoot || projectRoot.trim() === "") {
+            return {
+                success: false,
+                message: "projectRoot é obrigatório para auto-fix local.",
+                error: "MISSING_PROJECT_ROOT",
+            };
+        }
+        const request = {
+            projectRoot,
+            oldXPath,
+            newXPath,
+            confidence,
+            testFilePath: params.testFilePath,
+            attributesFile: params.attributesFile,
+            className: params.className,
+            locatorProperty: params.locatorProperty,
+            methodName: params.methodName,
+            lineNumber: params.lineNumber,
+            recoverySessionId: this.sessionId,
+            systemName: params.systemName,
+            environmentType: params.environmentType,
+            autoConfirm,
+            executionSource: "Local",
+        };
+        try {
+            // Headers extras: x-project-root como fallback (item 12 v2.7.44)
+            const extraHeaders = {
+                ...userHeadersMap(this.userHeaders),
+            };
+            if (projectRoot) {
+                extraHeaders["x-project-root"] = projectRoot;
+            }
+            const meta = getRecoveryMetadata();
+            if (meta.executionSource)
+                extraHeaders["x-execution-source"] = meta.executionSource;
+            const res = await postJsonWithFallback("/api/test-recovery/auto-fix-local", request, 30000, extraHeaders);
+            if (!res.ok) {
+                const errorText = await res.text().catch(() => "Erro desconhecido");
+                Logger.error(`[TestRecoveryHelper] auto-fix-local falhou: ${res.status} - ${errorText}`);
+                return {
+                    success: false,
+                    message: `Erro na API: ${res.status}`,
+                    error: errorText,
+                };
+            }
+            const data = (await res.json());
+            if (data.success && data.fix) {
+                Logger.success(`[TestRecoveryHelper] ✅ Auto-fix aplicado: ${data.fix.filePath}`);
+                Logger.info(`[TestRecoveryHelper]    Linha ${data.fix.lineNumber}: "${data.fix.oldXPath}" → "${data.fix.newXPath}"`);
+            }
+            return data;
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            Logger.error(`[TestRecoveryHelper] Erro ao chamar auto-fix-local: ${errorMessage}`);
+            return {
+                success: false,
+                message: "Falha na comunicação com a API de auto-fix.",
+                error: errorMessage,
+            };
+        }
+    }
+}
+// ==========================================
+// Instância singleton para uso simplificado
+// ==========================================
+/**
+ * Instância singleton do TestRecoveryHelper
+ * Use para casos simples sem necessidade de múltiplas instâncias
+ *
+ * @example
+ * ```typescript
+ * import { testRecoveryHelper } from '@silasfmartins/testhub';
+ *
+ * testRecoveryHelper.markFieldFilled(xpath, 'username');
+ * const result = await testRecoveryHelper.analyzeFailure({ ... });
+ * ```
+ */
+export const testRecoveryHelper = new TestRecoveryHelper();