@appliqation/automation-sdk 2.3.1 → 2.4.0

package/README.md

@@ -3,6 +3,7 @@
 A powerful SDK for integrating Playwright test results with the Appliqation test management portal.
 
 **What it does:**
+- ✅ **Auto-configuration** - Configure with just an API key (NEW!)
 - ✅ Automatically creates test runs in Appliqation
 - ✅ Handles browser authentication with JWT tokens
 - ✅ Reports test results (passed/failed/skipped) to your portal
@@ -41,6 +42,19 @@ Before you begin, ensure you have:
 
 Follow these steps in order to integrate the SDK with your Playwright tests.
 
+> **🎉 NEW: Simplified Configuration**
+> You now only need **one configuration value** to get started! Just provide your API key and the SDK automatically fetches your project ID and environment. This reduces setup from 3 required values to just 1.
+>
+> ```bash
+> # Before: 3 required values
+> APPLIQATION_API_KEY=...
+> APPLIQATION_PROJECT_KEY=...        # ❌ No longer required
+> APPLIQATION_ENVIRONMENT=...        # ❌ No longer required
+>
+> # After: 1 required value
+> APPLIQATION_API_KEY=...            # ✅ That's it!
+> ```
+
 **📌 Important:** Appliqation reporting is **opt-in**. You must either set `APPQ_ENABLE=1` environment variable or add `-- --appq` flag to your test command to send results to Appliqation. Without enabling reporting, tests run normally but results are not reported.
 
 ### Step 1: Install the SDK
@@ -59,20 +73,25 @@ npm install @appliqation/automation-sdk dotenv
 
 Create a `.env` file in your project root with your Appliqation credentials:
 
-**File:** `.env`
+**File:** `.env` (Simplified - Recommended)
 ```bash
-# IMPORTANT: No spaces around = signs, no trailing slashes on URLs
+# 🎉 NEW: Auto-Configuration - Only API key required!
+# The SDK automatically fetches project ID and environment from your API key
 
 APPLIQATION_API_KEY=appq_live_xxxxxxxxxxxxxxxxxxxx
-APPLIQATION_PROJECT_KEY=your-project-key-here
 TEST_APP_URL=https://www.example.com    # App under test (Playwright baseURL)
 ```
 
