@appliqation/automation-sdk 2.1.0

package/src/AppliqationClient.js

@@ -0,0 +1,562 @@
+const HttpClient = require('./core/HttpClient');
+const AuthManager = require('./core/AuthManager');
+const RunMatrixService = require('./services/RunMatrixService');
+const ResultService = require('./services/ResultService');
+const OrphanTestService = require('./services/OrphanTestService');
+const UuidValidator = require('./utils/UuidValidator');
+const PayloadBuilder = require('./utils/PayloadBuilder');
+const logger = require('./utils/logger');
+
+/**
+ * Main Appliqation Automation SDK Client
+ *
+ * @example
+ * // Initialize with API key (recommended for automation)
+ * const client = new AppliqationClient({
+ *   baseUrl: 'https://your-instance.appliqation.com',
+ *   apiKey: 'appq_live_xxxxxxxxxxxxx',
+ *   projectKey: 'your-project-key'
+ * });
+ *
+ * // Create run matrix
+ * const run = await client.createRun({
+ *   scenarioId: 123,
+ *   environment: 'Production',
+ *   browsers: ['Chrome', 'Firefox'],
+ *   device: 'Desktop',
+ *   os: 'Windows 11'
+ * });
+ *
+ * // Submit test results
+ * await client.submitResult(run.runId, {
+ *   uuid: '124-d1f9559c-b978-43cc-9c76-fd539c717cb4',
+ *   status: 'passed',
+ *   browser: 'Chrome'
+ * });
+ */
+class AppliqationClient {
+  /**
+   * Create Appliqation client
+   * @param {Object} config - Client configuration
+   * @param {string} config.baseUrl - Appliqation instance URL
+   * @param {string} config.apiKey - API key for authentication (recommended)
+   * @param {string} config.projectKey - Project key (base64 encoded or plain)
+   * @param {string} [config.username] - Username for CSRF auth (legacy)
+   * @param {string} [config.password] - Password for CSRF auth (legacy)
+   * @param {string} [config.title] - Custom run title (or use APPLIQATION_RUN_TITLE env var)
+   * @param {Object} [config.options] - Additional options
+   * @param {number} [config.options.timeout=30000] - Request timeout in ms
+   * @param {number} [config.options.retries=3] - Number of retry attempts
+   * @param {boolean} [config.options.logOrphans=true] - Log orphan tests to backend
+   * @param {string} [config.options.logLevel='info'] - Logging level
+   */
+  constructor(config) {
+    // Validate configuration
+    this.validateConfig(config);
+
+    // Determine SSL enforcement based on environment
+    const isProduction = this._isProductionEnvironment();
+    let rejectUnauthorized = true; // Default to secure
+
+    if (config.rejectUnauthorized !== undefined) {
+      // User explicitly set rejectUnauthorized
+      if (isProduction && config.rejectUnauthorized === false) {
+        // WARNING: User is trying to disable SSL in production
+        logger.warn('SSL certificate verification is disabled in production environment!', {
+          environment: process.env.NODE_ENV,
+          ci: process.env.CI,
+          warning: 'This is a security risk. SSL verification should be enabled in production.'
+        });
+      }
+      rejectUnauthorized = config.rejectUnauthorized;
+    } else if (isProduction) {
+      // Production environment - force SSL verification
+      rejectUnauthorized = true;
+      logger.info('SSL certificate verification enforced for production environment');
+    } else {
+      // Development environment - default to secure but can be overridden
+      rejectUnauthorized = true;
+    }
+
+    // Store configuration
+    this.config = {
+      baseUrl: config.baseUrl.replace(/\/$/, ''), // Remove trailing slash
+      apiKey: config.apiKey,
+      projectKey: config.projectKey,
+      username: config.username,
+      password: config.password,
+      runTitle: config.runTitle || config.title || process.env.APPLIQATION_RUN_TITLE || null,
+      rejectUnauthorized: rejectUnauthorized,
+      options: {
+        timeout: config.options?.timeout || 30000,
+        retries: config.options?.retries || 3,
+        logOrphans: config.options?.logOrphans !== false,
+        logLevel: config.options?.logLevel || 'info'
+      }
+    };
+
+    // Configure logger
+    logger.setLevel(this.config.options.logLevel);
+
+    // Initialize core components
+    this.auth = new AuthManager(this.config);
+    this.http = new HttpClient(this.config, this.auth);
+
+    // Initialize services
+    this.runMatrix = new RunMatrixService(this.http, this.config);
+    this.results = new ResultService(this.http);
+    this.orphans = new OrphanTestService(this.http);
+
+    // Track current run context
+    this.currentRun = null;
+
+    logger.info('Appliqation client initialized', {
+      baseUrl: this.config.baseUrl,
+      authMode: this.config.apiKey ? 'api_key' : 'csrf'
+    });
+  }
+
+  /**
+   * Create a new test run matrix
+   * @param {Object} options - Run configuration
+   * @param {number} options.scenarioId - Scenario node ID
+   * @param {number} options.testSetId - Test Set node ID (alternative to scenarioId)
+   * @param {string} options.type - 'scenario' or 'testset'
+   * @param {string} [options.environment='Local'] - Environment name
+   * @param {string[]} [options.browsers=['Chrome']] - Array of browser names
+   * @param {string} [options.device] - Device type (Desktop, Mobile, Tablet)
+   * @param {string} [options.os] - Operating system
+   * @param {string} [options.title] - Custom run title
+   * @returns {Promise<Object>} { runId, token, timestamp, metadata }
+   */
+  async createRun(options) {
+    try {
+      logger.info('Creating run matrix...', options);
+
+      const run = await this.runMatrix.create(options);
+
+      // Store current run context
+      this.currentRun = run;
+
+      // Store run configuration in AuthManager for JWT refresh capability
+      if (this.auth && this.config.apiKey) {
+        this.auth.setRunConfig({
+          projectKey: this.config.projectKey,
+          scenarioId: options.scenarioId || 0,
+          testSetId: options.testSetId,
+          environment: options.environment || 'Local',
+          browsers: options.browsers || ['Chrome'],
+          device: options.device,
+          os: options.os,
+          title: options.title || this.config.runTitle
+        });
+        logger.debug('Run configuration stored in AuthManager for JWT refresh');
+      }
+
+      logger.info('Run matrix created successfully', {
+        runId: run.runId,
+        timestamp: run.timestamp
+      });
+
+      return run;
+    } catch (error) {
+      logger.error('Failed to create run matrix', {
+        error: error.message,
+        options
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Create multiple runs for device/OS matrix testing
+   * @param {Array} configs - Array of run configurations
+   * @returns {Promise<Object>} { runs, errors, summary }
+   */
+  async createMultipleRuns(configs) {
+    try {
+      logger.info(`Creating ${configs.length} run matrices...`);
+
+      const result = await this.runMatrix.createMultiple(configs);
+
+      logger.info('Multiple runs created', {
+        total: result.summary.total,
+        success: result.summary.success,
+        failed: result.summary.failed
+      });
+
+      return result;
+    } catch (error) {
+      logger.error('Failed to create multiple runs', {
+        error: error.message
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Submit a single test result
+   * @param {string} runId - Run ID
+   * @param {Object} result - Test result
+   * @param {string} result.uuid - Test case UUID
+   * @param {string} result.status - Test status (passed, failed, skipped)
+   * @param {string} result.browser - Browser name
+   * @param {string} [result.parent_uuid] - Parent test case UUID
+   * @param {string} [result.comment] - Additional comments
+   * @param {string} [result.environment] - Environment name
+   * @returns {Promise<Object>} Response from server
+   */
+  async submitResult(runId, result) {
+    try {
+      // Validate UUID
+      const validation = UuidValidator.validateAndExtract(result.uuid);
+      if (!validation.valid) {
+        throw new Error(`Invalid UUID: ${validation.error}`);
+      }
+
+      // Validate result fields
+      const resultValidation = PayloadBuilder.validateResult(result);
+      if (!resultValidation.valid) {
+        throw new Error(`Invalid result: ${resultValidation.errors.join(', ')}`);
+      }
+
+      logger.debug('Submitting test result', {
+        runId,
+        uuid: result.uuid,
+        status: result.status,
+        browser: result.browser
+      });
+
+      const response = await this.results.submitSingle(runId, result);
+
+      return response;
+    } catch (error) {
+      logger.error('Failed to submit result', {
+        error: error.message,
+        runId,
+        uuid: result.uuid
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Submit batch of test results with smart grouping
+   * @param {Array} results - Array of test results
+   * @param {Object} [options] - Batch options
+   * @param {number} [options.batchSize=50] - Results per batch
+   * @param {Function} [options.onProgress] - Progress callback
+   * @param {boolean} [options.retryFailures=true] - Retry failed submissions
+   * @returns {Promise<Object>} { success, failed, total }
+   */
+  async submitBatch(results, options = {}) {
+    try {
+      logger.info(`Submitting batch of ${results.length} results...`);
+
+      // Validate all results first
+      const validResults = [];
+      const invalidResults = [];
+
+      for (const result of results) {
+        const validation = UuidValidator.validateAndExtract(result.uuid);
+        if (validation.valid) {
+          validResults.push(result);
+        } else {
+          invalidResults.push({ result, error: validation.error });
+          logger.warn('Invalid UUID in batch', {
+            uuid: result.uuid,
+            error: validation.error
+          });
+        }
+      }
+
+      if (invalidResults.length > 0) {
+        logger.warn(`Skipping ${invalidResults.length} results with invalid UUIDs`);
+      }
+
+      const summary = await this.results.submitBatch(validResults, options);
+
+      logger.info('Batch submission completed', {
+        success: summary.success,
+        failed: summary.failed,
+        invalid: invalidResults.length,
+        total: results.length
+      });
+
+      return {
+        ...summary,
+        invalid: invalidResults.length,
+        invalidResults
+      };
+    } catch (error) {
+      logger.error('Failed to submit batch', {
+        error: error.message,
+        count: results.length
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Log orphan tests (tests without UUID mappings)
+   * @param {string} runId - Run ID
+   * @param {Array} orphanTests - Array of orphan test objects
+   * @returns {Promise<Object>} Response from server
+   */
+  async logOrphanTests(runId, orphanTests) {
+    try {
+      if (!this.config.options.logOrphans) {
+        logger.debug('Orphan test logging is disabled');
+        return { success: true, logged: 0 };
+      }
+
+      if (!orphanTests || orphanTests.length === 0) {
+        return { success: true, logged: 0 };
+      }
+
+      logger.info(`Logging ${orphanTests.length} orphan tests...`);
+
+      const response = await this.orphans.log(runId, orphanTests);
+
+      logger.info(`Orphan tests logged successfully`, {
+        runId,
+        count: orphanTests.length
+      });
+
+      return response;
+    } catch (error) {
+      logger.error('Failed to log orphan tests', {
+        error: error.message,
+        runId,
+        count: orphanTests.length
+      });
+      // Don't throw - orphan logging should not break the test run
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Add browser to existing run matrix dynamically
+   * @param {string} runId - Run ID
+   * @param {string} browser - Browser name
+   * @param {number} nid - Optional scenario/testset node ID (defaults to 0)
+   * @returns {Promise<Object>} Response from server
+   */
+  async addBrowser(runId, browser, nid = 0) {
+    try {
+      logger.info('Adding browser to run matrix', { runId, browser, nid });
+
+      const response = await this.runMatrix.addBrowser(runId, browser, nid);
+
+      logger.info('Browser added successfully', { runId, browser });
+
+      return response;
+    } catch (error) {
+      logger.error('Failed to add browser', {
+        error: error.message,
+        runId,
+        browser
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Get run matrix data
+   * @param {string} runId - Run ID
+   * @returns {Promise<Object>} Run matrix data
+   */
+  async getRun(runId) {
+    try {
+      const response = await this.runMatrix.get(runId);
+      return response;
+    } catch (error) {
+      logger.error('Failed to get run matrix', {
+        error: error.message,
+        runId
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Get current run context (if set)
+   * @returns {Object|null} Current run data or null
+   */
+  getCurrentRun() {
+    return this.currentRun;
+  }
+
+  /**
+   * Set current run context manually
+   * @param {Object} run - Run data with runId
+   */
+  setCurrentRun(run) {
+    this.currentRun = run;
+  }
+
+  /**
+   * Validate UUID format
+   * @param {string} uuid - UUID to validate
+   * @returns {boolean} True if valid
+   */
+  validateUuid(uuid) {
+    return UuidValidator.validate(uuid);
+  }
+
+  /**
+   * Extract NID from UUID
+   * @param {string} uuid - UUID string
+   * @returns {number|null} NID or null if invalid
+   */
+  extractNid(uuid) {
+    return UuidValidator.extractNid(uuid);
+  }
+
+  /**
+   * Validate and extract UUID components
+   * @param {string} uuid - UUID string
+   * @returns {Object} { valid, nid, uuid, error }
+   */
+  parseUuid(uuid) {
+    return UuidValidator.validateAndExtract(uuid);
+  }
+
+  /**
+   * Validate client configuration
+   * @private
+   */
+  validateConfig(config) {
+    if (!config) {
+      throw new Error(
+        'Configuration is required.\n' +
+        'Please provide configuration object:\n' +
+        '  const client = new AppliqationClient({\n' +
+        '    baseUrl: process.env.APPLIQATION_BASE_URL,\n' +
+        '    apiKey: process.env.APPLIQATION_API_KEY,\n' +
+        '    projectKey: process.env.APPLIQATION_PROJECT_KEY\n' +
+        '  });'
+      );
+    }
+
+    if (!config.baseUrl) {
+      throw new Error(
+        'baseUrl is required.\n' +
+        'Please set the APPLIQATION_BASE_URL environment variable or provide baseUrl in configuration:\n' +
+        '  APPLIQATION_BASE_URL=https://your-instance.appliqation.com\n' +
+        'Or in code:\n' +
+        '  { baseUrl: "https://your-instance.appliqation.com" }'
+      );
+    }
+
+    if (!config.projectKey) {
+      throw new Error(
+        'projectKey is required.\n' +
+        'Please set the APPLIQATION_PROJECT_KEY environment variable or provide projectKey in configuration:\n' +
+        '  APPLIQATION_PROJECT_KEY=your-project-key\n' +
+        'Or in code:\n' +
+        '  { projectKey: "your-project-key" }\n' +
+        '\n' +
+        'You can find your project key in the Appliqation dashboard under Project Settings.'
+      );
+    }
+
+    // Note: Both base64-encoded project keys AND numeric project IDs are now supported
+    // Numeric IDs are a temporary workaround for duplicate project key issues
+    // The backend will validate the project key format and access permissions
+
+    // Must have either API key or username/password
+    if (!config.apiKey && (!config.username || !config.password)) {
+      throw new Error(
+        'Authentication credentials are required.\n' +
+        'Please set the APPLIQATION_API_KEY environment variable (recommended):\n' +
+        '  APPLIQATION_API_KEY=appq_live_xxxxxxxxxxxx\n' +
+        'Or in code:\n' +
+        '  { apiKey: "appq_live_xxxxxxxxxxxx" }\n' +
+        '\n' +
+        'You can generate an API key in the Appliqation dashboard under Settings > API Keys.\n' +
+        '\n' +
+        'Legacy CSRF authentication (username/password) is also supported but not recommended.'
+      );
+    }
+
+    // Validate URL format
+    try {
+      new URL(config.baseUrl);
+    } catch (error) {
+      throw new Error(
+        `Invalid baseUrl format: "${config.baseUrl}"\n` +
+        'baseUrl must be a valid URL starting with http:// or https://\n' +
+        'Example: https://your-instance.appliqation.com'
+      );
+    }
+  }
+
+  /**
+   * Test connectivity to Appliqation instance
+   * @returns {Promise<boolean>} True if connection successful
+   */
+  async testConnection() {
+    try {
+      logger.info('Testing connection to Appliqation...');
+
+      // Try to authenticate
+      await this.auth.authenticate();
+
+      logger.info('Connection test successful');
+      return true;
+    } catch (error) {
+      logger.error('Connection test failed', {
+        error: error.message
+      });
+      throw new Error(`Connection test failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Determine if the current environment is production
+   * @private
+   * @returns {boolean} True if production environment
+   */
+  _isProductionEnvironment() {
+    // Check for CI environments
+    if (process.env.CI === 'true' || process.env.CI === '1') {
+      return true;
+    }
+
+    // Check NODE_ENV
+    const nodeEnv = (process.env.NODE_ENV || '').toLowerCase();
+    if (nodeEnv === 'production' || nodeEnv === 'prod' || nodeEnv === 'staging') {
+      return true;
+    }
+
+    // Check for common CI environment variables
+    const ciEnvVars = [
+      'GITHUB_ACTIONS',
+      'GITLAB_CI',
+      'CIRCLECI',
+      'TRAVIS',
+      'JENKINS_URL',
+      'TEAMCITY_VERSION',
+      'BUILDKITE'
+    ];
+
+    for (const envVar of ciEnvVars) {
+      if (process.env[envVar]) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Get SDK version
+   * @returns {string} Version string
+   */
+  getVersion() {
+    return require('../package.json').version;
+  }
+}
+
+module.exports = AppliqationClient;