@appliqation/automation-sdk 2.1.0

package/src/utils/errors.js

@@ -0,0 +1,217 @@
+/**
+ * Centralized Error Handling
+ * Standardized error classes and error handling utilities
+ */
+
+/**
+ * Base SDK Error class
+ */
+class AppliqationError extends Error {
+  constructor(message, code, details = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.details = details;
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      details: this.details
+    };
+  }
+}
+
+/**
+ * Configuration Error
+ * Thrown when SDK configuration is invalid
+ */
+class ConfigurationError extends AppliqationError {
+  constructor(message, details = {}) {
+    super(message, 'CONFIGURATION_ERROR', details);
+  }
+}
+
+/**
+ * Authentication Error
+ * Thrown when authentication fails
+ */
+class AuthenticationError extends AppliqationError {
+  constructor(message, details = {}) {
+    super(message, 'AUTHENTICATION_ERROR', details);
+  }
+}
+
+/**
+ * Network Error
+ * Thrown when network requests fail
+ */
+class NetworkError extends AppliqationError {
+  constructor(message, details = {}) {
+    super(message, 'NETWORK_ERROR', details);
+  }
+}
+
+/**
+ * Validation Error
+ * Thrown when data validation fails
+ */
+class ValidationError extends AppliqationError {
+  constructor(message, details = {}) {
+    super(message, 'VALIDATION_ERROR', details);
+  }
+}
+
+/**
+ * API Error
+ * Thrown when API returns an error response
+ */
+class ApiError extends AppliqationError {
+  constructor(message, statusCode, details = {}) {
+    super(message, 'API_ERROR', { ...details, statusCode });
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * Timeout Error
+ * Thrown when requests timeout
+ */
+class TimeoutError extends AppliqationError {
+  constructor(message, timeout, details = {}) {
+    super(message, 'TIMEOUT_ERROR', { ...details, timeout });
+    this.timeout = timeout;
+  }
+}
+
+/**
+ * Error Handler Utility
+ */
+class ErrorHandler {
+  /**
+   * Handle HTTP errors and convert to SDK errors
+   * @param {Error} error - Original error
+   * @param {string} context - Context where error occurred
+   * @returns {AppliqationError} Standardized error
+   */
+  static handleHttpError(error, context = 'HTTP request') {
+    // Timeout errors
+    if (error.code === 'ECONNABORTED' || error.message.includes('timeout')) {
+      return new TimeoutError(
+        `${context} timed out`,
+        error.config?.timeout,
+        { originalError: error.message }
+      );
+    }
+
+    // Network errors (no response)
+    if (!error.response) {
+      return new NetworkError(
+        `${context} failed: ${error.message}`,
+        {
+          code: error.code,
+          syscall: error.syscall,
+          originalError: error.message
+        }
+      );
+    }
+
+    // API errors (with response)
+    const { status, statusText, data } = error.response;
+
+    // Authentication errors
+    if (status === 401 || status === 403) {
+      return new AuthenticationError(
+        `Authentication failed: ${statusText}`,
+        {
+          status,
+          statusText,
+          response: data
+        }
+      );
+    }
+
+    // Validation errors
+    if (status === 400 || status === 422) {
+      return new ValidationError(
+        `Validation failed: ${data?.message || statusText}`,
+        {
+          status,
+          statusText,
+          response: data
+        }
+      );
+    }
+
+    // Generic API errors
+    return new ApiError(
+      `${context} failed: ${statusText}`,
+      status,
+      {
+        statusText,
+        response: data
+      }
+    );
+  }
+
+  /**
+   * Check if error is retryable
+   * @param {Error} error - Error to check
+   * @returns {boolean} True if error is retryable
+   */
+  static isRetryable(error) {
+    // Network errors are retryable
+    if (error instanceof NetworkError) {
+      return true;
+    }
+
+    // Timeout errors are retryable
+    if (error instanceof TimeoutError) {
+      return true;
+    }
+
+    // Certain API errors are retryable (5xx, 429, 408)
+    if (error instanceof ApiError) {
+      const { statusCode } = error;
+      return statusCode >= 500 || statusCode === 429 || statusCode === 408;
+    }
+
+    return false;
+  }
+
+  /**
+   * Format error for logging
+   * @param {Error} error - Error to format
+   * @returns {Object} Formatted error object
+   */
+  static formatForLogging(error) {
+    if (error instanceof AppliqationError) {
+      return {
+        name: error.name,
+        code: error.code,
+        message: error.message,
+        details: error.details
+      };
+    }
+
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack
+    };
+  }
+}
+
+module.exports = {
+  AppliqationError,
+  ConfigurationError,
+  AuthenticationError,
+  NetworkError,
+  ValidationError,
+  ApiError,
+  TimeoutError,
+  ErrorHandler
+};

package/src/utils/index.js

@@ -0,0 +1,17 @@
+/**
+ * Utilities export module
+ */
+
+const UuidValidator = require('./UuidValidator');
+const PayloadBuilder = require('./PayloadBuilder');
+const RunDataNormalizer = require('./RunDataNormalizer');
+const { mapAppqUuid } = require('./mapAppqUuid');
+const logger = require('./logger');
+
+module.exports = {
+  UuidValidator,
+  PayloadBuilder,
+  RunDataNormalizer,
+  mapAppqUuid,
+  logger
+};

package/src/utils/logger.js

@@ -0,0 +1,124 @@
+const LOG_LEVELS = {
+  ERROR: 0,
+  WARN: 1,
+  INFO: 2,
+  DEBUG: 3
+};
+
+// Sensitive data patterns to sanitize
+const SENSITIVE_PATTERNS = [
+  // API Keys
+  { pattern: /(appq_\w+_[a-f0-9]{32})/gi, replacement: 'appq_***_REDACTED' },
+  { pattern: /("apiKey"\s*:\s*")([^"]+)(")/gi, replacement: '$1***REDACTED***$3' },
+  { pattern: /("X-API-Key"\s*:\s*")([^"]+)(")/gi, replacement: '$1***REDACTED***$3' },
+
+  // JWT Tokens
+  { pattern: /(eyJ[A-Za-z0-9-_]+\.eyJ[A-Za-z0-9-_]+\.[A-Za-z0-9-_.+/=]+)/g, replacement: 'eyJ***REDACTED***' },
+  { pattern: /("token"\s*:\s*")([^"]+)(")/gi, replacement: '$1***REDACTED***$3' },
+  { pattern: /("jwt"\s*:\s*")([^"]+)(")/gi, replacement: '$1***REDACTED***$3' },
+
+  // Authorization Headers
+  { pattern: /("Authorization"\s*:\s*")(Bearer\s+)?([^"]+)(")/gi, replacement: '$1$2***REDACTED***$4' },
+  { pattern: /("authorization"\s*:\s*")(Bearer\s+)?([^"]+)(")/gi, replacement: '$1$2***REDACTED***$4' },
+
+  // Passwords
+  { pattern: /("password"\s*:\s*")([^"]+)(")/gi, replacement: '$1***REDACTED***$3' },
+  { pattern: /("pass"\s*:\s*")([^"]+)(")/gi, replacement: '$1***REDACTED***$3' },
+
+  // Session IDs
+  { pattern: /("sessionId"\s*:\s*")([^"]+)(")/gi, replacement: '$1***REDACTED***$3' },
+  { pattern: /("session"\s*:\s*")([^"]+)(")/gi, replacement: '$1***REDACTED***$3' }
+];
+
+class Logger {
+  constructor(level = 'INFO') {
+    this.level = LOG_LEVELS[level.toUpperCase()] || LOG_LEVELS.INFO;
+    this.enableConsole = process.env.NODE_ENV !== 'test';
+  }
+
+  /**
+   * Sanitize sensitive data from logs
+   * @param {any} data - Data to sanitize (string, object, or array)
+   * @returns {any} Sanitized data
+   */
+  sanitize(data) {
+    if (data === null || data === undefined) {
+      return data;
+    }
+
+    // Handle strings
+    if (typeof data === 'string') {
+      let sanitized = data;
+      SENSITIVE_PATTERNS.forEach(({ pattern, replacement }) => {
+        sanitized = sanitized.replace(pattern, replacement);
+      });
+      return sanitized;
+    }
+
+    // Handle objects and arrays by converting to JSON and back
+    if (typeof data === 'object') {
+      try {
+        let jsonString = JSON.stringify(data);
+        SENSITIVE_PATTERNS.forEach(({ pattern, replacement }) => {
+          jsonString = jsonString.replace(pattern, replacement);
+        });
+        return JSON.parse(jsonString);
+      } catch (error) {
+        // If JSON parsing fails, return original data
+        return data;
+      }
+    }
+
+    return data;
+  }
+
+  formatMessage(level, message, meta = {}) {
+    const timestamp = new Date().toISOString();
+    // Sanitize both message and meta
+    const sanitizedMessage = this.sanitize(message);
+    const sanitizedMeta = this.sanitize(meta);
+    const metaString = Object.keys(sanitizedMeta).length > 0 ? JSON.stringify(sanitizedMeta) : '';
+    return `[${timestamp}] [${level}] ${sanitizedMessage} ${metaString}`.trim();
+  }
+
+  error(message, meta = {}) {
+    if (this.level >= LOG_LEVELS.ERROR) {
+      const formatted = this.formatMessage('ERROR', message, meta);
+      if (this.enableConsole) console.error(formatted);
+    }
+  }
+
+  warn(message, meta = {}) {
+    if (this.level >= LOG_LEVELS.WARN) {
+      const formatted = this.formatMessage('WARN', message, meta);
+      if (this.enableConsole) console.warn(formatted);
+    }
+  }
+
+  info(message, meta = {}) {
+    if (this.level >= LOG_LEVELS.INFO) {
+      const formatted = this.formatMessage('INFO', message, meta);
+      if (this.enableConsole) console.log(formatted);
+    }
+  }
+
+  debug(message, meta = {}) {
+    if (this.level >= LOG_LEVELS.DEBUG) {
+      const formatted = this.formatMessage('DEBUG', message, meta);
+      if (this.enableConsole) console.debug(formatted);
+    }
+  }
+
+  setLevel(level) {
+    this.level = LOG_LEVELS[level.toUpperCase()] || LOG_LEVELS.INFO;
+  }
+
+  setConsoleEnabled(enabled) {
+    this.enableConsole = enabled;
+  }
+}
+
+// Export singleton instance
+const logger = new Logger(process.env.LOG_LEVEL || 'INFO');
+
+module.exports = logger;

package/src/utils/mapAppqUuid.js

@@ -0,0 +1,83 @@
+/**
+ * UUID Mapping Utility for Appliqation SDK
+ *
+ * This utility provides a simple, framework-agnostic way to map test UUIDs
+ * to framework-specific test metadata (currently supports Playwright).
+ */
+
+/**
+ * Adds Appliqation UUID annotation to a Playwright test.
+ *
+ * This helper function keeps UUID mapping centralized and makes tests more
+ * framework-agnostic by abstracting the annotation mechanism.
+ *
+ * @param {import('@playwright/test').TestInfo} testInfo - Playwright test info object
+ * @param {string} uuid - Appliqation test UUID in format: nid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ *
+ * @throws {Error} If testInfo is not provided or invalid
+ *
+ * @example
+ * // In your Playwright test file
+ * const { test } = require('@playwright/test');
+ * const { mapAppqUuid } = require('@appliqation/automation-sdk/utils');
+ *
+ * test('login functionality', async ({ page }, testInfo) => {
+ *   // Map this test to Appliqation test case
+ *   mapAppqUuid(testInfo, '1141-6d2827f3-1bc2-405c-95b4-6a09e8b64148');
+ *
+ *   await page.goto('/login');
+ *   // ... test implementation
+ * });
+ *
+ * @example
+ * // UUID format examples
+ * mapAppqUuid(testInfo, '1141-6d2827f3-1bc2-405c-95b4-6a09e8b64148');  // Standard format
+ * mapAppqUuid(testInfo, '1234-abc12345-6789-def0-1234-567890abcdef');  // Another valid UUID
+ */
+function mapAppqUuid(testInfo, uuid) {
+  // Validate testInfo parameter
+  if (!testInfo) {
+    throw new Error(
+      '[Appliqation SDK] mapAppqUuid requires a valid testInfo object. ' +
+      'Make sure to pass the testInfo parameter from your test function.'
+    );
+  }
+
+  // Validate testInfo has annotations array
+  if (!testInfo.annotations || !Array.isArray(testInfo.annotations)) {
+    throw new Error(
+      '[Appliqation SDK] testInfo.annotations is not available. ' +
+      'Ensure you are using a compatible version of Playwright (@playwright/test >= 1.30.0).'
+    );
+  }
+
+  // Validate UUID parameter
+  if (!uuid || typeof uuid !== 'string') {
+    console.warn(
+      '[Appliqation SDK] mapAppqUuid called without a valid UUID. ' +
+      'Test results may not be properly linked to Appliqation test cases.'
+    );
+    return;
+  }
+
+  // Trim whitespace from UUID
+  const trimmedUuid = uuid.trim();
+
+  // Basic UUID format validation (nid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
+  const uuidPattern = /^\d+-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(trimmedUuid)) {
+    console.warn(
+      `[Appliqation SDK] UUID format appears invalid: "${trimmedUuid}". ` +
+      'Expected format: nid-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (e.g., 1141-6d2827f3-1bc2-405c-95b4-6a09e8b64148)'
+    );
+  }
+
+  // Add UUID as Playwright annotation
+  // The SDK's UuidExtractor will read this annotation when reporting results
+  testInfo.annotations.push({
+    type: 'appliqation-uuid',
+    description: trimmedUuid
+  });
+}
+
+module.exports = { mapAppqUuid };

package/src/utils/validator.js

@@ -0,0 +1,157 @@
+/**
+ * Validates the payload for test result insertion
+ * @param {Object} payload - The test result payload
+ * @returns {Object} - Validation result with isValid flag and errors array
+ */
+function validatePayload(payload) {
+  const errors = [];
+  
+  if (!payload) {
+    errors.push('Payload is required');
+    return { isValid: false, errors };
+  }
+
+  // Required fields validation
+  if (!payload.run_id) {
+    errors.push('run_id is required');
+  } else if (typeof payload.run_id !== 'string') {
+    errors.push('run_id must be a string');
+  }
+
+  if (!payload.uuid) {
+    errors.push('uuid is required');
+  } else if (typeof payload.uuid !== 'string') {
+    errors.push('uuid must be a string');
+  } else if (!validateUuidFormat(payload.uuid)) {
+    errors.push('uuid must be in format: nid-uuid (e.g., "124-d1f9559c-b978-43cc-9c76-fd539c717cb4")');
+  }
+
+  if (!payload.status) {
+    errors.push('status is required');
+  } else if (typeof payload.status !== 'string') {
+    errors.push('status must be a string');
+  } else if (!validateStatus(payload.status)) {
+    errors.push('status must be one of: Pass, Fail, Skip, Pending');
+  }
+
+  // Optional fields validation
+  if (payload.browser && typeof payload.browser !== 'string') {
+    errors.push('browser must be a string');
+  }
+
+  if (payload.comment && typeof payload.comment !== 'string') {
+    errors.push('comment must be a string');
+  }
+
+  // Additional validation for run_id format (UUID)
+  if (payload.run_id && !validateRunIdFormat(payload.run_id)) {
+    errors.push('run_id must be a valid UUID format');
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Validates UUID format for run_id
+ * @param {string} runId - The run ID to validate
+ * @returns {boolean} - True if valid UUID format
+ */
+function validateRunIdFormat(runId) {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidRegex.test(runId);
+}
+
+/**
+ * Validates UUID format for test case UUID
+ * @param {string} uuid - The UUID to validate (format: nid-uuid)
+ * @returns {boolean} - True if valid format
+ */
+function validateUuidFormat(uuid) {
+  // Format should be: nid-uuid (e.g., "124-d1f9559c-b978-43cc-9c76-fd539c717cb4")
+  const parts = uuid.split('-');
+  if (parts.length < 6) return false; // nid + 5 UUID parts
+  
+  const nid = parts[0];
+  const uuidPart = parts.slice(1).join('-');
+  
+  // Validate nid is numeric
+  if (!/^\d+$/.test(nid)) return false;
+  
+  // Validate UUID part
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidRegex.test(uuidPart);
+}
+
+/**
+ * Validates test status
+ * @param {string} status - The test status
+ * @returns {boolean} - True if valid status
+ */
+function validateStatus(status) {
+  const validStatuses = ['Pass', 'Fail', 'Skip', 'Pending', 'pass', 'fail', 'skip', 'pending'];
+  return validStatuses.includes(status);
+}
+
+/**
+ * Sanitizes and normalizes payload data
+ * @param {Object} payload - The payload to sanitize
+ * @returns {Object} - Sanitized payload
+ */
+function sanitizePayload(payload) {
+  const sanitized = { ...payload };
+  
+  // Normalize status to proper case
+  if (sanitized.status) {
+    sanitized.status = sanitized.status.toLowerCase();
+    sanitized.status = sanitized.status.charAt(0).toUpperCase() + sanitized.status.slice(1);
+  }
+  
+  // Trim string fields
+  if (sanitized.browser) {
+    sanitized.browser = sanitized.browser.trim();
+  }
+  
+  if (sanitized.comment) {
+    sanitized.comment = sanitized.comment.trim();
+  }
+  
+  if (sanitized.run_id) {
+    sanitized.run_id = sanitized.run_id.trim();
+  }
+  
+  if (sanitized.uuid) {
+    sanitized.uuid = sanitized.uuid.trim();
+  }
+  
+  return sanitized;
+}
+
+/**
+ * Creates a payload from test framework data
+ * @param {Object} testData - Test data from framework
+ * @param {Object} config - Configuration options
+ * @returns {Object} - Formatted payload
+ */
+function createPayload(testData, config) {
+  const payload = {
+    run_id: testData.run_id || config.run_id,
+    uuid: testData.uuid || config.uuid,
+    browser: testData.browser || config.browser || 'Unknown',
+    status: testData.status || 'Fail',
+    comment: testData.comment || testData.error || ''
+  };
+  
+  return sanitizePayload(payload);
+}
+
+module.exports = {
+  validatePayload,
+  validateRunIdFormat,
+  validateUuidFormat,
+  validateStatus,
+  sanitizePayload,
+  createPayload
+};