@silasfmartins/testhub 1.0.0

package/dist/src/functions/errors/ConfigurationError.js

@@ -0,0 +1,48 @@
+/**
+ * ConfigurationError: Erros relacionados à configuração do framework
+ */
+import { BaseError } from './BaseError.js';
+export class ConfigurationError extends BaseError {
+    constructor(code, message, userMessage, originalError, context) {
+        const details = {
+            code,
+            message,
+            userMessage,
+            category: 'configuration',
+            severity: 'medium',
+            recoverable: true,
+            suggestions: [
+                'Verifique os arquivos de configuração',
+                'Consulte a documentação de configuração',
+                'Use os valores padrão se disponíveis',
+            ],
+            documentation: 'https://docs.autocore.rbqa/configuration',
+        };
+        super(details, originalError, context);
+    }
+    static missingConfigFile(filePath, context) {
+        return new ConfigurationError('CFG_MISSING_CONFIG_FILE', `Configuration file not found: ${filePath}`, `Arquivo de configuração não encontrado: ${filePath}`, undefined, { ...context, metadata: { filePath } });
+    }
+    static invalidConfigFormat(filePath, error, context) {
+        return new ConfigurationError('CFG_INVALID_CONFIG_FORMAT', `Invalid configuration format in ${filePath}: ${error.message}`, `Formato de configuração inválido em ${filePath}.`, error, { ...context, metadata: { filePath } });
+    }
+    static missingEnvironmentVariable(varName, context) {
+        return new ConfigurationError('CFG_MISSING_ENV_VAR', `Missing required environment variable: ${varName}`, `Variável de ambiente obrigatória não definida: ${varName}`, undefined, { ...context, metadata: { varName } });
+    }
+    static invalidEnvironmentValue(varName, expectedFormat, context) {
+        return new ConfigurationError('CFG_INVALID_ENV_VALUE', `Invalid value for environment variable ${varName}, expected: ${expectedFormat}`, `Valor inválido para variável de ambiente ${varName}. Esperado: ${expectedFormat}`, undefined, { ...context, metadata: { varName, expectedFormat } });
+    }
+    static conflictingConfiguration(config1, config2, context) {
+        return new ConfigurationError('CFG_CONFLICTING_CONFIG', `Conflicting configuration between ${config1} and ${config2}`, `Configurações conflitantes entre ${config1} e ${config2}.`, undefined, { ...context, metadata: { config1, config2 } });
+    }
+    static unsupportedBrowserConfig(browser, context) {
+        return new ConfigurationError('CFG_UNSUPPORTED_BROWSER', `Unsupported browser configuration: ${browser}`, `Configuração de navegador não suportada: ${browser}`, undefined, { ...context, metadata: { browser } });
+    }
+    static invalidTestConfiguration(configKey, reason, context) {
+        return new ConfigurationError('CFG_INVALID_TEST_CONFIG', `Invalid test configuration for ${configKey}: ${reason}`, `Configuração de teste inválida para ${configKey}: ${reason}`, undefined, { ...context, metadata: { configKey, reason } });
+    }
+    static missingDependency(dependency, context) {
+        return new ConfigurationError('CFG_MISSING_DEPENDENCY', `Missing required dependency: ${dependency}`, `Dependência obrigatória não encontrada: ${dependency}`, undefined, { ...context, metadata: { dependency } });
+    }
+}
+export default ConfigurationError;

