@appliqation/automation-sdk 2.1.0

package/src/utils/PayloadBuilder.js

@@ -0,0 +1,280 @@
+const { normalizeBrowser, normalizeOS, normalizeDevice } = require('./RunDataNormalizer');
+
+/**
+ * Payload Builder for Appliqation API requests
+ * Ensures consistent payload structure and field mapping
+ */
+class PayloadBuilder {
+  /**
+   * Build run creation payload
+   * @param {Object} config - SDK configuration
+   * @param {Object} options - Run options
+   * @returns {Object} API payload
+   */
+  static buildRunPayload(config, options) {
+    // Normalize browsers array
+    const browsers = options.browsers || ['Chrome'];
+    const normalizedBrowsers = browsers.map(browser => normalizeBrowser(browser));
+
+    const payload = {
+      project_key: Buffer.from(config.projectKey).toString('base64'),
+      environment: options.environment || 'Local',
+      browsers: normalizedBrowsers,
+      device: normalizeDevice(options.device || 'Desktop'),
+      os: normalizeOS(options.os || this.detectOS()),
+      title: options.title || `Automated Run - ${new Date().toISOString()}`
+    };
+
+    // Add either scenario_id or testset_id
+    if (options.scenarioId) {
+      payload.scenario_id = parseInt(options.scenarioId);
+      payload.type = options.type || 'scenario';
+    } else if (options.testSetId) {
+      payload.testset_id = parseInt(options.testSetId);
+      payload.type = 'testset';
+    }
+
+    return payload;
+  }
+
+  /**
+   * Build result submission payload
+   * @param {string} runId - Run ID
+   * @param {Object} result - Test result object
+   * @returns {Object} API payload
+   */
+  static buildResultPayload(runId, result) {
+    const browserName = result.browser || result.browserName || 'Unknown Browser';
+
+    return {
+      run_id: runId,
+      run_timestamp: result.runTimestamp || this.getCurrentTimestamp(),
+      uuid: result.uuid,
+      parent_uuid: result.parent_uuid || '',
+      nid: result.nid || this.extractNid(result.uuid),
+      browserName: normalizeBrowser(browserName),
+      status: this.normalizeStatus(result.status),
+      environment: result.environment || 'Local',
+      comment: result.comment || '',
+      timestamp: result.timestamp || this.getCurrentTimestamp()
+    };
+  }
+
+  /**
+   * Build orphan test entry payload
+   * @param {Object} test - Test object
+   * @param {string} reason - Reason for being orphaned
+   * @returns {Object} Formatted orphan test entry
+   */
+  static buildOrphanEntry(test, reason = 'No UUID annotation found') {
+    const browser = test.browser || 'unknown';
+
+    return {
+      test_title: test.title || test.name || test.test_title || 'Unknown Test',
+      test_file: test.file || test.location?.file || test.test_file || 'unknown',
+      browser: normalizeBrowser(browser),
+      timestamp: test.timestamp || this.getCurrentTimestamp(),
+      reason: reason,
+      framework: test.framework || 'unknown'
+    };
+  }
+
+  /**
+   * Build batch orphan tests payload
+   * @param {string} runId - Run ID
+   * @param {Array} orphanTests - Array of orphan test objects
+   * @returns {Object} API payload
+   */
+  static buildOrphanTestsPayload(runId, orphanTests) {
+    return {
+      run_id: runId,
+      orphan_tests: orphanTests.map(test => this.buildOrphanEntry(test))
+    };
+  }
+
+  /**
+   * Build browser update payload
+   * @param {string} runId - Run ID
+   * @param {string} browser - Browser name
+   * @returns {Object} API payload
+   */
+  static buildBrowserUpdatePayload(runId, browser) {
+    return {
+      run_id: runId,
+      operation: 'add_browser',
+      browser: normalizeBrowser(browser)
+    };
+  }
+
+  /**
+   * Normalize test status to Appliqation format
+   * @param {string} status - Test status
+   * @returns {string} Normalized status
+   */
+  static normalizeStatus(status) {
+    if (!status) return 'unknown';
+
+    const statusMap = {
+      // Standard statuses
+      'passed': 'passed',
+      'failed': 'failed',
+      'skipped': 'skipped',
+      'pending': 'pending',
+
+      // Playwright variants
+      'expected': 'passed',
+      'unexpected': 'failed',
+      'flaky': 'flaky',
+      'timedOut': 'failed',
+      'interrupted': 'skipped',
+
+      // Cypress variants
+      'pass': 'passed',
+      'fail': 'failed',
+
+      // Jest variants
+      'success': 'passed',
+      'error': 'failed',
+      'disabled': 'skipped',
+
+      // Generic variants
+      'ok': 'passed',
+      'success': 'passed',
+      'failure': 'failed',
+      'error': 'failed',
+      'skip': 'skipped',
+      'todo': 'pending'
+    };
+
+    const normalized = statusMap[status.toLowerCase()];
+    return normalized || status.toLowerCase();
+  }
+
+  /**
+   * Extract NID from UUID
+   * @param {string} uuid - UUID string
+   * @returns {number|null} NID or null if invalid
+   */
+  static extractNid(uuid) {
+    if (!uuid || typeof uuid !== 'string') return null;
+    const parts = uuid.split('-');
+    if (parts.length < 2) return null;
+    const nid = parseInt(parts[0], 10);
+    return isNaN(nid) ? null : nid;
+  }
+
+  /**
+   * Get current Unix timestamp in seconds
+   * @returns {number} Unix timestamp
+   */
+  static getCurrentTimestamp() {
+    return Math.floor(Date.now() / 1000);
+  }
+
+  /**
+   * Auto-detect operating system
+   * @returns {string} OS name (normalized)
+   */
+  static detectOS() {
+    const platform = process.platform;
+    const osMap = {
+      'win32': 'Windows',
+      'darwin': 'macOS',
+      'linux': 'Linux'
+    };
+    // Return normalized value directly
+    return normalizeOS(osMap[platform] || 'Unknown');
+  }
+
+  /**
+   * Validate required result fields
+   * @param {Object} result - Test result object
+   * @returns {Object} { valid: boolean, errors: string[] }
+   */
+  static validateResult(result) {
+    const errors = [];
+
+    if (!result.uuid) {
+      errors.push('UUID is required');
+    }
+
+    if (!result.status) {
+      errors.push('Status is required');
+    }
+
+    if (!result.browser && !result.browserName) {
+      errors.push('Browser name is required');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Validate run creation options
+   * @param {Object} options - Run options
+   * @returns {Object} { valid: boolean, errors: string[] }
+   */
+  static validateRunOptions(options) {
+    const errors = [];
+
+    if (!options.scenarioId && !options.testSetId) {
+      errors.push('Either scenarioId or testSetId is required');
+    }
+
+    if (options.scenarioId && options.testSetId) {
+      errors.push('Cannot specify both scenarioId and testSetId');
+    }
+
+    if (options.browsers && !Array.isArray(options.browsers)) {
+      errors.push('browsers must be an array');
+    }
+
+    if (options.browsers && options.browsers.length === 0) {
+      errors.push('browsers array cannot be empty');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Sanitize string for API submission
+   * @param {string} str - String to sanitize
+   * @param {number} maxLength - Maximum length
+   * @returns {string} Sanitized string
+   */
+  static sanitizeString(str, maxLength = 1000) {
+    if (!str || typeof str !== 'string') return '';
+
+    // Remove control characters and trim
+    let sanitized = str.replace(/[\x00-\x1F\x7F]/g, '').trim();
+
+    // Truncate if needed
+    if (sanitized.length > maxLength) {
+      sanitized = sanitized.substring(0, maxLength) + '...';
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Format error message for API
+   * @param {Error} error - Error object
+   * @returns {string} Formatted error message
+   */
+  static formatErrorMessage(error) {
+    if (!error) return 'Unknown error';
+
+    const message = error.message || error.toString();
+    const stack = error.stack ? `\n${error.stack}` : '';
+
+    return this.sanitizeString(message + stack, 5000);
+  }
+}
+
+module.exports = PayloadBuilder;

package/src/utils/RunDataNormalizer.js

@@ -0,0 +1,335 @@
+/**
+ * RunDataNormalizer - Validates and normalizes Browser, OS, and Device data
+ *
+ * This module provides centralized validation and normalization for test run metadata.
+ * It ensures consistent formatting across all reporters and frameworks.
+ *
+ * @module RunDataNormalizer
+ * @example
+ * const { normalizeBrowser, normalizeOS, normalizeDevice } = require('./RunDataNormalizer');
+ *
+ * normalizeBrowser('chrome 141.0.7811.4'); // Returns: "Chrome 141"
+ * normalizeBrowser('Mozilla/5.0 ... Chrome/141.0.0.0'); // Returns: "Chrome 141"
+ * normalizeOS('Windows 11'); // Returns: "Windows"
+ * normalizeDevice('mobile'); // Returns: "Mobile"
+ */
+
+/**
+ * Configuration object for supported browsers
+ * Add new browsers here to extend support
+ */
+const BROWSER_CONFIG = {
+  chrome: { name: 'Chrome', aliases: ['chromium', 'google chrome', 'chrome headless'] },
+  firefox: { name: 'Firefox', aliases: ['mozilla firefox', 'ff', 'firefox headless'] },
+  safari: { name: 'Safari', aliases: ['webkit', 'safari technology preview'] },
+  edge: { name: 'Edge', aliases: ['microsoft edge', 'msedge', 'edge chromium'] },
+  opera: { name: 'Opera', aliases: ['opera gx', 'opera mini'] },
+  brave: { name: 'Brave', aliases: ['brave browser'] },
+  ie: { name: 'Internet Explorer', aliases: ['msie', 'trident', 'internet explorer'] },
+  node: { name: 'Node.js', aliases: ['nodejs', 'node'] },
+  electron: { name: 'Electron', aliases: [] }
+};
+
+/**
+ * Configuration object for supported operating systems
+ * Maps various OS variants to generic families
+ */
+const OS_CONFIG = {
+  windows: {
+    name: 'Windows',
+    aliases: ['win', 'win32', 'win64', 'windows nt', 'windows 10', 'windows 11', 'windows 7', 'windows 8', 'windows server']
+  },
+  macos: {
+    name: 'macOS',
+    aliases: ['mac os', 'mac os x', 'osx', 'os x', 'darwin', 'mac', 'macosx', 'macos']
+  },
+  chromeos: {
+    name: 'ChromeOS',
+    aliases: ['chrome os', 'cros']
+  },
+  linux: {
+    name: 'Linux',
+    aliases: ['gnu/linux', 'linux gnu']
+  },
+  ubuntu: {
+    name: 'Ubuntu',
+    aliases: ['ubuntu linux']
+  },
+  unix: {
+    name: 'Unix',
+    aliases: []
+  },
+  android: {
+    name: 'Android',
+    aliases: []
+  },
+  ios: {
+    name: 'iOS',
+    aliases: ['iphone os', 'ipad os', 'ipados']
+  }
+};
+
+/**
+ * Configuration object for supported device types
+ */
+const DEVICE_CONFIG = {
+  desktop: { name: 'Desktop', aliases: ['pc', 'computer', 'laptop', 'workstation', 'server'] },
+  mobile: { name: 'Mobile', aliases: ['phone', 'smartphone', 'mobile device', 'cellphone'] },
+  tablet: { name: 'Tablet', aliases: ['ipad', 'tablet device'] }
+};
+
+/**
+ * Extracts major version from a version string or user agent
+ *
+ * @param {string} input - Version string or user agent
+ * @returns {string|null} - Major version number or null if not found
+ *
+ * @example
+ * extractMajorVersion('141.0.7811.4'); // Returns: "141"
+ * extractMajorVersion('Chrome/141.0.0.0'); // Returns: "141"
+ */
+function extractMajorVersion(input) {
+  if (!input) return null;
+
+  // Match version patterns: 141.0.7811.4, v141.0, 141
+  const versionMatch = input.match(/(\d+)(?:\.\d+)*/);
+  return versionMatch ? versionMatch[1] : null;
+}
+
+/**
+ * Normalizes browser name and extracts major version
+ *
+ * Supports:
+ * - Simple names: "chrome", "Chrome", "CHROME"
+ * - With versions: "Chrome 141", "chrome 141.0.7811.4"
+ * - User agents: "Mozilla/5.0 ... Chrome/141.0.0.0 ..."
+ * - Playwright projects: "chromium", "firefox", "webkit"
+ *
+ * @param {string} input - Browser name, version, or user agent
+ * @returns {string} - Normalized format: "BrowserName MajorVersion" or "BrowserName" or "Unknown Browser"
+ *
+ * @example
+ * normalizeBrowser('chrome'); // Returns: "Chrome"
+ * normalizeBrowser('Chrome 141'); // Returns: "Chrome 141"
+ * normalizeBrowser('chrome 141.0.7811.4'); // Returns: "Chrome 141"
+ * normalizeBrowser('chromium'); // Returns: "Chrome"
+ * normalizeBrowser('Mozilla/5.0 ... Chrome/141.0.0.0'); // Returns: "Chrome 141"
+ * normalizeBrowser('unknown'); // Returns: "Unknown Browser"
+ */
+function normalizeBrowser(input) {
+  if (!input || typeof input !== 'string') {
+    return 'Unknown Browser';
+  }
+
+  const inputLower = input.toLowerCase().trim();
+
+  // Try to match against known browsers
+  for (const [key, config] of Object.entries(BROWSER_CONFIG)) {
+    const allNames = [key, ...config.aliases];
+
+    for (const name of allNames) {
+      // Check if input contains the browser name
+      if (inputLower.includes(name)) {
+        // Try to extract version from various formats
+        let version = null;
+
+        // Pattern 1: "Chrome/141.0.0.0" (user agent)
+        const uaPattern = new RegExp(`${name.replace(/\s/g, '\\s*')}/([\\d.]+)`, 'i');
+        const uaMatch = input.match(uaPattern);
+        if (uaMatch) {
+          version = extractMajorVersion(uaMatch[1]);
+        }
+
+        // Pattern 2: "Chrome 141.0.7811.4" (space-separated)
+        if (!version) {
+          const spacePattern = new RegExp(`${name.replace(/\s/g, '\\s*')}\\s+([\\d.]+)`, 'i');
+          const spaceMatch = input.match(spacePattern);
+          if (spaceMatch) {
+            version = extractMajorVersion(spaceMatch[1]);
+          }
+        }
+
+        // Pattern 3: Just version numbers after browser name
+        if (!version) {
+          const afterBrowser = input.substring(input.toLowerCase().indexOf(name) + name.length);
+          version = extractMajorVersion(afterBrowser);
+        }
+
+        // Return normalized format
+        return version ? `${config.name} ${version}` : config.name;
+      }
+    }
+  }
+
+  // No match found
+  return 'Unknown Browser';
+}
+
+/**
+ * Normalizes operating system name to generic family
+ *
+ * Supports:
+ * - Generic names: "windows", "macos", "linux"
+ * - Specific versions: "Windows 11", "macOS Sonoma"
+ * - User agent formats: "Windows NT 10.0", "Mac OS X 10_15_7"
+ * - Platform values: "win32", "darwin", "linux"
+ *
+ * @param {string} input - OS name, version, or platform string
+ * @returns {string} - Generic OS family or "Unknown OS"
+ *
+ * @example
+ * normalizeOS('Windows 11'); // Returns: "Windows"
+ * normalizeOS('win32'); // Returns: "Windows"
+ * normalizeOS('macOS Sonoma'); // Returns: "macOS"
+ * normalizeOS('darwin'); // Returns: "macOS"
+ * normalizeOS('Ubuntu 22.04'); // Returns: "Ubuntu"
+ * normalizeOS('unknown'); // Returns: "Unknown OS"
+ */
+function normalizeOS(input) {
+  if (!input || typeof input !== 'string') {
+    return 'Unknown OS';
+  }
+
+  const inputLower = input.toLowerCase().trim();
+
+  // Try exact match first
+  for (const [key, config] of Object.entries(OS_CONFIG)) {
+    if (inputLower === key || config.aliases.some(alias => inputLower === alias)) {
+      return config.name;
+    }
+  }
+
+  // Try substring match with longer aliases first to avoid false matches
+  // (e.g., "darwin" shouldn't match "win" in "darwin")
+  const allAliases = [];
+  for (const [key, config] of Object.entries(OS_CONFIG)) {
+    const names = [key, ...config.aliases];
+    names.forEach(name => allAliases.push({ name, result: config.name }));
+  }
+
+  // Sort by length (longest first) to match more specific patterns first
+  allAliases.sort((a, b) => b.name.length - a.name.length);
+
+  // Try substring match
+  for (const alias of allAliases) {
+    if (inputLower.includes(alias.name)) {
+      return alias.result;
+    }
+  }
+
+  // No match found
+  return 'Unknown OS';
+}
+
+/**
+ * Normalizes device type to standard categories
+ *
+ * Supports:
+ * - Standard types: "desktop", "mobile", "tablet"
+ * - Aliases: "pc", "phone", "smartphone", "laptop"
+ * - Case-insensitive matching
+ *
+ * @param {string} input - Device type or description
+ * @returns {string} - Normalized device type: "Desktop", "Mobile", "Tablet", or "Desktop" (default)
+ *
+ * @example
+ * normalizeDevice('desktop'); // Returns: "Desktop"
+ * normalizeDevice('MOBILE'); // Returns: "Mobile"
+ * normalizeDevice('phone'); // Returns: "Mobile"
+ * normalizeDevice('pc'); // Returns: "Desktop"
+ * normalizeDevice('unknown'); // Returns: "Desktop" (fallback)
+ */
+function normalizeDevice(input) {
+  if (!input || typeof input !== 'string') {
+    return 'Desktop'; // Default fallback
+  }
+
+  const inputLower = input.toLowerCase().trim();
+
+  // Try to match against known device types
+  for (const [key, config] of Object.entries(DEVICE_CONFIG)) {
+    const allNames = [key, ...config.aliases];
+
+    for (const name of allNames) {
+      if (inputLower.includes(name)) {
+        return config.name;
+      }
+    }
+  }
+
+  // Default fallback
+  return 'Desktop';
+}
+
+/**
+ * Normalizes all run data fields at once
+ *
+ * @param {Object} data - Object containing browser, os, and/or device fields
+ * @param {string} [data.browser] - Browser name/version/user agent
+ * @param {string} [data.os] - OS name/version/platform
+ * @param {string} [data.device] - Device type
+ * @returns {Object} - Normalized data with same field names
+ *
+ * @example
+ * normalizeRunData({
+ *   browser: 'chrome 141.0.7811.4',
+ *   os: 'Windows 11',
+ *   device: 'desktop'
+ * });
+ * // Returns: { browser: 'Chrome 141', os: 'Windows', device: 'Desktop' }
+ */
+function normalizeRunData(data) {
+  const normalized = {};
+
+  if (data.browser !== undefined) {
+    normalized.browser = normalizeBrowser(data.browser);
+  }
+
+  if (data.os !== undefined) {
+    normalized.os = normalizeOS(data.os);
+  }
+
+  if (data.device !== undefined) {
+    normalized.device = normalizeDevice(data.device);
+  }
+
+  return normalized;
+}
+
+/**
+ * Gets list of all supported browsers
+ * @returns {Array<string>} - Array of browser names
+ */
+function getSupportedBrowsers() {
+  return Object.values(BROWSER_CONFIG).map(config => config.name);
+}
+
+/**
+ * Gets list of all supported operating systems
+ * @returns {Array<string>} - Array of OS names
+ */
+function getSupportedOS() {
+  return Object.values(OS_CONFIG).map(config => config.name);
+}
+
+/**
+ * Gets list of all supported device types
+ * @returns {Array<string>} - Array of device types
+ */
+function getSupportedDevices() {
+  return Object.values(DEVICE_CONFIG).map(config => config.name);
+}
+
+module.exports = {
+  normalizeBrowser,
+  normalizeOS,
+  normalizeDevice,
+  normalizeRunData,
+  getSupportedBrowsers,
+  getSupportedOS,
+  getSupportedDevices,
+  // Export configs for extensibility
+  BROWSER_CONFIG,
+  OS_CONFIG,
+  DEVICE_CONFIG
+};

package/src/utils/UuidValidator.js

@@ -0,0 +1,102 @@
+/**
+ * UUID Validator for Appliqation test case UUIDs
+ * Format: {nid}-{uuid-v4}
+ * Example: 124-d1f9559c-b978-43cc-9c76-fd539c717cb4
+ */
+class UuidValidator {
+  /**
+   * Validate UUID format
+   * @param {string} uuid - UUID to validate
+   * @returns {boolean} True if valid, false otherwise
+   */
+  static validate(uuid) {
+    if (!uuid || typeof uuid !== 'string') {
+      return false;
+    }
+
+    // Pattern: nid-uuid-v4
+    const pattern = /^\d+-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+    return pattern.test(uuid);
+  }
+
+  /**
+   * Extract NID (node ID) from UUID
+   * @param {string} uuid - UUID string
+   * @returns {number|null} NID or null if invalid
+   */
+  static extractNid(uuid) {
+    if (!this.validate(uuid)) {
+      return null;
+    }
+    const parts = uuid.split('-');
+    return parseInt(parts[0], 10);
+  }
+
+  /**
+   * Extract UUID portion (without NID)
+   * @param {string} uuid - Full UUID string
+   * @returns {string|null} UUID portion or null if invalid
+   */
+  static extractUuidPortion(uuid) {
+    if (!this.validate(uuid)) {
+      return null;
+    }
+    const parts = uuid.split('-');
+    return parts.slice(1).join('-');
+  }
+
+  /**
+   * Validate and extract components
+   * @param {string} uuid - UUID string
+   * @returns {Object} { valid, nid, uuid, error }
+   */
+  static validateAndExtract(uuid) {
+    if (!uuid) {
+      return {
+        valid: false,
+        nid: null,
+        uuid: null,
+        error: 'UUID is required'
+      };
+    }
+
+    if (typeof uuid !== 'string') {
+      return {
+        valid: false,
+        nid: null,
+        uuid: null,
+        error: 'UUID must be a string'
+      };
+    }
+
+    const isValid = this.validate(uuid);
+
+    if (!isValid) {
+      return {
+        valid: false,
+        nid: null,
+        uuid: null,
+        error: 'Invalid UUID format. Expected: {nid}-{uuid-v4}'
+      };
+    }
+
+    return {
+      valid: true,
+      nid: this.extractNid(uuid),
+      uuid: this.extractUuidPortion(uuid),
+      error: null
+    };
+  }
+
+  /**
+   * Create UUID from components
+   * @param {number} nid - Node ID
+   * @param {string} uuidPortion - UUID v4 string
+   * @returns {string} Combined UUID
+   */
+  static create(nid, uuidPortion) {
+    return `${nid}-${uuidPortion}`;
+  }
+}
+
+module.exports = UuidValidator;