-**How to get these values:**
-- `APPLIQATION_API_KEY` -     Found in your project settings
-- `APPLIQATION_PROJECT_KEY` - Found in your project settings
-- `TEST_APP_URL` - The site you’re testing (e.g., https://www.amazon.in). Used as Playwright `baseURL`.
-- 
+**That's it!** The SDK will automatically:
+- ✅ Fetch your project ID from the API key
+- ✅ Detect available environments
+- ✅ Use the default environment
+
+**How to get your API key:**
+- Go to your Appliqation project settings
+- Navigate to Settings > API Keys
+- Generate a new API key
+- Copy the API key (starts with `appq_live_`)
 
 **⚠️ Add .env to .gitignore** to keep credentials secret:
 ```bash
@@ -81,20 +100,50 @@ echo ".env" >> .gitignore
 
 ---
 
+<details>
+<summary><strong>Advanced: Manual Configuration (Optional)</strong></summary>
+
+If you prefer to specify project ID and environment manually (or need backward compatibility), you can use the traditional configuration:
+
+```bash
+# Traditional configuration - Still supported!
+APPLIQATION_API_KEY=appq_live_xxxxxxxxxxxxxxxxxxxx
+APPLIQATION_PROJECT_KEY=1162                    # Optional: Auto-fetched if not provided
+APPLIQATION_ENVIRONMENT=Production              # Optional: Uses default if not provided
+TEST_APP_URL=https://www.example.com
+```
+
+**When to use manual configuration:**
+- You want to override the auto-detected environment
+- You're testing the SDK in development
+- You have specific environment requirements
+- Backward compatibility with existing setups
+
+**Benefits of auto-configuration:**
+- Simpler setup (1 value instead of 3)
+- Less configuration errors
+- Automatic environment validation
+- Easy to get started for new users
+
+</details>
+
+---
+
 ### Step 3: Update playwright.config.js
 
 Update your Playwright configuration to use the SDK's built-in features:
 
-**File:** `playwright.config.js`
+**File:** `playwright.config.js` (Simplified)
 
 ```javascript
 const { defineConfig } = require('@playwright/test');
 require('dotenv').config();  // Load .env variables
 
-// SDK configuration
+// SDK configuration - Auto-configuration enabled!
 const appliqationConfig = {
   apiKey: process.env.APPLIQATION_API_KEY,
-  projectKey: process.env.APPLIQATION_PROJECT_KEY,
+  // projectKey: Auto-fetched from API key! ✨
+  // environment: Auto-detected default environment! ✨
 
   // Optional settings
   autoCreateRun: true,           // Automatically create run on test start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appliqation/automation-sdk",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Appliqation Automation SDK with API key authentication, custom run titles, and framework-specific reporters",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/AppliqationClient.js

@@ -134,21 +134,165 @@ class AppliqationClient {
     // Track current run context
     this.currentRun = null;
 
+    // Auto-configuration state
+    this._autoConfigured = false;
+    this._projectInfo = null;
+    this._autoConfigPromise = null; // Prevents concurrent auto-config calls
+
     // Show baseUrl only in DEBUG mode
     const meta = {
-      authMode: this.config.apiKey ? 'api_key' : 'csrf'
+      authMode: this.config.apiKey ? 'api_key' : 'csrf',
+      autoConfigEnabled: !this.config.projectKey // Will auto-fetch if projectKey not provided
     };
     logger.info('Appliqation client initialized', meta);
     logger.debug('Client configuration', { baseUrl: this.config.baseUrl });
   }
 
+  /**
+   * Ensure project configuration is loaded
+   * Automatically fetches project metadata from API key if projectKey not provided.
+   * This method is idempotent and can be called multiple times safely.
+   *
+   * @private
+   * @returns {Promise<void>}
+   * @throws {Error} If auto-configuration fails
+   */
+  async ensureProjectConfig() {
+    // If projectKey provided manually, no need to fetch
+    if (this.config.projectKey) {
+      return;
+    }
+
+    // If already auto-configured, skip
+    if (this._autoConfigured) {
+      return;
+    }
+
+    // If auto-config is in progress, wait for it
+    if (this._autoConfigPromise) {
+      return this._autoConfigPromise;
+    }
+
+    // Start auto-configuration
+    this._autoConfigPromise = this._performAutoConfig();
+
+    try {
+      await this._autoConfigPromise;
+    } finally {
+      this._autoConfigPromise = null;
+    }
+  }
+
+  /**
+   * Perform auto-configuration by fetching project info
+   * @private
+   * @returns {Promise<void>}
+   */
+  async _performAutoConfig() {
+    logger.info('Auto-fetching project configuration from API key...');
+
+    try {
+      this._projectInfo = await this.http.getProjectInfo();
+
+      // Validate response structure
+      if (!this._projectInfo || typeof this._projectInfo !== 'object') {
+        throw new Error(
+          `Invalid response format: expected object, got ${typeof this._projectInfo}`
+        );
+      }
+
+      if (!this._projectInfo.project_id && this._projectInfo.project_id !== 0) {
+        throw new Error(
+          `Invalid response: missing project_id field in API response`
+        );
+      }
+
+      this._autoConfigured = true;
+
+      // Update config with fetched project_id
+      this.config.projectKey = this._projectInfo.project_id.toString();
+
+      logger.info('Auto-configuration successful', {
+        project_id: this._projectInfo.project_id,
+        project_title: this._projectInfo.project_title,
+        environments: this._projectInfo.environments,
+        default_environment: this._projectInfo.default_environment
+      });
+
+      // Log warning if no environments configured
+      if (!this._projectInfo.has_environments_configured) {
+        logger.warn('Project has no environments configured. Using default environment "Local".', {
+          project_id: this._projectInfo.project_id,
+          action_required: 'Configure environments in project settings for better environment validation'
+        });
+      }
+    } catch (error) {
+      logger.error('Auto-configuration failed', {
+        error: error.message
+      });
+
+      throw new Error(
+        `Failed to auto-configure project from API key: ${error.message}\n\n` +
+        'Possible solutions:\n' +
+        '1. Verify your API key is valid and not expired\n' +
+        '2. Ensure your API key is associated with a valid project\n' +
+        '3. Check network connectivity to Appliqation instance\n' +
+        '4. Provide projectKey manually in configuration as fallback:\n' +
+        '   { projectKey: "your-project-id" }'
+      );
+    }
+  }
+
+  /**
+   * Get available environments for the project
+   * Automatically triggers project info fetch if not already loaded.
+   *
+   * @returns {Promise<Array<string>>} List of environment names
+   * @example
+   * const environments = await client.getAvailableEnvironments();
+   * console.log(environments); // ['Development', 'Staging', 'Production']
+   */
+  async getAvailableEnvironments() {
+    await this.ensureProjectConfig();
+    return this._projectInfo?.environments || [];
+  }
+
+  /**
+   * Get default environment for the project
+   * Automatically triggers project info fetch if not already loaded.
+   *
+   * @returns {Promise<string>} Default environment name
+   * @example
+   * const defaultEnv = await client.getDefaultEnvironment();
+   * console.log(defaultEnv); // 'Development'
+   */
+  async getDefaultEnvironment() {
+    await this.ensureProjectConfig();
+    return this._projectInfo?.default_environment || 'Local';
+  }
+
+  /**
+   * Get cached project information
+   * Returns null if auto-configuration hasn't been triggered yet.
+   *
+   * @returns {Object|null} Project metadata or null
+   * @property {number} project_id - Project ID
+   * @property {string} project_title - Project name
+   * @property {Array<string>} environments - Available environments
+   * @property {string} default_environment - Default environment
+   * @property {boolean} has_environments_configured - Whether environments exist
+   */
+  getProjectInfo() {
+    return this._projectInfo;
+  }
+
   /**
    * 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.environment='Local'] - Environment name (auto-detected if not provided)
    * @param {string[]} [options.browsers=['Chrome']] - Array of browser names
    * @param {string} [options.device] - Device type (Desktop, Mobile, Tablet)
    * @param {string} [options.os] - Operating system
@@ -157,6 +301,18 @@ class AppliqationClient {
    */
   async createRun(options) {
     try {
+      // Ensure project config is loaded (auto-fetch if needed)
+      await this.ensureProjectConfig();
+
+      // If environment not provided, use auto-detected default
+      if (!options.environment && this._projectInfo) {
+        options.environment = this._projectInfo.default_environment;
+        logger.info('Using auto-detected default environment', {
+          environment: options.environment,
+          source: 'project_config'
+        });
+      }
+
       logger.info('Creating run matrix...', options);
 
       const run = await this.runMatrix.create(options);
@@ -504,23 +660,7 @@ class AppliqationClient {
       );
     }
 
-    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
+    // Must have either API key or username/password for authentication
     if (!config.apiKey && (!config.username || !config.password)) {
       throw new Error(
         'Authentication credentials are required.\n' +
@@ -535,6 +675,27 @@ class AppliqationClient {
       );
     }
 
+    // projectKey is now optional when using API key authentication
+    // If not provided, it will be auto-fetched from the API key's associated project
+    if (!config.projectKey && !config.apiKey) {
+      throw new Error(
+        'projectKey is required when not using API key authentication.\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' +
+        'Alternatively, use API key authentication (recommended) and projectKey will be auto-fetched:\n' +
+        '  APPLIQATION_API_KEY=appq_live_xxxxxxxxxxxx\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 supported
+    // Numeric IDs are used when auto-fetched from API key
+    // The backend validates project access permissions
+
     // Validate URL format
     try {
       new URL(config.baseUrl);

package/src/core/HttpClient.js

@@ -306,6 +306,68 @@ class HttpClient {
     }
   }
 
+  /**
+   * Fetch project information from API key
+   * Enables SDK auto-configuration where only API key is required.
+   * Returns project metadata including ID, title, and configured environments.
+   *
+   * @returns {Promise<Object>} Project metadata
+   * @property {boolean} success - Operation success status
+   * @property {number} project_id - Numeric project ID
+   * @property {number} project_nid - Same as project_id (for consistency)
+   * @property {string} project_title - Project name
+   * @property {Array<string>} environments - List of configured environment names
+   * @property {string} default_environment - First environment or 'Local' fallback
+   * @property {boolean} has_environments_configured - Whether environments exist
+   *
+   * @throws {Error} If API key is invalid or project not found
+   *
+   * @example
+   * const projectInfo = await httpClient.getProjectInfo();
+   * console.log(projectInfo.project_id); // 1162
+   * console.log(projectInfo.environments); // ['Development', 'Staging', 'Production']
+   * console.log(projectInfo.default_environment); // 'Development'
+   */
+  async getProjectInfo() {
+    logger.debug('Fetching project information from API key...');
+
+    try {
+      const response = await this.get('/api/automation/project/info');
+
+      logger.info('Project info retrieved successfully', {
+        project_id: response.data.project_id,
+        project_title: response.data.project_title,
+        environments: response.data.environments,
+        has_environments: response.data.has_environments_configured
+      });
+
+      return response.data;
+    } catch (error) {
+      logger.error('Failed to fetch project info', {
+        error: error.message,
+        status: error.response?.status,
+        code: error.code
+      });
+
+      // Enhance error message for common scenarios
+      if (error.response?.status === 400) {
+        throw new Error(
+          'No project associated with this API key. Please verify your API key is correctly configured.'
+        );
+      } else if (error.response?.status === 404) {
+        throw new Error(
+          'Project not found or invalid. Please verify your API key is associated with a valid project.'
+        );
+      } else if (error.response?.status === 401 || error.response?.status === 403) {
+        throw new Error(
+          'API key authentication failed. Please verify your API key is valid and not expired.'
+        );
+      }
+
+      throw error;
+    }
+  }
+
   /**
    * Set authorization header
    * @param {string} token - Authorization token

package/src/reporters/cypress/CypressReporter.js

@@ -161,6 +161,18 @@ class CypressReporter {
    */
   async createRun(details) {
     try {
+      // Auto-configure project from API key if needed
+      await this.client.ensureProjectConfig();
+
+      // Use auto-detected environment if not explicitly provided
+      if (!this.config.environment && this.client._projectInfo) {
+        this.config.environment = this.client._projectInfo.default_environment;
+        logger.info('Using auto-detected default environment', {
+          environment: this.config.environment,
+          source: 'api_key_project_config'
+        });
+      }
+
       const browser = details.browser?.displayName || details.browser?.name || 'Cypress';
       const platform = details.system?.platform || process.platform;
       const os = this.detectOS(platform);

package/src/reporters/jest/JestReporter.js

@@ -137,6 +137,18 @@ class JestReporter {
    */
   async createRun() {
     try {
+      // Auto-configure project from API key if needed
+      await this.client.ensureProjectConfig();
+
+      // Use auto-detected environment if not explicitly provided
+      if (!this.config.environment && this.client._projectInfo) {
+        this.config.environment = this.client._projectInfo.default_environment;
+        logger.info('Using auto-detected default environment', {
+          environment: this.config.environment,
+          source: 'api_key_project_config'
+        });
+      }
+
       const os = this.detectOS();
 
       const runOptions = {

package/src/reporters/playwright/AppliqationReporter.js

@@ -209,6 +209,26 @@ class AppliqationReporter {
       return;
     }
 
+    // Auto-configure project from API key if needed
+    try {
+      await this.client.ensureProjectConfig();
+
+      // Use auto-detected environment if not explicitly provided
+      if (!this.config.environment && this.client._projectInfo) {
+        this.config.environment = this.client._projectInfo.default_environment;
+        logger.info('Using auto-detected default environment', {
+          environment: this.config.environment,
+          source: 'api_key_project_config'
+        });
+      }
+    } catch (error) {
+      logger.error('Failed to auto-configure from API key', {
+        error: error.message
+      });
+      console.error('\n❌ Auto-configuration failed:', error.message);
+      throw error;
+    }
+
     // Get project names that are actually running (honors --project filter)
     const runningProjectNames = this.getRunningProjectNames(suite);
     logger.debug('Projects actually running:', runningProjectNames);
@@ -546,11 +566,11 @@ class AppliqationReporter {
       this.trackResult(runInfo.runId, testResult);
 
       // Update counters
-      if (testResult.status === 'passed') {
+      if (testResult.status === 'Pass') {
         this.passedTests++;
-      } else if (testResult.status === 'failed') {
+      } else if (testResult.status === 'Fail') {
         this.failedTests++;
-      } else if (testResult.status === 'skipped') {
+      } else if (testResult.status === 'Skipped') {
         this.skippedTests++;
       }
 
@@ -1465,27 +1485,13 @@ class AppliqationReporter {
       throw new Error('apiKey is required');
     }
 
-    if (!this.config.projectKey) {
-      throw new Error('projectKey is required');
-    }
+    // projectKey is now optional with API key authentication
+    // It will be auto-fetched from the API key's associated project
+    // If not provided, auto-configuration will happen in onBegin()
 
-    // Environment is required - no default fallback
-    if (!this.config.environment) {
-      throw new Error(
-        '\n' +
-        '❌ Testing environment is required.\n' +
-        '\n' +
-        'Please provide the environment in your test run command:\n' +
-        '\n' +
-        '  APPLIQATION_ENVIRONMENT=Production npx playwright test\n' +
-        '\n' +
-        'Or set it in your .env file:\n' +
-        '\n' +
-        '  APPLIQATION_ENVIRONMENT=Production\n' +
-        '\n' +
-        'Valid environments are configured in your Appliqation project settings.\n'
-      );
-    }
+    // environment is now optional - will be auto-detected from project configuration
+    // If not provided, the default environment from the project will be used
+    // Manual configuration still supported for backward compatibility
 
     // Note: scenarioId, testSetId, and title are optional
   }