package/dist/src/functions/errors/ErrorCatalog.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Catálogo centralizado de erros do framework AutoCore.
+ *
+ * Cada erro tem um código único, uma mensagem template e um nível de severidade.
+ * Isso padroniza mensagens de erro em todo o codebase.
+ *
+ * @module errors/ErrorCatalog
+ */
+export type ErrorSeverity = 'critical' | 'error' | 'warning' | 'info';
+export interface ErrorEntry {
+    code: string;
+    message: string;
+    severity: ErrorSeverity;
+    hint?: string;
+}
+/**
+ * Códigos de erro do framework.
+ * Formato: `AC-{AREA}-{NUMERO}`
+ *   - AREA: WEB, MOB, API, CFG, SEC, REC, INT
+ *   - NUMERO: 3 dígitos
+ */
+export declare const ErrorCatalog: {
+    readonly 'AC-WEB-001': {
+        readonly code: "AC-WEB-001";
+        readonly message: "Elemento não encontrado: {selector}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Verifique se o XPath/CSS está correto e se a página carregou completamente.";
+    };
+    readonly 'AC-WEB-002': {
+        readonly code: "AC-WEB-002";
+        readonly message: "Timeout ao aguardar elemento: {selector} ({timeout}ms)";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Aumente o timeout ou verifique se o elemento é renderizado condicionalmente.";
+    };
+    readonly 'AC-WEB-003': {
+        readonly code: "AC-WEB-003";
+        readonly message: "Múltiplos elementos encontrados para: {selector}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Use um seletor mais específico ou índice para selecionar o elemento correto.";
+    };
+    readonly 'AC-WEB-004': {
+        readonly code: "AC-WEB-004";
+        readonly message: "Navegação falhou para URL: {url}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Verifique se a URL está acessível e se não há bloqueio de rede/firewall.";
+    };
+    readonly 'AC-WEB-005': {
+        readonly code: "AC-WEB-005";
+        readonly message: "Frame não encontrado: {selector}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Verifique se o iframe existe e se o seletor aponta para o frame correto.";
+    };
+    readonly 'AC-MOB-001': {
+        readonly code: "AC-MOB-001";
+        readonly message: "Falha na conexão com o dispositivo: {device}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Verifique se o Appium está rodando e o dispositivo/emulador está conectado.";
+    };
+    readonly 'AC-MOB-002': {
+        readonly code: "AC-MOB-002";
+        readonly message: "App não encontrado: {appPath}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Verifique o caminho do APK/IPA e se o arquivo existe.";
+    };
+    readonly 'AC-API-001': {
+        readonly code: "AC-API-001";
+        readonly message: "URL inválida para requisição: {url}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "A URL deve começar com http:// ou https:// e ser bem formada.";
+    };
+    readonly 'AC-API-002': {
+        readonly code: "AC-API-002";
+        readonly message: "Timeout na requisição API: {url} ({timeout}ms)";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Aumente o timeout ou verifique a saúde do serviço alvo.";
+    };
+    readonly 'AC-API-003': {
+        readonly code: "AC-API-003";
+        readonly message: "Resposta inesperada: HTTP {status} de {url}";
+        readonly severity: ErrorSeverity;
+    };
+    readonly 'AC-CFG-001': {
+        readonly code: "AC-CFG-001";
+        readonly message: "Variável de ambiente obrigatória ausente: {variable}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Defina a variável no .env ou nas configurações do sistema.";
+    };
+    readonly 'AC-CFG-002': {
+        readonly code: "AC-CFG-002";
+        readonly message: "Arquivo de configuração não encontrado: {path}";
+        readonly severity: ErrorSeverity;
+    };
+    readonly 'AC-SEC-001': {
+        readonly code: "AC-SEC-001";
+        readonly message: "Certificado SSL inválido ou expirado";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Configure HUB_IGNORE_SSL=true para ambientes de teste ou atualize o certificado.";
+    };
+    readonly 'AC-SEC-002': {
+        readonly code: "AC-SEC-002";
+        readonly message: "Dados sensíveis detectados no output — mascarando automaticamente";
+        readonly severity: ErrorSeverity;
+    };
+    readonly 'AC-REC-001': {
+        readonly code: "AC-REC-001";
+        readonly message: "Recovery bem-sucedido: {selector} → {newSelector} (tentativa {attempt})";
+        readonly severity: ErrorSeverity;
+    };
+    readonly 'AC-REC-002': {
+        readonly code: "AC-REC-002";
+        readonly message: "Recovery falhou após {attempts} tentativas para: {selector}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "O elemento pode ter sido removido ou a página mudou significativamente.";
+    };
+    readonly 'AC-REC-003': {
+        readonly code: "AC-REC-003";
+        readonly message: "Serviço de recovery indisponível: {reason}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Verifique a conectividade com o backend e HUB_BACKEND_URL.";
+    };
+    readonly 'AC-INT-001': {
+        readonly code: "AC-INT-001";
+        readonly message: "Falha na conexão com o backend: {url}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Verifique HUB_BACKEND_URL e conectividade de rede.";
+    };
+    readonly 'AC-INT-002': {
+        readonly code: "AC-INT-002";
+        readonly message: "Teams flush falhou: {reason}";
+        readonly severity: ErrorSeverity;
+        readonly hint: "Verifique webhook URL, SSL corporativo e HUB_TEAMS_FLUSH_IGNORE_SSL.";
+    };
+};
+export type ErrorCode = keyof typeof ErrorCatalog;
+/**
+ * Formata uma mensagem de erro do catálogo com parâmetros.
+ *
+ * @example
+ * ```ts
+ * formatError('AC-WEB-001', { selector: '//button[@id="submit"]' })
+ * // → '[AC-WEB-001] Elemento não encontrado: //button[@id="submit"]'
+ * ```
+ */
+export declare function formatError(code: ErrorCode, params?: Record<string, string | number>): string;
+/**
+ * Retorna a hint associada a um código de erro (se existir).
+ */
+export declare function getErrorHint(code: ErrorCode): string | undefined;

package/dist/src/functions/errors/ErrorCatalog.js

