@silasfmartins/testhub 1.0.0

package/dist/src/playwright/WebActions.d.ts

@@ -0,0 +1,1599 @@
+import { type XPathCatalogItem, type CatalogGetOptions, type RawPageStructure } from "../utils/XPathCatalog.js";
+import type { ILocator, IPage } from "../interfaces.js";
+import { type DateOptions, type DateFormat } from "../utils/DateHelper.js";
+export declare function invokeCodegen(params: any): Promise<void>;
+import "../hubdocs/StatementTracker.js";
+export type PageXPathItem = XPathCatalogItem;
+type WaitVisibilityOptions = {
+    timeout?: number;
+    descricao?: string;
+    tirarPrint?: boolean;
+};
+type ExtendedWaitVisibilityOptions = WaitVisibilityOptions & {
+    hoverParent?: string;
+    checkOverlays?: boolean;
+    inFrameSelector?: string;
+};
+/**
+ * Interface para log de Network (usado pelo startNetworkLogging/stopNetworkLogging)
+ */
+interface NetworkLogEntry {
+    timestamp: string;
+    type: "request" | "response" | "failed";
+    method: string;
+    url: string;
+    status?: number;
+    statusText?: string;
+    resourceType: string;
+    duration?: number;
+    size?: number;
+    errorText?: string;
+}
+/**
+ * Classe de ações web para automação com Playwright.
+ * API nova e organizada seguindo padrão dos outros Actions (SSHActions, MobileActions, etc).
+ * Migrada de Actions.ts para nova arquitetura DDD.
+ */
+export declare class WebActions {
+    private static networkLoggingEnabled;
+    private static networkLogs;
+    private static networkRequestTimings;
+    private static networkListenersAttached;
+    /**
+     * ✅ NOVO: Extrai o seletor real de um ILocator ou string
+     * @private
+     * @param {string|ILocator} elemento Elemento do qual extrair o seletor
+     * @returns {string} O seletor extraído
+     */
+    private static extractSelector;
+    /**
+     * ✅ NOVO: Detecta o tipo do seletor
+     * @private
+     * @param {string} selector Seletor a analisar
+     * @returns {string} Tipo do seletor
+     */
+    private static detectSelectorType;
+    /**
+     * Timeout padrão para resolver XPath/locators entre contextos e frames.
+     */
+    private static getResolveTimeoutMs;
+    /**
+     * Normaliza e simplifica eixos de XPath para versões equivalentes e mais estáveis.
+     */
+    private static normalizeAxisXPath;
+    private static isXPathSelector;
+    /**
+     * Aguarda attachment e confirma match para reduzir falso negativo em DOM dinâmico.
+     */
+    private static probeLocator;
+    /**
+     * Prioriza frames visíveis para busca de XPath.
+     */
+    private static getFramesByVisibility;
+    /**
+     * Gera variações candidatas de um seletor para aumentar chances de localização
+     */
+    private static getSelectorCandidates;
+    /**
+     * Retorna uma lista ampliada de seletores de contêineres de listas/dropdowns comuns
+     */
+    private static getListSelectors;
+    /**
+     * Tenta clicar de forma robusta no locator: espera visibilidade, click normal, fallback para force, fallback evaluate click
+     */
+    private static robustClick;
+    /**
+     * Normaliza seletor recebido em runtime para reduzir falhas por formatação.
+     */
+    private static normalizeSelector;
+    /**
+     * Retorna locator singular quando houver múltiplos matches (usa first()).
+     */
+    private static toSingleLocator;
+    /**
+     * Verifica se locator possui pelo menos um elemento.
+     */
+    private static hasLocatorMatch;
+    /**
+     * Resolve locator em qualquer contexto disponível (page atual + iframes).
+     * Isso reduz falso negativo quando o usuário vê o elemento na tela, mas ele está em frame diferente.
+     */
+    private static resolveLocatorAnyContext;
+    /**
+     * Resolve candidate usado no withRecovery sem perder fallback do Test Recovery.
+     */
+    private static resolveCandidateForRecovery;
+    /**
+     * Fallback robusto para click, inclusive em elementos desabilitados/overlay.
+     */
+    private static clickWithFallback;
+    /**
+     * Aguarda overlays/spinners/loadings comuns desaparecerem antes de interagir.
+     * Evita cliques que "funcionam" mas são interceptados por overlays.
+     */
+    private static waitForOverlaysClear;
+    /**
+     * Verifica se o clique realmente teve efeito na página.
+     * Retorna true se houve mudança detectável (URL, DOM, rede).
+     * Usado para validar cliques via force:true ou dispatchEvent.
+     */
+    private static verifyClickEffect;
+    /**
+     * Captura um snapshot leve do DOM para comparação pós-clique.
+     */
+    private static captureDomSnapshot;
+    /**
+     * Fallback robusto para setar valor em inputs/textarea/contenteditable.
+     */
+    private static setValueWithFallback;
+    /**
+     * Seleciona uma opção em um <select> comparando labels de forma normalizada
+     * (remove acentos, normaliza espaços e compara lowercase). Retorna true se selecionou.
+     * @private
+     */
+    private static selectOptionByNormalizedLabel;
+    /**
+     * Retorna a primeira selector candidato que encontra elementos na página
+     */
+    private static findFirstMatchingSelector;
+    /**
+     * 🆕 Extrai estrutura básica da página para o Test Recovery
+     * Captura botões, inputs, links e headings com seus seletores
+     * @param page Página do Playwright
+     * @returns Estrutura da página com elementos principais
+     */
+    static extractBasicPageStructure(page: IPage): Promise<{
+        buttons?: Array<{
+            tag: string;
+            text: string;
+            xpath?: string;
+            id?: string;
+            className?: string;
+        }>;
+        inputs?: Array<{
+            tag: string;
+            type?: string;
+            xpath?: string;
+            id?: string;
+            name?: string;
+            placeholder?: string;
+        }>;
+        links?: Array<{
+            tag: string;
+            text: string;
+            href?: string;
+            xpath?: string;
+        }>;
+        headings?: Array<{
+            tag: string;
+            text: string;
+            xpath?: string;
+        }>;
+    }>;
+    /** Timestamp do último refreshDOM (debounce para evitar múltiplas chamadas consecutivas) */
+    private static _lastDOMRefreshTime;
+    /** Guard contra recursão infinita em withRecovery (click_other/navigateTo/switchTo dentro de recovery) */
+    private static _recoveryDepth;
+    private static readonly _maxRecoveryDepth;
+    /**
+     * 🔄 Força atualização/estabilização do DOM antes de localizar/interagir com elementos.
+     * Essencial para SPAs (ex.: Salesforce Lightning/Vlocity) que recriam Shadow DOM a cada interação.
+     *
+     * Chamado automaticamente ANTES de cada ação (click, setText, hover, etc.) para
+     * garantir que o DOM esteja sempre fresco na primeira tentativa.
+     *
+     * Estratégias:
+     * 1. waitForLoadState('domcontentloaded') — aguardar parsing base
+     * 2. Forçar reflow/repaint via JS (offsetHeight leitura)
+     * 3. Aguardar microtasks/pending mutations (requestAnimationFrame + setTimeout)
+     * 4. Aguardar Shadow DOM roots se estabilizarem (Custom Elements defineados)
+     * 5. Breve pausa para rendering assíncrono de frameworks (LWC, Aura, React)
+     *
+     * 🛡️ Debounce: pula automaticamente se chamado dentro do cooldown (default 200ms).
+     * 🛡️ Toggle: desabilitar com env AUTOCORE_REFRESH_DOM_BEFORE_ACTION=false
+     *
+     * @param {number} [stabilityMs=300] Tempo mínimo em ms para considerar o DOM estável.
+     */
+    private static refreshDOM;
+    private static withRecovery;
+    private static applyValueHeuristics;
+    /**
+     * 🖼️ Obtém o locator correto considerando se estamos dentro de um iframe.
+     * Se switchTo foi chamado, usa o frameLocator para buscar elementos.
+     * @private
+     * @param {string | ILocator} elemento Seletor ou locator do elemento
+     * @returns {ILocator} Locator no contexto correto (page ou frame)
+     */
+    private static getLocatorInContext;
+    /**
+     * 🖼️ Verifica se estamos dentro de um iframe.
+     * @returns {boolean} true se switchTo foi chamado e estamos em um frame
+     */
+    static isInFrame(): boolean;
+    /**
+     * 🖼️ Obtém o seletor do frame atual.
+     * @returns {string | null} Seletor do frame atual ou null se não estiver em um frame
+     */
+    static getCurrentFrameSelector(): string | null;
+    static resolveWaitVisibilityOptions(timeoutOrOptions?: number | string | boolean | WaitVisibilityOptions, descricaoOrTirarPrint?: string | boolean, tirarPrintFallback?: boolean): Required<WaitVisibilityOptions>;
+    /**
+     * ✅ NOVO: Captura informações do stack trace para obter o nome do método
+     * @private
+     * @returns {string} Nome do método que chamou a ação
+     */
+    private static getCallerMethodName;
+    /**
+     * ✅ NOVO: Função auxiliar para interceptar ações no AutoDocs
+     * @private
+     * @param {string} action Nome da ação (click, fill, hover, etc.)
+     * @param {string} [selector] Seletor do elemento (opcional)
+     * @param {string} [url] URL da página (opcional)
+     * @param {any} [extraDetails] Detalhes extras específicos da ação
+     */
+    private static interceptForAutoDocs;
+    /**
+     * ✅ NOVO: Função auxiliar para atualizar status de sucesso no AutoDocs
+     * @private
+     * @param {string} action Nome da ação
+     * @param {string} [selector] Seletor do elemento (opcional)
+     * @param {boolean} success Se a ação foi bem-sucedida
+     * @param {number} duration Duração em ms
+     * @param {string} [error] Mensagem de erro (se houver)
+     */
+    private static updateAutoDocsStatus;
+    /**
+     * Obtém a página atual do contexto de teste.
+     * @public
+     * @returns {IPage}
+     * @throws {Error} Se a página não estiver disponível.
+     */
+    static getPage(): IPage;
+    /**
+     * 🆕 NOVO: Método para auto-inicializar o TestContext.page quando possível
+     * @param page Page do Playwright para inicializar automaticamente
+     */
+    static ensurePageInitialized(page?: any): void;
+    /**
+     * Adiciona log ao UnifiedReportManager.
+     * @private
+     * @param {string} message Mensagem de log.
+     */
+    private static logToUnified;
+    /**
+     * Registra metadados de ação no UnifiedReportManager.
+     * @private
+     * @param {string} actionType Tipo de ação.
+     * @param {boolean} success Sucesso da ação.
+     * @param {number} [duration] Duração em ms.
+     */
+    private static addActionMetadata;
+    /**
+     * 📡 Inicia a captura de logs de Network no terminal.
+     * A partir deste ponto, todas as requisições/respostas serão logadas no terminal.
+     * Use `stopNetworkLogging()` para parar e gerar o resumo.
+     *
+     * @example
+     * ```typescript
+     * await WebActions.startNetworkLogging()
+     * await WebActions.navigateTo('https://example.com')
+     * await WebActions.click('#button')
+     * const logs = await WebActions.stopNetworkLogging()
+     * ```
+     */
+    static startNetworkLogging(): Promise<void>;
+    /**
+     * 📡 Para a captura de logs de Network e exibe resumo no terminal.
+     *
+     * @returns {NetworkLogEntry[]} Array com todos os logs capturados
+     *
+     * @example
+     * ```typescript
+     * const logs = await WebActions.stopNetworkLogging()
+     * console.log(`Capturados ${logs.length} logs de rede`)
+     * ```
+     */
+    static stopNetworkLogging(): Promise<NetworkLogEntry[]>;
+    /**
+     * 📡 Retorna os logs de Network capturados até o momento (sem parar a captura).
+     *
+     * @returns {NetworkLogEntry[]} Array com logs capturados
+     */
+    static getNetworkLogs(): NetworkLogEntry[];
+    /**
+     * 📡 Verifica se a captura de Network está ativa.
+     */
+    static isNetworkLoggingEnabled(): boolean;
+    /**
+     * Helper para truncar URLs longas nos logs de network
+     * @private
+     */
+    private static truncateNetworkUrl;
+    /**
+     * Helper para formatar bytes de forma legível nos logs de network
+     * @private
+     */
+    private static formatNetworkBytes;
+    /**
+     * 🌐 MELHORADO: Navega para uma URL com ErrorHandling completo e recuperação automática.
+     * @param {string} url URL de destino.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {number} [tempo] Timeout em ms.
+     * @param {'load' | 'domcontentloaded' | 'networkidle' | 'commit'} [waitUntil] Estado de carregamento a esperar (default: 'networkidle').
+     */
+    static navigateTo(url: string, descricao?: string, tirarPrint?: boolean, tempo?: number, waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"): Promise<void>;
+    /**
+     * Preenche um campo/input.
+     * ✅ MELHORADO: Espera elemento estar visível antes de preencher.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} valor Valor a preencher.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {any} [pageParam] Page do Playwright (opcional, para auto-inicialização)
+     */
+    static setText(elemento: string | ILocator, valor: string, descricao?: string, tirarPrint?: boolean, pageParam?: any, force?: boolean): Promise<void>;
+    /**
+     * Preenche um campo de data usando digitação caractere por caractere.
+     * ✅ Resolve problemas com campos de data que têm máscara ou validação especial.
+     * ✅ Usa keyboard.type() que simula digitação real, funcionando melhor com máscaras.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator do campo de data.
+     * @param {string} data Data no formato esperado pelo campo (ex: "01/01/2025", "2025-01-01").
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {number} [delay=50] Delay entre cada caractere em ms (ajuste se a máscara for lenta).
+     * @param {DateFormat} [inputFormat] Formato de entrada da data (como você está passando).
+     * @param {DateFormat} [outputFormat] Formato de saída (como o campo espera receber).
+     *
+     * @example
+     * // Campo com máscara DD/MM/YYYY (padrão brasileiro)
+     * await WebActions.setDate(campoDataNascimento, '15/03/1990', 'Preenchendo data de nascimento');
+     *
+     * @example
+     * // Convertendo de formato brasileiro para americano
+     * await WebActions.setDate(campoData, '15/03/1990', 'Data', false, 50, 'DD/MM/YYYY', 'MM/DD/YYYY');
+     * // Resultado: digita 03/15/1990
+     *
+     * @example
+     * // Convertendo de ISO para brasileiro
+     * await WebActions.setDate(campoData, '1990-03-15', 'Data', false, 50, 'YYYY-MM-DD', 'DD/MM/YYYY');
+     * // Resultado: digita 15/03/1990
+     *
+     * @example
+     * // Usando DateOptions (forma mais limpa)
+     * await WebActions.setDate(campoData, '15/03/1990', {
+     *   descricao: 'Data de nascimento',
+     *   inputFormat: 'DD/MM/YYYY',
+     *   outputFormat: 'YYYY-MM-DD'
+     * });
+     */
+    static setDate(elemento: string | ILocator, data: string, descricaoOrOptions?: string | DateOptions, tirarPrint?: boolean, delay?: number, inputFormat?: DateFormat, outputFormat?: DateFormat): Promise<void>;
+    /**
+     * Preenche um campo de telefone (comportamento simples, como setDate).
+     * Tem comportamento semelhante a `setDate` (click, clear, type) e validação básica.
+     * Aceita `pressTab` para compatibilidade (padrão: true).
+     *
+     * @param elemento Seletor ou locator
+     * @param telefone Valor do telefone a ser inserido
+     * @param descricaoOrOptions Descrição ou opções (descricao, tirarPrint, delay, pressTab)
+     * @param tirarPrint Se deve tirar print
+     * @param delay Delay entre caracteres
+     * @param pressTab Se deve pressionar Tab ao final (padrão: true)
+     */
+    static setPhone(elemento: string | ILocator, telefone: string, descricaoOrOptions?: string | {
+        descricao?: string;
+        tirarPrint?: boolean;
+        delay?: number;
+        pressTab?: boolean;
+    }, tirarPrint?: boolean, delay?: number, pressTab?: boolean): Promise<void>;
+    /**
+     * Preenche campo de data usando estratégia alternativa com clear + type.
+     * ✅ Útil quando setDate não funciona por causa de validações específicas.
+     * ✅ Tenta múltiplas estratégias até uma funcionar.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator do campo de data.
+     * @param {string} data Data no formato esperado pelo campo (ex: "01/01/2025", "2025-01-01").
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {DateFormat} [inputFormat] Formato de entrada da data (como você está passando).
+     * @param {DateFormat} [outputFormat] Formato de saída (como o campo espera receber).
+     *
+     * @example
+     * await WebActions.setDateRobust(campoDataNascimento, '15/03/1990', 'Preenchendo data de nascimento');
+     *
+     * @example
+     * // Convertendo de formato brasileiro para americano
+     * await WebActions.setDateRobust(campoData, '15/03/1990', 'Data', false, 'DD/MM/YYYY', 'MM/DD/YYYY');
+     * // Resultado: digita 03/15/1990
+     *
+     * @example
+     * // Convertendo de ISO para brasileiro
+     * await WebActions.setDateRobust(campoData, '1990-03-15', 'Data', false, 'YYYY-MM-DD', 'DD/MM/YYYY');
+     * // Resultado: digita 15/03/1990
+     *
+     * @example
+     * // Usando DateOptions (forma mais limpa)
+     * await WebActions.setDateRobust(campoData, '15/03/1990', {
+     *   descricao: 'Data de nascimento',
+     *   inputFormat: 'DD/MM/YYYY',
+     *   outputFormat: 'YYYY-MM-DD'
+     * });
+     */
+    static setDateRobust(elemento: string | ILocator, data: string, descricaoOrOptions?: string | DateOptions, tirarPrint?: boolean, inputFormat?: DateFormat, outputFormat?: DateFormat, pressTab?: boolean): Promise<void>;
+    /**
+     * Seleciona uma opção a partir do XPath que aponta para a tag <option>.
+     * Ex: //select[@title='Visibilidade']/option[text()='Todas as cotações das organizações']
+     * Faz evaluate no browser para localizar o option, encontrar o select pai,
+     * aplicar o value/selected e disparar eventos 'input' e 'change'. Usa TestRecovery
+     * em caso de falha para tentar alternativas.
+     */
+    /**
+     * @deprecated Use `selectOption(optionXPath, valor, descricao)` — todas as estratégias foram unificadas em selectOption.
+     */
+    static selectOptionByXPath(optionXPath: string, descricao?: string): Promise<void>;
+    /**
+     * Preenche um campo de telefone de forma robusta (várias estratégias).
+     * Não pressiona `Tab` ao final para evitar mudanças indesejadas de foco.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} telefone Valor do telefone a ser inserido.
+     * @param {string|{descricao?:string,tirarPrint?:boolean,delay?:number}} descricaoOrOptions Descrição ou opções.
+     * @param {boolean} [tirarPrint=false] Se deve capturar evidência.
+     * @param {number} [delay] Delay entre caracteres em ms.
+     */
+    static setPhoneRobust(elemento: string | ILocator, telefone: string, descricaoOrOptions?: string | {
+        descricao?: string;
+        tirarPrint?: boolean;
+        delay?: number;
+        pressTab?: boolean;
+    }, tirarPrint?: boolean, delay?: number, pressTab?: boolean): Promise<void>;
+    /**
+     * Limpa um campo e digita o texto caractere por caractere.
+     * ✅ Útil para campos com máscaras, validações ou que não aceitam fill().
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} texto Texto a digitar.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {number} [delay=30] Delay entre caracteres em ms.
+     *
+     * @example
+     * await WebActions.clearAndType(campoCPF, '123.456.789-00', 'Preenchendo CPF');
+     */
+    static clearAndType(elemento: string | ILocator, texto: string, descricao?: string, tirarPrint?: boolean, delay?: number): Promise<void>;
+    /**
+     * Preenche campo de data HTML5 (type="date") usando o valor nativo.
+     * ✅ Para campos <input type="date"> que esperam formato YYYY-MM-DD.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator do campo de data HTML5.
+     * @param {string} data Data no formato ISO (YYYY-MM-DD) ou DD/MM/YYYY (será convertido).
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     *
+     * @example
+     * // Formato ISO direto
+     * await WebActions.setDateNative(campoData, '1990-03-15', 'Data de nascimento');
+     *
+     * @example
+     * // Formato brasileiro (será convertido automaticamente)
+     * await WebActions.setDateNative(campoData, '15/03/1990', 'Data de nascimento');
+     *
+     * @example
+     * // Com formato de entrada explícito (americano)
+     * await WebActions.setDateNative(campoData, '03/15/1990', 'Data', false, 'MM/DD/YYYY');
+     *
+     * @example
+     * // Usando DateOptions
+     * await WebActions.setDateNative(campoData, '15/03/1990', {
+     *   descricao: 'Data de nascimento',
+     *   inputFormat: 'DD/MM/YYYY'
+     * });
+     */
+    static setDateNative(elemento: string | ILocator, data: string, descricaoOrOptions?: string | DateOptions, tirarPrint?: boolean, inputFormat?: DateFormat): Promise<void>;
+    /**
+     * Converte uma data de um formato para outro.
+     *
+     * @param {string} data Data a ser convertida.
+     * @param {DateFormat} inputFormat Formato de entrada.
+     * @param {DateFormat} outputFormat Formato de saída.
+     * @returns {string} Data convertida.
+     *
+     * @example
+     * // Brasileiro para Americano
+     * const dataUS = WebActions.convertDate('15/03/1990', 'DD/MM/YYYY', 'MM/DD/YYYY')
+     * // Resultado: '03/15/1990'
+     *
+     * @example
+     * // Brasileiro para ISO
+     * const dataISO = WebActions.convertDate('15/03/1990', 'DD/MM/YYYY', 'YYYY-MM-DD')
+     * // Resultado: '1990-03-15'
+     * @deprecated Use `DateHelper.convert()` diretamente.
+     */
+    static convertDate(data: string, inputFormat: DateFormat, outputFormat: DateFormat): string;
+    /**
+     * Converte uma data para formato ISO (YYYY-MM-DD).
+     *
+     * @param {string} data Data a ser convertida.
+     * @param {DateFormat} [inputFormat] Formato de entrada (detecta automaticamente se não informado).
+     * @returns {string} Data em formato ISO.
+     *
+     * @example
+     * const dataISO = WebActions.toISODate('15/03/1990', 'DD/MM/YYYY')
+     * // Resultado: '1990-03-15'
+     *
+     * @example
+     * // Detecta automaticamente o formato
+     * const dataISO = WebActions.toISODate('15/03/1990')
+     * // Resultado: '1990-03-15'
+     * @deprecated Use `DateHelper.toISO()` diretamente.
+     */
+    static toISODate(data: string, inputFormat?: DateFormat): string;
+    /**
+     * Detecta automaticamente o formato de uma data.
+     *
+     * @param {string} data Data a ser analisada.
+     * @returns {DateFormat} Formato detectado.
+     *
+     * @example
+     * const formato = WebActions.detectDateFormat('15/03/1990')
+     * // Resultado: 'DD/MM/YYYY'
+     *
+     * @example
+     * const formato = WebActions.detectDateFormat('1990-03-15')
+     * // Resultado: 'YYYY-MM-DD'
+     * @deprecated Use `DateHelper.detectFormat()` diretamente.
+     */
+    static detectDateFormat(data: string): DateFormat;
+    /**
+     * Troca apenas o separador da data mantendo a ordem dos campos.
+     * Útil quando o usuário passa dd-mm-yyyy mas o campo espera dd/mm/yyyy.
+     *
+     * @param {string} data Data com separador atual.
+     * @param {string} newSeparator Novo separador desejado ('/', '-', '.').
+     * @returns {string} Data com novo separador.
+     *
+     * @example
+     * const dataBarra = WebActions.replaceDateSeparator('15-03-1990', '/')
+     * // Resultado: '15/03/1990'
+     *
+     * @example
+     * const dataHifen = WebActions.replaceDateSeparator('15/03/1990', '-')
+     * // Resultado: '15-03-1990'
+     *
+     * @example
+     * const dataPonto = WebActions.replaceDateSeparator('15/03/1990', '.')
+     * // Resultado: '15.03.1990'
+     * @deprecated Use `DateHelper.changeSeparator()` diretamente.
+     */
+    static replaceDateSeparator(data: string, newSeparator: "/" | "-" | "."): string;
+    /**
+     * Realiza clique em elemento.
+     * ✅ MELHORADO: Espera elemento estar visível e estável antes de clicar.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {any} [pageParam] Page do Playwright (opcional, para auto-inicialização)
+     */
+    static click(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean, pageParam?: any): Promise<void>;
+    /**
+     * Realiza duplo clique em elemento.
+     * Possui as mesmas estratégias do click(): direta com eventos nativos, force,
+     * tabela, lista/overlay, iframe — cada uma com fallback via Test Recovery.
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {any} [pageParam] Page alternativa (auto-inicializa se fornecida).
+     */
+    static doubleClick(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean, pageParam?: any): Promise<void>;
+    /**
+     * Realiza clique com botão direito.
+     * ✅ MELHORADO: Espera elemento estar visível antes de clicar.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     */
+    static rightClick(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Move o mouse para o centro do elemento.
+     * ✅ MELHORADO: Espera elemento estar visível antes de mover.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     */
+    static mouseMove(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Realiza hover sobre elemento.
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     */
+    static hover(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Seleciona opção em dropdown (por valor).
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} valor Valor da opção.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     */
+    static selectOption(elemento: string | ILocator, valor: string, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Seleciona opção em lista (por label).
+     * ✅ MELHORADO: Espera elemento estar visível antes de selecionar.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} texto Label da opção.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     */
+    /**
+     * @deprecated Use `selectOption(elemento, texto, descricao, tirarPrint)` — todas as estratégias foram unificadas em selectOption.
+     */
+    static selectFromList(elemento: string | ILocator, texto: string, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Seleciona opção em tabela (por texto).
+     * @param {string} seletorTabela Seletor da tabela.
+     * @param {string} texto Texto da célula.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     */
+    static selectTableOption(seletorTabela: string, texto: string, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Switch to frame by selector.
+     * @param {string} seletorFrame Frame selector.
+     * @param {string} [descricao] Action description.
+     * @throws {Error} If frame is not found.
+     */
+    /**
+     * 🔄 Recarrega a página atual e opcionalmente valida a presença de um elemento.
+     *
+     * @param {string | ILocator} [elementoValidacao] Elemento para validar após recarregar (opcional).
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {number} [timeout=30000] Timeout em ms para reload.
+     * @param {number} [waitAfterMs=0] Tempo extra de espera (ms) após o reload completar, antes de validar elemento. Útil para SPAs/Salesforce onde conteúdo assíncrono demora a renderizar.
+     * @returns {Promise<typeof WebActions>} Retorna a classe para encadeamento.
+     *
+     * @example
+     * // Recarregar página simples
+     * await WebActions.refresh('Recarregar página inicial');
+     *
+     * @example
+     * // Recarregar e validar elemento
+     * await WebActions.refresh('#elemento-inicial', 'Recarregar e validar elemento inicial', true);
+     *
+     * @example
+     * // Recarregar e esperar 3 segundos antes de prosseguir
+     * await WebActions.refresh('#painel', 'Aguardar painel carregar', false, 30000, 3000);
+     *
+     * @example
+     * // Encadeamento
+     * await WebActions
+     *   .refresh('#logo', 'Recarregar página')
+     *   .click('#botao', 'Clicar no botão');
+     */
+    static refresh(elementoValidacaoOrDescricao?: string | ILocator, descricao?: string, tirarPrint?: boolean, timeout?: number, waitAfterMs?: number): Promise<typeof WebActions>;
+    /**
+     * 🔄 Recarrega a página forçando bypass do cache (equivalente a Ctrl+Shift+R).
+     *
+     * Diferente do `refresh()` normal, este método limpa o cache do navegador
+     * antes de recarregar, garantindo que todos os recursos (JS, CSS, HTML)
+     * sejam buscados novamente do servidor — ideal para cenários onde o
+     * elemento não aparece porque o browser está usando uma versão cacheada.
+     *
+     * @param {string | ILocator} [elementoValidacao] Elemento para validar após recarregar.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {number} [timeout=30000] Timeout em ms.
+     * @param {number} [waitAfterMs=0] Tempo extra de espera (ms) após o reload completar. Útil quando o conteúdo demora a renderizar após recarga completa.
+     * @returns {Promise<typeof WebActions>} Retorna a classe para encadeamento.
+     *
+     * @example
+     * // Hard refresh simples (Ctrl+Shift+R)
+     * await WebActions.hardRefresh('Forçar recarga completa');
+     *
+     * @example
+     * // Hard refresh e validar elemento que não aparecia
+     * await WebActions.hardRefresh('#painel-ofertas', 'Forçar recarga para exibir ofertas', true);
+     *
+     * @example
+     * // Hard refresh com 5 segundos de espera extra
+     * await WebActions.hardRefresh('#grid-dados', 'Recarregar grid', false, 30000, 5000);
+     */
+    static hardRefresh(elementoValidacaoOrDescricao?: string | ILocator, descricao?: string, tirarPrint?: boolean, timeout?: number, waitAfterMs?: number): Promise<typeof WebActions>;
+    /**
+     * Closes the current page.
+     * @param {string} [descricao] Action description.
+     */
+    static closePage(descricao?: string): Promise<void>;
+    /**
+     * 🚨 Waits for a browser alert/dialog to appear.
+     * @param {number} [timeout=5000] Timeout in milliseconds to wait for alert.
+     * @param {string} [descricao] Action description.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     * @returns {Promise<string>} The alert message.
+     * @throws {Error} If alert doesn't appear within timeout.
+     */
+    static waitForAlert(timeout?: number, descricao?: string, tirarPrint?: boolean): Promise<string>;
+    /**
+     * 🚨 NOVO: Clica em um alert/dialog do browser (aceitar ou cancelar).
+     * @param {boolean} [aceitar=true] If true accepts alert, if false dismisses.
+     * @param {string} [textoParaDigitar] Text to type in prompt alerts.
+     * @param {string} [descricao] Action description.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     * @returns {Promise<string>} The alert message that was clicked.
+     * @throws {Error} If no active alert exists.
+     */
+    static clickAlert(aceitar?: boolean, textoParaDigitar?: string, descricao?: string, tirarPrint?: boolean): Promise<string>;
+    /**
+     * 🚨 Waits and automatically clicks an alert in a single action.
+     * @param {boolean} [aceitar=true] If true accepts alert, if false dismisses.
+     * @param {string} [textoParaDigitar] Text to type in prompt alerts.
+     * @param {number} [timeout=5000] Timeout in milliseconds to wait for alert.
+     * @param {string} [descricao] Action description.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     * @returns {Promise<string>} The alert message.
+     */
+    static waitAndClickAlert(aceitar?: boolean, textoParaDigitar?: string, timeout?: number, descricao?: string, tirarPrint?: boolean): Promise<string>;
+    /**
+     * Realiza upload de arquivos em campo file.
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string[]} filePaths Caminhos dos arquivos.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     */
+    static setFiles(elemento: string | ILocator, filePaths: string[], descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Realiza scroll para coordenadas x, y com verificação de que o scroll aconteceu.
+     * Usa múltiplas estratégias: window.scrollTo, scrollBy, e element.scrollTop.
+     *
+     * @param {number} x Coordenada X.
+     * @param {number} y Coordenada Y.
+     * @param {string} [descricao] Descrição da ação.
+     */
+    static scrollTo(x: number, y: number, descricao?: string): Promise<void>;
+    /**
+     * Realiza scroll até o elemento com verificação robusta.
+     * Usa múltiplas estratégias: scrollIntoViewIfNeeded, scrollIntoView via JS,
+     * e fallback com mouse.wheel. Verifica se o elemento ficou visível no viewport.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     */
+    static scrollToElement(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Verifica se um elemento está visível dentro do viewport atual.
+     * @param el Locator do elemento
+     * @param page Página atual
+     * @returns true se o elemento está no viewport
+     */
+    private static isElementInViewport;
+    /**
+     * 🖱️ Clica e segura por um tempo determinado no elemento informado.
+     * Compatível com Qandalf Java: clickAndHold(WebElement element, String descriptionToAction, int timeHold, Boolean getSnapshot)
+     *
+     * @param {string|ILocator} elemento Seletor ou locator do elemento.
+     * @param {string} descricao Descrição da ação para relatório.
+     * @param {number} timeHold Tempo que deseja segurar no elemento (em segundos).
+     * @param {boolean} [tirarPrint=false] Se deve tirar captura de tela.
+     * @returns {Promise<typeof WebActions>} Retorna a própria instância da classe para encadeamento.
+     *
+     * @example
+     * // Clicar e segurar por 2 segundos
+     * await WebActions.clickAndHold(
+     *   '#botaoMostrarMensagem',
+     *   'Clicar no botão para mostrar mensagem',
+     *   2,
+     *   true
+     * );
+     *
+     * @example
+     * // Encadeamento
+     * await WebActions
+     *   .clickAndHold('#elemento', 'Segurar elemento', 3, true)
+     *   .verificarExistencia('#mensagem', 'Validar mensagem');
+     */
+    static clickAndHold(elemento: string | ILocator, descricao: string, timeHold: number, tirarPrint?: boolean): Promise<typeof WebActions>;
+    /**
+     * Verifies custom condition.
+     * @param {() => boolean|Promise<boolean>} condicao Condition function.
+     * @param {string} descricaoCondicao Condition description.
+     * @param {string} [descricao] Action description.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     * @returns {Promise<boolean>}
+     */
+    static verifyCondition(condicao: () => boolean | Promise<boolean>, descricaoCondicao: string, descricao?: string, tirarPrint?: boolean): Promise<boolean>;
+    /**
+     * Presses a keyboard key.
+     * @param {string} tecla Key to press.
+     * @param {string} [descricao] Action description.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     */
+    static pressKey(tecla: string, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * 🔧 Presses a key multiple times while holding a modifier key.
+     * Compatible with Qandalf Java: Actions.keyDown(Keys.CONTROL) + pressKey + Actions.keyUp(Keys.CONTROL)
+     *
+     * @param {'Control' | 'Shift' | 'Alt' | 'Meta'} modificador Modifier key to hold.
+     * @param {string} tecla Key to press (e.g., 'Subtract', 'Add', 'a', 'c').
+     * @param {number} [vezes=1] Number of times to press the key.
+     * @param {string} [descricao] Action description for report.
+     * @param {boolean} [tirarPrint=false] Whether to capture screenshot.
+     * @returns {Promise<typeof WebActions>} Returns WebActions for chaining.
+     *
+     * @example
+     * // Ctrl+- three times to zoom out
+     * await WebActions.pressWithModifier('Control', 'Subtract', 3, 'Zooming Out');
+     *
+     * @example
+     * // Ctrl+Shift+S for save as
+     * await WebActions.pressWithModifier('Control', 'Shift+s', 1, 'Save As');
+     *
+     * @example
+     * // Ctrl+C for copy
+     * await WebActions.pressWithModifier('Control', 'c', 1, 'Copy');
+     */
+    static pressWithModifier(modificador: "Control" | "Shift" | "Alt" | "Meta", tecla: string, vezes?: number, descricao?: string, tirarPrint?: boolean): Promise<typeof WebActions>;
+    /**
+     * Waits for a fixed time in seconds.
+     * @param {number} seconds Time in seconds.
+     * @param {string} [description] Action description.
+     * @param {boolean} [takeScreenshotAfter=true] Whether to capture screenshot after wait.
+     *
+     * @example
+     * // With screenshot (default) - 5 seconds
+     * await WebActions.fixedWait(5, 'Waiting for load')
+     *
+     * // Without screenshot - 3 seconds
+     * await WebActions.fixedWait(3, 'Waiting for load', false)
+     */
+    static fixedWait(segundos: number, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Espera até elemento estar visível.
+     * ✅ MELHORADO: Primeiro espera a página carregar (networkidle), depois procura o elemento.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {number|WaitVisibilityOptions} [timeout] Timeout em ms ou objeto de opções.
+     * @param {string} [descricao] Descrição opcional quando usando assinatura posicional.
+     * @param {boolean} [tirarPrint] Evidência opcional quando usando assinatura posicional.
+     *
+     * @example
+     * await WebActions.waitForVisible('#botao')
+     * await WebActions.waitForVisible('#botao', 3000, 'Esperar botão', true)
+     * await WebActions.waitForVisible('#botao', 'Esperar botão sem timeout custom')
+     * await WebActions.waitForVisible('#botao', { descricao: 'Esperar', tirarPrint: true })
+     */
+    static waitForVisible(elemento: string | ILocator, options?: WaitVisibilityOptions): Promise<void>;
+    static waitForVisible(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    static waitForVisible(elemento: string | ILocator, timeout?: number, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Non-throwing variant of `waitForVisible` that returns boolean.
+     * Useful when you want to check visibility in conditions without throwing.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {number|string|boolean|WaitVisibilityOptions} [timeoutOrOptions] Timeout em ms, descrição, ou objeto de opções.
+     * @param {string|boolean} [descricaoOrTirarPrint] Descrição ou flag de screenshot.
+     * @param {boolean} [tirarPrintFallback] Flag de screenshot quando usando assinatura posicional.
+     * @returns {Promise<boolean>} true se elemento está visível, false caso contrário.
+     *
+     * @example
+     * // Usar em condições sem lançar erro
+     * if (await WebActions.waitForVisibleBoolean('#modal', 3000)) {
+     *   await WebActions.click('#closeModal');
+     * }
+     *
+     * @example
+     * // Verificar se elemento apareceu
+     * const isVisible = await WebActions.waitForVisibleBoolean('#successMessage', 5000, 'Aguardando mensagem');
+     * console.log(isVisible ? 'Mensagem apareceu!' : 'Mensagem não apareceu');
+     */
+    static waitForVisibleBoolean(elemento: string | ILocator, timeoutOrOptions?: number | string | boolean | WaitVisibilityOptions, descricaoOrTirarPrint?: string | boolean, tirarPrintFallback?: boolean): Promise<boolean>;
+    static _waitForVisibleImpl(elemento: string | ILocator, opts: Required<WaitVisibilityOptions & Partial<ExtendedWaitVisibilityOptions>>): Promise<boolean>;
+    /**
+     * Ensure element is visible using a short initial probe, then consult TestRecovery if needed.
+     * - initial probe: 5s (or less if maxTimeout smaller)
+     * - max default timeout: 30s
+     */
+    static ensureVisibleWithRecovery(elOrSelector: string | ILocator, explicitTimeoutMs?: number): Promise<void>;
+    /**
+      try { await page.waitForLoadState('domcontentloaded', { timeout: 1500 }); } catch {}
+      // preparar candidatos de selector (normalize-space / parent select etc.)
+      const originalSelector = WebActions.extractSelector(elemento)
+      const selectorCandidates = WebActions.getSelectorCandidates(originalSelector)
+      const matchedSelector = await WebActions.findFirstMatchingSelector(page, selectorCandidates)
+      const selectorToUse = matchedSelector || originalSelector
+   * Useful for loaders, spinners, or loading elements.
+        const selector = selectorToUse;
+              const sel = selector
+        const selector = selectorToUse;
+        const selector = selectorToUse;
+        const selector = selectorToUse;
+      try {
+        const selector = selectorToUse;
+   * @example
+   * // Wait for loader to disappear
+   * await WebActions.waitWhileVisible('#loader', 500, 30000, 'Waiting for loader');
+   *
+   * // Wait for spinner with default timeout
+   * await WebActions.waitWhileVisible('.spinner', 1000, undefined, 'Waiting for spinner');
+   */
+    static waitWhileVisible(elemento: string | ILocator, intervalo?: number, timeout?: number, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Waits until element is clickable.
+     * @param {string|ILocator} elemento Selector or locator.
+     * @param {number} [timeout] Timeout in ms.
+     * @param {string} [descricao] Action description.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     */
+    static waitForClickable(elemento: string | ILocator, timeout?: number, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Validates if an element is present and visible on the screen.
+     * Useful for validating elements after login or navigation.
+     *
+     * @param {string|ILocator} elemento Element selector or locator to validate.
+     * @param {string} [descricao] Description of the action (used in reports).
+     * @param {boolean} [tirarPrint=false] Whether to capture a screenshot.
+     * @param {number} [timeout] Timeout in ms (default: project timeout).
+     * @returns {Promise<boolean>} Returns true if element is visible, false otherwise.
+     *
+     * @example
+     * // Validate element presence after login
+     * await WebActions.validateObject('#dashboard', 'Validar presença do dashboard', true);
+     *
+     * // Validate without screenshot
+     * const isVisible = await WebActions.validateObject('.welcome-message', 'Verificar mensagem de boas-vindas');
+     *
+     * // With custom timeout
+     * await WebActions.validateObject('#userMenu', 'Validar menu do usuário', true, 10000);
+     */
+    static validateObject(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean, timeout?: number): Promise<boolean>;
+    /**
+     * Validates if elements exist and returns the count.
+     * Supports toHaveCount-style assertions.
+     * Does NOT throw an error, just returns the count for flexible assertions.
+     *
+     * @param {string|ILocator} elemento Element selector or locator to validate.
+     * @param {string} [descricao] Description of the action (used in reports).
+     * @param {boolean} [tirarPrint=false] Whether to capture a screenshot.
+     * @param {number} [expectedCount] Optional expected count - if provided, validates exact match.
+     * @returns {Promise<number>} Returns the count of matching elements.
+     *
+     * @example
+     * // Get count of elements
+     * const count = await WebActions.validateObjectCount('.list-item', 'Contar itens');
+     * expect(count).toBeGreaterThan(0);
+     *
+     * // Validate exact count (like toHaveCount)
+     * const count = await WebActions.validateObjectCount('.row', 'Validar linhas', false, 5);
+     * // Throws if count !== 5
+     *
+     * // Use in assertions
+     * const itemCount = await WebActions.validateObjectCount('#cart .item', 'Itens no carrinho');
+     * expect(itemCount).toBe(3);
+     */
+    static validateObjectCount(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean, expectedCount?: number): Promise<number>;
+    /**
+     * Counts the number of elements matching the selector.
+     * Useful for validations that need to check element count.
+     *
+     * @param {string|ILocator} elemento Element selector or locator to count.
+     * @param {string} [descricao] Description of the action (used in reports).
+     * @param {boolean} [tirarPrint=false] Whether to capture a screenshot.
+     * @returns {Promise<number>} Returns the count of matching elements.
+     *
+     * @example
+     * // Count items in a list
+     * const count = await WebActions.countElements('.list-item', 'Contar itens da lista');
+     * console.log(`Encontrados ${count} itens`);
+     *
+     * // Validate no errors exist
+     * const errorCount = await WebActions.countElements('.error-message', 'Contar erros');
+     * if (errorCount === 0) {
+     *   console.log('Nenhum erro encontrado!');
+     * }
+     */
+    static countElements(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<number>;
+    /**
+     * Validates if an element is NOT present or NOT visible on the screen.
+     * Useful for validating that elements have been removed or are hidden.
+     * Supports count validation using `.count(0)` style.
+     *
+     * @param {string|ILocator} elemento Element selector or locator to validate.
+     * @param {string} [descricao] Description of the action (used in reports).
+     * @param {boolean} [tirarPrint=false] Whether to capture a screenshot.
+     * @param {number} [timeout] Timeout in ms (default: project timeout).
+     * @returns {Promise<boolean>} Returns true if element is NOT visible, false otherwise.
+     *
+     * @example
+     * // Validate that loading spinner disappeared
+     * await WebActions.validateObjectNotExists('.loading-spinner', 'Validar que spinner desapareceu', true);
+     *
+     * // Validate error message is not shown
+     * const isHidden = await WebActions.validateObjectNotExists('#errorMsg', 'Verificar ausência de erro');
+     *
+     * // With custom timeout
+     * await WebActions.validateObjectNotExists('.modal', 'Validar que modal fechou', true, 5000);
+     *
+     * // Using locator directly (validates count === 0)
+     * await WebActions.validateObjectNotExists(this.divError(), 'Validar sem erros');
+     */
+    static validateObjectNotExists(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean, timeout?: number): Promise<boolean>;
+    /**
+     * Validates if elements matching the selector do NOT exist (count === 0).
+     * Returns the count of elements found, useful for assertions.
+     * Does NOT throw an error, just returns the count.
+     *
+     * @param {string|ILocator} elemento Element selector or locator to validate.
+     * @param {string} [descricao] Description of the action (used in reports).
+     * @param {boolean} [tirarPrint=false] Whether to capture a screenshot.
+     * @returns {Promise<number>} Returns the count of matching elements (0 if none found).
+     *
+     * @example
+     * // Validate no errors exist and get count
+     * const errorCount = await WebActions.validateObjectNotExistsCount('.error-message', 'Verificar ausência de erros');
+     * if (errorCount === 0) {
+     *   console.log('Nenhum erro encontrado!');
+     * } else {
+     *   console.log(`Ainda existem ${errorCount} erro(s)`);
+     * }
+     *
+     * // Use in assertions
+     * const count = await WebActions.validateObjectNotExistsCount('#modal', 'Validar que modal fechou');
+     * expect(count).toBe(0);
+     */
+    static validateObjectNotExistsCount(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<number>;
+    /**
+     * Validates that an element has the expected count.
+     * Works like Playwright's expect(locator).toHaveCount(n).
+     *
+     * @param {string|ILocator} elemento Element selector or locator to validate.
+     * @param {number} expectedCount Expected number of elements.
+     * @param {string} [descricao] Description of the action (used in reports).
+     * @param {boolean} [tirarPrint=false] Whether to capture a screenshot.
+     * @param {number} [timeout] Timeout in ms (default: project timeout).
+     * @returns {Promise<boolean>} Returns true if count matches, throws error otherwise.
+     *
+     * @example
+     * // Validate no error messages exist (count === 0)
+     * await WebActions.toHaveCount(this.divMessageError(), 0, 'Validando que não há erros');
+     *
+     * // Validate exactly 5 items in list
+     * await WebActions.toHaveCount('.list-item', 5, 'Validando 5 itens na lista');
+     *
+     * // Validate at least one result (will fail if count !== 1)
+     * await WebActions.toHaveCount('#result', 1, 'Validando resultado único');
+     */
+    static toHaveCount(elemento: string | ILocator, expectedCount: number, descricao?: string, tirarPrint?: boolean, timeout?: number): Promise<boolean>;
+    /**
+     * Waits for network idle state.
+     * @param {string} [descricao] Action description.
+     * @param {number} [timeout] Timeout in ms.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     */
+    static waitForNetworkIdle(descricao?: string, timeout?: number, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Waits for navigation (load, domcontentloaded, etc).
+     * @param {string} [descricao] Action description.
+     * @param {number} [timeout] Timeout in ms.
+     * @param {string} [waitUntil] Navigation state.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     */
+    static waitForNavigation(descricao?: string, timeout?: number, waitUntil?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Captures screenshot and attaches to report.
+     * @param {string} descricao Evidence description.
+     * @returns {Promise<string>} Path of captured screenshot
+     */
+    static takeScreenshot(descricao: string): Promise<string>;
+    /**
+     * Gets field/input value.
+     * @param {string|ILocator} elemento Selector or locator.
+     * @param {string} [descricao] Action description.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     * @returns {Promise<string|null>}
+     */
+    static getFieldValue(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<string | null>;
+    /**
+     * Gets element attribute.
+     * @param {string|ILocator} elemento Selector or locator.
+     * @param {string} atributo Attribute name.
+     * @param {string} [descricao] Action description.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     * @returns {Promise<string|null>}
+     */
+    static getAttribute(elemento: string | ILocator, atributo: string, descricao?: string, tirarPrint?: boolean): Promise<string | null>;
+    /**
+     * Verifica se o elemento existe no DOM (não necessariamente visível).
+     * Retorna um objeto com `exists` e `message` para maior compatibilidade com validações.
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @returns {Promise<{exists: boolean, message: string}>}
+     */
+    static verifyExists(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<{
+        exists: boolean;
+        message: string;
+    }>;
+    /**
+     * Clears field/input.
+     * @param {string|ILocator} elemento Selector or locator.
+     * @param {string} [descricao] Action description.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     */
+    static clearField(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Validates if checkbox is checked.
+     * @param {string|ILocator} elemento Selector or locator.
+     * @param {string} [descricao] Action description.
+     * @param {boolean} [tirarPrint] Whether to capture evidence.
+     * @returns {Promise<{checked: boolean, message: string}>}
+     */
+    static validateCheckboxChecked(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<{
+        checked: boolean;
+        message: string;
+    }>;
+    /**
+     * Waits for element to appear (alias for waitForVisible).
+     * @deprecated Use `waitForVisible()` diretamente.
+     */
+    static waitForElement(elemento: ILocator | string, descricao?: string, timeout?: number): Promise<void>;
+    /**
+     * Waits for element to be visible (alias for waitForVisible).
+     * @deprecated Use `waitForVisible()` diretamente.
+     */
+    static waitForElementVisible(elemento: ILocator | string, descricao?: string, timeout?: number): Promise<void>;
+    /**
+     * Waits for element to be removed/detached.
+     */
+    static waitForElementDetached(elemento: ILocator | string, descricao?: string, timeout?: number): Promise<void>;
+    /**
+     * Checks if element is visible.
+     */
+    static isVisible(elemento: ILocator | string, descricao?: string): Promise<boolean>;
+    /**
+     * Checks if element is enabled.
+     */
+    static isEnabled(elemento: ILocator | string, descricao?: string): Promise<boolean>;
+    /**
+     * Gets element text (alias for getText).
+     */
+    static getText(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean): Promise<string>;
+    static getTextContent(elemento: ILocator | string, descricao?: string, tirarPrint?: boolean): Promise<string>;
+    /**
+     * Checks a checkbox.
+     */
+    static checkCheckbox(elemento: ILocator | string, descricao?: string, tirarPrint?: boolean, minIntervalMs?: number): Promise<void>;
+    /**
+     * Unchecks a checkbox.
+     */
+    static uncheckCheckbox(elemento: ILocator | string, descricao?: string, tirarPrint?: boolean, minIntervalMs?: number): Promise<void>;
+    /**
+     * Types text slowly into element.
+     */
+    static typeSlowly(elemento: ILocator | string, texto: string, descricao?: string, delay?: number, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Focuses on an element.
+     */
+    static focus(elemento: ILocator | string, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Goes back one page in history.
+     */
+    static goBack(descricao?: string, timeout?: number): Promise<void>;
+    /**
+     * Goes forward one page in history.
+     */
+    static goForward(descricao?: string, timeout?: number): Promise<void>;
+    /**
+     * Sets the viewport size.
+     */
+    static setViewportSize(width: number, height: number, descricao?: string): Promise<void>;
+    /**
+     * Executes JavaScript code on the page.
+     */
+    static executeJavaScript(codigo: string, descricao?: string): Promise<any>;
+    /**
+     * Waits for page load state.
+     */
+    static waitForLoad(estado?: "load" | "domcontentloaded" | "networkidle", descricao?: string, timeout?: number): Promise<void>;
+    /**
+     * 🆕 Espera a página ficar completamente pronta para interação.
+     * Ideal para aplicações SPA lentas como Salesforce/SFA.
+     * Combina: networkidle + espera spinners sumirem + estabilização DOM.
+     *
+     * @param {string} [descricao] Descrição da ação.
+     * @param {number} [timeout] Timeout em ms (default: 60000).
+     * @param {string[]} [spinnerSelectors] Seletores de spinners/loaders a esperar sumirem.
+     * @param {boolean} [tirarPrint] Se deve capturar screenshot após estabilização.
+     *
+     * @example
+     * await WebActions.waitForPageReady('Aguardando dashboard carregar')
+     * await WebActions.waitForPageReady('Após login', 120000, ['.spinner', '.loading'])
+     */
+    static waitForPageReady(descricao?: string, timeout?: number, spinnerSelectors?: string[], tirarPrint?: boolean): Promise<void>;
+    /**
+     * 🆕 Clica e espera a página carregar completamente.
+     * Ideal para cliques que causam navegação em SPAs lentas.
+     *
+     * @param {string|ILocator} elemento Seletor ou locator.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {number} [timeout] Timeout para aguardar carregamento.
+     *
+     * @example
+     * await WebActions.clickAndWait('#btnLogin', 'Clicando em Login')
+     * await WebActions.clickAndWait(page.getByRole('button', { name: 'Entrar' }), 'Login')
+     */
+    static clickAndWait(elemento: string | ILocator, descricao?: string, tirarPrint?: boolean, timeout?: number): Promise<void>;
+    /**
+     * 🆕 Clica em um menu/dropdown e depois clica na opção desejada.
+     * Ideal para menus dinâmicos que aparecem após clique (ex: dropdowns, context menus).
+     *
+     * @param {string|ILocator} menuElement Seletor ou locator do botão/trigger do menu.
+     * @param {string|ILocator} optionElement Seletor ou locator da opção dentro do menu.
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @param {number} [waitMs] Tempo em ms para aguardar opção aparecer (default: 3000).
+     * @param {boolean} [forceClick] Se deve forçar o clique na opção (default: true).
+     *
+     * @example
+     * // Menu dropdown simples
+     * await WebActions.clickMenuOption('#btnMenu', '#opcaoAnexos', 'Selecionar Anexos')
+     *
+     * @example
+     * // Menu com seta e opções dinâmicas
+     * await WebActions.clickMenuOption(
+     *   this.botaoSetaListaTelas,
+     *   this.linkTelaLista('Anexos'),
+     *   'Acessar menu Anexos',
+     *   true
+     * )
+     */
+    static clickMenuOption(menuElement: string | ILocator, optionElement: string | ILocator, descricao?: string, tirarPrint?: boolean, waitMs?: number, forceClick?: boolean): Promise<void>;
+    /**
+     * 🆕 Clica em um dropdown e seleciona uma opção por texto visível.
+     * Ideal para selects customizados ou dropdowns que não são <select> nativo.
+     *
+     * @param {string|ILocator} dropdownElement Seletor ou locator do dropdown.
+     * @param {string} optionText Texto da opção a selecionar.
+     * @param {string} [optionSelector] Seletor base das opções (default: tenta detectar).
+     * @param {string} [descricao] Descrição da ação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     *
+     * @example
+     * // Dropdown customizado
+     * await WebActions.selectDropdownOption(
+     *   this.campoVisibilidade,
+     *   'Todas as cotações das organizações',
+     *   undefined,
+     *   'Selecionando visibilidade'
+     * )
+     */
+    static selectDropdownOption(dropdownElement: string | ILocator, optionText: string, optionSelector?: string, descricao?: string, tirarPrint?: boolean): Promise<void>;
+    /**
+     * Obtém a URL atual da página.
+     * @param descricao - Descrição da ação
+     * @param tirarPrint - Se deve tirar screenshot
+     * @returns URL atual da página
+     */
+    static getUrl(descricao?: string, tirarPrint?: boolean): Promise<string>;
+    /**
+     * Valida se dois valores são iguais.
+     * @param {any} valorAtual Valor atual obtido.
+     * @param {any} valorEsperado Valor esperado.
+     * @param {string} [descricao] Descrição da validação.
+     * @param {boolean} [tirarPrint] Se deve capturar evidência.
+     * @returns {Promise<boolean>} True se os valores são iguais.
+     * @throws {Error} Se os valores não são iguais.
+     */
+    static validateEquals(valorAtual: any, valorEsperado: any, descricao?: string, tirarPrint?: boolean): Promise<boolean>;
+    /**
+     * 🖼️ Troca o foco para um iframe específico.
+     * Permite interagir com elementos dentro de iframes.
+     *
+     * @param {string | ILocator} element Seletor ou Locator do iframe.
+     * @param {string} descriptionToAction Descrição da ação para relatório.
+     * @param {boolean} [getSnapShot=false] Se deve tirar captura de tela.
+     * @returns {Promise<typeof WebActions>} Retorna a classe para encadeamento.
+     * @throws {Error} Se o iframe não for encontrado.
+     *
+     * @example
+     * // Uso com seletor string
+     * await WebActions.switchTo('#meuIframe', 'Mudar para iframe do formulário', true);
+     * await WebActions.setText('#campoNoIframe', 'valorTeste', 'Preencher campo', false);
+     * await WebActions.switchToDefault('Voltar para página principal');
+     *
+     * @example
+     * // Uso com Locator
+     * const iframeLocator = page.locator('iframe[name="formFrame"]');
+     * await WebActions.switchTo(iframeLocator, 'Acessar iframe de formulário', true);
+     */
+    static switchTo(element: string | ILocator, descriptionToAction: string, getSnapShot?: boolean): Promise<typeof WebActions>;
+    /**
+     * 🏠 Volta o foco para a página principal (sai do iframe).
+     *
+     * @param {string} descriptionToAction Descrição da ação para relatório.
+     * @param {boolean} [getSnapShot=false] Se deve tirar captura de tela.
+     * @returns {Promise<typeof WebActions>} Retorna a classe para encadeamento.
+     *
+     * @example
+     * await WebActions.switchTo('#meuIframe', 'Entrar no iframe', true);
+     * await WebActions.setText('#campo', 'valor', 'Preencher', false);
+     * await WebActions.switchToDefault('Voltar para página padrão');
+     */
+    static switchToDefault(descriptionToAction: string, getSnapShot?: boolean): Promise<typeof WebActions>;
+    /**
+     * 🪟 Troca o foco para uma nova janela/aba baseado na URL.
+     * Útil quando um clique abre uma nova janela e você precisa interagir com ela.
+     *
+     * @param {string} url URL (ou parte dela) da nova janela.
+     * @param {string} descriptionToAction Descrição da ação para relatório.
+     * @param {boolean} [getSnapShot=false] Se deve tirar captura de tela.
+     * @returns {Promise<typeof WebActions>} Retorna a classe para encadeamento.
+     * @throws {Error} Se a janela com a URL especificada não for encontrada.
+     *
+     * @example
+     * // Clicar em link que abre nova janela e mudar para ela
+     * await WebActions.click('#linkNovaJanela', 'Abrir nova janela', true);
+     * await WebActions.switchToWindowByUrl('http://example.com/nova', 'Mudar para nova janela', true);
+     * // Agora você está na nova janela
+     * await WebActions.getText('#tituloNovo', 'Obter título', false);
+     */
+    static switchToWindowByUrl(url: string, descriptionToAction: string, getSnapShot?: boolean): Promise<typeof WebActions>;
+    /**
+     * 🪟 Troca o foco para uma nova janela/aba baseado no título.
+     *
+     * @param {string} title Título (ou parte dele) da nova janela.
+     * @param {string} descriptionToAction Descrição da ação para relatório.
+     * @param {boolean} [getSnapShot=false] Se deve tirar captura de tela.
+     * @returns {Promise<typeof WebActions>} Retorna a classe para encadeamento.
+     * @throws {Error} Se a janela com o título especificado não for encontrada.
+     *
+     * @example
+     * await WebActions.click('#linkNovaJanela', 'Abrir nova janela', true);
+     * await WebActions.switchToWindowByTitle('Nova Página', 'Mudar para nova janela', true);
+     */
+    static switchToWindowByTitle(title: string, descriptionToAction: string, getSnapShot?: boolean): Promise<typeof WebActions>;
+    /**
+     * 🔙 Fecha a janela/aba atual e volta para a janela anterior.
+     *
+     * @param {string} descriptionToAction Descrição da ação para relatório.
+     * @param {boolean} [getSnapShot=false] Se deve tirar captura de tela.
+     * @returns {Promise<typeof WebActions>} Retorna a classe para encadeamento.
+     *
+     * @example
+     * await WebActions.click('#linkNovaJanela', 'Abrir nova janela', true);
+     * await WebActions.switchToWindowByUrl('http://example.com/nova', 'Mudar para nova janela', true);
+     * // Fazer algo na nova janela...
+     * await WebActions.closeWindowAndSwitchBack('Fechar e voltar', true);
+     */
+    static closeWindowAndSwitchBack(descriptionToAction: string, getSnapShot?: boolean): Promise<typeof WebActions>;
+    /**
+     * 📋 Obtém a quantidade de janelas/abas abertas no contexto atual.
+     *
+     * @param {string} [descricao] Descrição da ação para relatório.
+     * @returns {Promise<number>} Número de janelas abertas.
+     *
+     * @example
+     * const qtdJanelas = await WebActions.getWindowCount('Verificar janelas abertas');
+     * console.log(`Janelas abertas: ${qtdJanelas}`);
+     */
+    static getWindowCount(descricao?: string): Promise<number>;
+    /**
+     * 🗑️ Fecha todas as abas/janelas abertas, exceto a principal.
+     * Tenta fechar botões específicos de abas dentro da página antes de fechar as janelas do navegador.
+     *
+     * @param {string | ILocator} [closeTabCadenceSelector] Seletor do botão de fechar aba Cadence Builder (opcional).
+     * @param {string | ILocator} [closeTabItemSelector] Seletor do botão de fechar aba item (opcional).
+     * @param {number} [waitTime=1000] Tempo de espera após fechar cada aba (em ms).
+     * @param {boolean} [getSnapShot=false] Se deve tirar captura de tela.
+     * @returns {Promise<typeof WebActions>} Retorna a classe para encadeamento.
+     *
+     * @example
+     * // Fechar todas as abas/janelas abertas
+     * await WebActions.closeAllTabs();
+     *
+     * @example
+     * // Fechar abas específicas com seletores personalizados
+     * await WebActions.closeAllTabs(
+     *   '[data-testid="close-cadence"]',
+     *   '.close-tab-button',
+     *   2000,
+     *   true
+     * );
+     */
+    static closeAllTabs(closeTabCadenceSelector?: string | ILocator, closeTabItemSelector?: string | ILocator, waitTime?: number, getSnapShot?: boolean): Promise<typeof WebActions>;
+    /**
+     * 🔍 Obtém todos os elementos que correspondem ao seletor fornecido.
+     * Retorna um array de ILocator para todos os elementos encontrados.
+     *
+     * @param {string | ILocator} elemento Seletor CSS, XPath ou ILocator do elemento.
+     * @param {string} [descricao] Descrição da ação para logs (opcional).
+     * @returns {Promise<ILocator[]>} Array de ILocator com todos os elementos encontrados.
+     *
+     * @example
+     * // Obter todos os botões na página
+     * const botoes = await WebActions.getAllElements('button', 'Buscar todos os botões');
+     * console.log(`Encontrados ${botoes.length} botões`);
+     *
+     * @example
+     * // Obter todos os elementos de uma lista
+     * const items = await WebActions.getAllElements('.list-item');
+     * for (const item of items) {
+     *   const texto = await item.textContent();
+     *   console.log(texto);
+     * }
+     */
+    static getAllElements(elemento: string | ILocator, descricao?: string): Promise<ILocator[]>;
+    /**
+     * 🔧 Altera o innerText de um elemento via JavaScript.
+     * Compatível com Qandalf Java: executeScript para alterar innerText.
+     * Útil para elementos que não aceitam preenchimento normal ou labels/spans.
+     *
+     * @param {string | ILocator} elemento Seletor CSS/XPath ou ILocator do elemento.
+     * @param {string} texto Texto a ser definido no innerText.
+     * @param {string} [descricao] Descrição da ação para relatório.
+     * @param {boolean} [tirarPrint=false] Se deve capturar captura de tela.
+     * @returns {Promise<typeof WebActions>} Retorna a classe para encadeamento.
+     *
+     * @example
+     * // Alterar texto de um label
+     * await WebActions.setInnerText('#labelProbabilidade', '75%', 'Definir probabilidade', true);
+     *
+     * @example
+     * // Uso com variável
+     * const taxProbability = 85;
+     * await WebActions.setInnerText(
+     *   this.selecionarProbabilidadeParceiroBeforeText,
+     *   `${taxProbability}%`,
+     *   'Alterando probabilidade do parceiro',
+     *   true
+     * );
+     */
+    static setInnerText(elemento: string | ILocator, texto: string, descricao?: string, tirarPrint?: boolean): Promise<typeof WebActions>;
+    /**
+     * 🔧 Altera o innerHTML de um elemento via JavaScript.
+     * Útil para inserir HTML dinâmico em elementos.
+     *
+     * @param {string | ILocator} elemento Seletor CSS/XPath ou ILocator do elemento.
+     * @param {string} html HTML a ser definido no innerHTML.
+     * @param {string} [descricao] Descrição da ação para relatório.
+     * @param {boolean} [tirarPrint=false] Se deve capturar captura de tela.
+     * @returns {Promise<typeof WebActions>} Retorna a classe para encadeamento.
+     *
+     * @example
+     * await WebActions.setInnerHTML('#container', '<span class="destaque">Novo conteúdo</span>', 'Inserir HTML', true);
+     */
+    static setInnerHTML(elemento: string | ILocator, html: string, descricao?: string, tirarPrint?: boolean): Promise<typeof WebActions>;
+    /**
+     * 🔧 Executa um script JavaScript customizado no contexto do elemento.
+     * Compatível com Qandalf Java: executeScript genérico.
+     *
+     * @param {string | ILocator} elemento Seletor CSS/XPath ou ILocator do elemento.
+     * @param {string} script Script JavaScript a ser executado. Use 'element' para referenciar o elemento.
+     * @param {string} [descricao] Descrição da ação para relatório.
+     * @param {boolean} [tirarPrint=false] Se deve capturar captura de tela.
+     * @returns {Promise<unknown>} Resultado da execução do script.
+     *
+     * @example
+     * // Alterar estilo do elemento
+     * await WebActions.executeScriptOnElement('#botao', 'element.style.backgroundColor = "red"', 'Destacar botão');
+     *
+     * @example
+     * // Obter propriedade do elemento
+     * const offsetTop = await WebActions.executeScriptOnElement('#header', 'return element.offsetTop');
+     */
+    static executeScriptOnElement(elemento: string | ILocator, script: string, descricao?: string, tirarPrint?: boolean): Promise<unknown>;
+    /** Flag para controle de inicialização do extrator */
+    private static _catalogExtractorReady;
+    /** URLs já populadas automaticamente pelo catálogo (lazy auto-refresh, uma vez por página) */
+    private static _catalogPopulatedPages;
+    /**
+     * Garante que o extrator do XPathCatalog esteja configurado.
+     * Registra `extractBasicPageStructure` como fonte de dados.
+     */
+    private static ensureCatalogExtractor;
+    /**
+     * Extrai a estrutura da página atual e armazena no catálogo interno.
+     * Equivale a `extract_page_structure` do MCP, porém local via Playwright.
+     *
+     * @returns Estrutura bruta capturada
+     *
+     * @example
+     * ```ts
+     * const structure = await WebActions.extractPageStructure()
+     * console.log(structure.inputs?.length, 'inputs encontrados')
+     * ```
+     */
+    static extractPageStructure(): Promise<RawPageStructure>;
+    /**
+     * Obtém catálogo de XPaths da página atual ou de uma página específica.
+     *
+     * @param opts Opções de consulta
+     *
+     * @example
+     * ```ts
+     * // Todos os XPaths da página atual
+     * const catalog = await WebActions.getCurrentXPathCatalog()
+     *
+     * // Filtrar por texto
+     * const results = await WebActions.getCurrentXPathCatalog({ filter: 'catalogo de ofertas' })
+     *
+     * // Forçar refresh
+     * const fresh = await WebActions.getCurrentXPathCatalog({ refresh: true })
+     * ```
+     */
+    static getCurrentXPathCatalog(opts?: CatalogGetOptions): Promise<XPathCatalogItem[]>;
+    /**
+     * Obtém estrutura de XPaths da página atual (item 18 v2.7.44).
+     *
+     * Comportamento:
+     * - Sem `page`: usa URL atual da sessão.
+     * - Com `strictPage=true` (default): prioriza só XPaths da página atual.
+     * - Se a estrutura mudar, `refresh=true` recaptura automaticamente.
+     *
+     * @example
+     * ```ts
+     * const items = await WebActions.getCurrentPageStructure()
+     * const filtered = await WebActions.getCurrentPageStructure({ filter: 'login', refresh: true })
+     * ```
+     */
+    static getCurrentPageStructure(params?: {
+        page?: string;
+        filter?: string;
+        refresh?: boolean;
+        strictPage?: boolean;
+        maxItems?: number;
+    }): Promise<PageXPathItem[]>;
+    /**
+     * Detecta nome do arquivo de Page Object chamador a partir do stack trace.
+     * Retorna metadados de página para enriquecer requisições de recovery.
+     *
+     * Regra de inferência (item 20):
+     * - `PagePlaywrightLoginSalesforce` → pageName: `Login Salesforce`
+     */
+    static getCallerPageMetadata(): {
+        pageFileName?: string;
+        pageName?: string;
+        pageObjectName?: string;
+    };
+    /**
+     * Detecta o arquivo de Attributes* e nome de classe/método do chamador,
+     * usado para enriquecer auto-fix com contexto de propriedade (item 7/12).
+     */
+    static getCallerAttributesContext(): {
+        attributesFile?: string;
+        className?: string;
+        methodName?: string;
+    };
+    /**
+     * Tenta resolver o alvo recebido (texto/label/id/name) usando o catálogo
+     * da página atual. Se encontrar match com score >= 0.6, retorna o XPath.
+     * Caso contrário, retorna o alvo original inalterado.
+     *
+     * Usado internamente antes de cada ação para aproveitar o catálogo.
+     */
+    private static resolveXPathFromCatalog;
+    /**
+     * Captura DOM/pageStructure da página atual e envia ao backend para
+     * processamento remoto.  Usado em execuções Azure/CI onde o backend não
+     * tem acesso de rede à URL alvo.
+     *
+     * O backend processa, enriquece com hints Redis e retorna catálogo.
+     * O resultado alimenta automaticamente o cache do XPathCatalog.
+     *
+     * @param opts Opções extras (filtro, xpaths específicos, auth token)
+     * @returns Resposta do backend com catálogo enriquecido
+     *
+     * @example
+     * ```ts
+     * const result = await WebActions.pushCatalogToBackend({ filter: 'cliente' })
+     * // O catálogo já está no cache; próximos click/fill usam resolver interno
+     * ```
+     */
+    private static pushCatalogToBackend;
+}
+export {};