@@ -0,0 +1,157 @@
+/**
+ * Catálogo centralizado de erros do framework AutoCore.
+ *
+ * Cada erro tem um código único, uma mensagem template e um nível de severidade.
+ * Isso padroniza mensagens de erro em todo o codebase.
+ *
+ * @module errors/ErrorCatalog
+ */
+/**
+ * Códigos de erro do framework.
+ * Formato: `AC-{AREA}-{NUMERO}`
+ *   - AREA: WEB, MOB, API, CFG, SEC, REC, INT
+ *   - NUMERO: 3 dígitos
+ */
+export const ErrorCatalog = {
+    // ── Web/Playwright ─────────────────────────────────────────
+    'AC-WEB-001': {
+        code: 'AC-WEB-001',
+        message: 'Elemento não encontrado: {selector}',
+        severity: 'error',
+        hint: 'Verifique se o XPath/CSS está correto e se a página carregou completamente.',
+    },
+    'AC-WEB-002': {
+        code: 'AC-WEB-002',
+        message: 'Timeout ao aguardar elemento: {selector} ({timeout}ms)',
+        severity: 'error',
+        hint: 'Aumente o timeout ou verifique se o elemento é renderizado condicionalmente.',
+    },
+    'AC-WEB-003': {
+        code: 'AC-WEB-003',
+        message: 'Múltiplos elementos encontrados para: {selector}',
+        severity: 'warning',
+        hint: 'Use um seletor mais específico ou índice para selecionar o elemento correto.',
+    },
+    'AC-WEB-004': {
+        code: 'AC-WEB-004',
+        message: 'Navegação falhou para URL: {url}',
+        severity: 'error',
+        hint: 'Verifique se a URL está acessível e se não há bloqueio de rede/firewall.',
+    },
+    'AC-WEB-005': {
+        code: 'AC-WEB-005',
+        message: 'Frame não encontrado: {selector}',
+        severity: 'error',
+        hint: 'Verifique se o iframe existe e se o seletor aponta para o frame correto.',
+    },
+    // ── Mobile ─────────────────────────────────────────────────
+    'AC-MOB-001': {
+        code: 'AC-MOB-001',
+        message: 'Falha na conexão com o dispositivo: {device}',
+        severity: 'critical',
+        hint: 'Verifique se o Appium está rodando e o dispositivo/emulador está conectado.',
+    },
+    'AC-MOB-002': {
+        code: 'AC-MOB-002',
+        message: 'App não encontrado: {appPath}',
+        severity: 'error',
+        hint: 'Verifique o caminho do APK/IPA e se o arquivo existe.',
+    },
+    // ── API ────────────────────────────────────────────────────
+    'AC-API-001': {
+        code: 'AC-API-001',
+        message: 'URL inválida para requisição: {url}',
+        severity: 'error',
+        hint: 'A URL deve começar com http:// ou https:// e ser bem formada.',
+    },
+    'AC-API-002': {
+        code: 'AC-API-002',
+        message: 'Timeout na requisição API: {url} ({timeout}ms)',
+        severity: 'error',
+        hint: 'Aumente o timeout ou verifique a saúde do serviço alvo.',
+    },
+    'AC-API-003': {
+        code: 'AC-API-003',
+        message: 'Resposta inesperada: HTTP {status} de {url}',
+        severity: 'warning',
+    },
+    // ── Configuração ────────────────────────────────────────────
+    'AC-CFG-001': {
+        code: 'AC-CFG-001',
+        message: 'Variável de ambiente obrigatória ausente: {variable}',
+        severity: 'critical',
+        hint: 'Defina a variável no .env ou nas configurações do sistema.',
+    },
+    'AC-CFG-002': {
+        code: 'AC-CFG-002',
+        message: 'Arquivo de configuração não encontrado: {path}',
+        severity: 'error',
+    },
+    // ── Segurança ───────────────────────────────────────────────
+    'AC-SEC-001': {
+        code: 'AC-SEC-001',
+        message: 'Certificado SSL inválido ou expirado',
+        severity: 'warning',
+        hint: 'Configure HUB_IGNORE_SSL=true para ambientes de teste ou atualize o certificado.',
+    },
+    'AC-SEC-002': {
+        code: 'AC-SEC-002',
+        message: 'Dados sensíveis detectados no output — mascarando automaticamente',
+        severity: 'warning',
+    },
+    // ── Recovery ────────────────────────────────────────────────
+    'AC-REC-001': {
+        code: 'AC-REC-001',
+        message: 'Recovery bem-sucedido: {selector} → {newSelector} (tentativa {attempt})',
+        severity: 'info',
+    },
+    'AC-REC-002': {
+        code: 'AC-REC-002',
+        message: 'Recovery falhou após {attempts} tentativas para: {selector}',
+        severity: 'error',
+        hint: 'O elemento pode ter sido removido ou a página mudou significativamente.',
+    },
+    'AC-REC-003': {
+        code: 'AC-REC-003',
+        message: 'Serviço de recovery indisponível: {reason}',
+        severity: 'warning',
+        hint: 'Verifique a conectividade com o backend e HUB_BACKEND_URL.',
+    },
+    // ── Integração ──────────────────────────────────────────────
+    'AC-INT-001': {
+        code: 'AC-INT-001',
+        message: 'Falha na conexão com o backend: {url}',
+        severity: 'warning',
+        hint: 'Verifique HUB_BACKEND_URL e conectividade de rede.',
+    },
+    'AC-INT-002': {
+        code: 'AC-INT-002',
+        message: 'Teams flush falhou: {reason}',
+        severity: 'warning',
+        hint: 'Verifique webhook URL, SSL corporativo e HUB_TEAMS_FLUSH_IGNORE_SSL.',
+    },
+};
+/**
+ * Formata uma mensagem de erro do catálogo com parâmetros.
+ *
+ * @example
+ * ```ts
+ * formatError('AC-WEB-001', { selector: '//button[@id="submit"]' })
+ * // → '[AC-WEB-001] Elemento não encontrado: //button[@id="submit"]'
+ * ```
+ */
+export function formatError(code, params = {}) {
+    const entry = ErrorCatalog[code];
+    let msg = entry.message;
+    for (const [key, value] of Object.entries(params)) {
+        msg = msg.replace(`{${key}}`, String(value));
+    }
+    return `[${code}] ${msg}`;
+}
+/**
+ * Retorna a hint associada a um código de erro (se existir).
+ */
+export function getErrorHint(code) {
+    const entry = ErrorCatalog[code];
+    return 'hint' in entry ? entry.hint : undefined;
+}

package/dist/src/functions/errors/GlobalErrorHandler.d.ts

@@ -0,0 +1,101 @@
+/**
+ * GlobalErrorHandler: Sistema global de captura e tratamento de erros
+ * Gerencia erros não capturados e fornece logging e observabilidade
+ */
+import { BaseError } from './BaseError.js';
+export interface ErrorHandlerConfig {
+    enableConsoleLogging: boolean;
+    enableFileLogging: boolean;
+    logFilePath?: string;
+    enableObservability: boolean;
+    observabilityEndpoint?: string;
+    maxErrorsInMemory: number;
+    enableStackTrace: boolean;
+    enableUserFriendlyMessages: boolean;
+}
+export interface ErrorMetrics {
+    totalErrors: number;
+    errorsByCategory: Record<string, number>;
+    errorsBySeverity: Record<string, number>;
+    recentErrors: BaseError[];
+    startTime: number;
+}
+export declare class GlobalErrorHandler {
+    private static instance;
+    private config;
+    private errors;
+    private metrics;
+    private originalConsoleError;
+    private originalProcessListeners;
+    private constructor();
+    /**
+     * Obtém instância singleton do GlobalErrorHandler
+     */
+    static getInstance(config?: Partial<ErrorHandlerConfig>): GlobalErrorHandler;
+    /**
+     * Configura handlers globais para captura de erros
+     */
+    private setupGlobalHandlers;
+    /**
+     * Manuseia erro principal do sistema
+     */
+    handleError(error: Error | BaseError, context?: Record<string, unknown>): void;
+    /**
+     * Manuseia erros não capturados
+     */
+    private handleUncaughtError;
+    /**
+     * Manuseia rejeições não tratadas
+     */
+    private handleUnhandledRejection;
+    /**
+     * Manuseia logs de erro do console
+     */
+    private handleConsoleError;
+    /**
+     * Converte erro genérico para BaseError
+     */
+    private convertToBaseError;
+    /**
+     * Registra erro nos logs
+     */
+    private logError;
+    /**
+     * Escreve erro em arquivo de log
+     */
+    private writeToLogFile;
+    /**
+     * Atualiza métricas de erro
+     */
+    private updateMetrics;
+    /**
+     * Armazena erro na memória
+     */
+    private storeError;
+    /**
+     * Envia erro para sistema de observabilidade
+     */
+    private sendToObservability;
+    /**
+     * Obtém métricas atuais
+     */
+    getMetrics(): ErrorMetrics;
+    /**
+     * Obtém erros recentes
+     */
+    getRecentErrors(limit?: number): BaseError[];
+    /**
+     * Gera relatório de status
+     */
+    generateStatusReport(): string;
+    /**
+     * Limpa erros armazenados
+     */
+    clearErrors(): void;
+    /**
+     * Desativa handlers globais
+     */
+    dispose(): void;
+}
+export declare const globalErrorHandler: GlobalErrorHandler;
+export default GlobalErrorHandler;