froth-webdriverio-framework 7.0.116 → 7.0.118-uat

package/CLAUDE.md

@@ -0,0 +1,215 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Version:** 9.0.5-ytlc
+
+**Repository:** https://github.com/RoboticoDigitalProjects/froth-webdriverio.git
+
+This is a WebdriverIO test automation framework (FROTH - "froth-webdriverio-framework") that supports web, Android, and iOS testing on both BrowserStack and local environments. The framework integrates with a Froth TestOps backend API for execution tracking, reporting, and test data management.
+
+## Commands
+
+### Running Tests
+
+Tests are run using the WebdriverIO CLI with platform-specific configurations. Note: Configuration files (`android.conf.js`, `web.conf.js`, etc.) must be created at the root level to reference `froth_configs/wdio.common.conf.js`:
+
+```bash
+# Android tests
+npx wdio ./android.conf.js
+
+# Web tests
+npx wdio ./web.conf.js
+
+# iOS tests
+npx wdio ./ios.conf.js
+
+# Lint code
+npm run lint
+```
+
+### Creating Configuration Files
+
+Platform-specific config files must be created at the root level. Example `android.conf.js`:
+
+```javascript
+exports.config = require('./froth_configs/wdio.common.conf').config;
+```
+
+### Generating Allure Reports
+
+Allure reports are generated manually using the Allure CLI:
+
+```bash
+# Android reports
+allure generate ./mobile/androidReports/allure-results --clean && allure open
+
+# iOS reports
+allure generate ./mobile/iosReports/allure-results --clean && allure open
+
+# Web reports
+allure generate ./webReports/allure-results --clean && allure open
+```
+
+### Running Tests
+
+Tests are run by specifying environment variables and the config file:
+
+```bash
+SUITE=./android_suites/samplesuite_x.js \
+YML_NAME=./ymls/browserstack/android/android_pixel8.yml \
+PLATFORM=browserstack \
+EXECUTION_ID=123 \
+API_TOKEN=your_token \
+ORGANISATION_DOMAIN_URL=https://devapi.frothtestops.com \
+npx wdio ./android.conf.js
+```
+
+## Architecture
+
+### Configuration Hierarchy
+
+The framework uses a multi-layered configuration system:
+
+1. **Base Configuration** (`froth_configs/base.config.js`): Contains framework settings, specs path, timeouts, and Mocha options. Initializes a global `BUFFER` using `node-localstorage` for cross-module state sharing.
+
+2. **Common Configuration** (`froth_configs/wdio.common.conf.js`): Acts as the entry point. It:
+   - Loads capabilities from a YAML file specified by `YML_NAME`
+   - Decodes BrowserStack credentials from base64
+   - Determines platform (web vs mobile) based on `platformName` in capabilities
+   - Merges base config with platform-specific config
+
+3. **Platform-Specific Configs** (`froth_configs/browserstack/` and `froth_configs/local/`):
+   - `web.config.js`: BrowserStack web testing configuration
+   - `mobile.config.js`: BrowserStack mobile (Android/iOS) testing configuration
+   - Supports `BS_UPLOAD_MEDIA` for injecting media files into tests
+
+### Test Lifecycle and Hooks
+
+All test lifecycle hooks are defined in `froth_configs/commonhook.js`:
+
+- **onPrepare**: Initializes environment variables, execution details, suite details, and test data via `setallDatailinBuffer.js`. Registers global error handlers.
+- **beforeSession**: Validates test syntax, configures BrowserStack capabilities, sets app path for mobile testing
+- **beforeSuite**: Fetches BrowserStack session details, updates CICD run ID
+- **beforeTest/afterTest**: Updates individual script execution status via API
+- **afterSession**: Calculates total execution time, updates final execution status
+- **onComplete**: Clears the BUFFER storage
+
+### Directory Structure
+
+```
+froth_common_actions/     # Reusable test utilities and actions
+  ├── Utils.js            # Central export point for all utilities
+  ├── scroll.js           # Scrolling helpers (scrollToEnd, scrollDownToView, etc.)
+  ├── swipe.js            # Gesture helpers (swipeUp, swipeDown, swipeWithCoordinates)
+  ├── click.js            # Click helpers (clickIfVisible, doubleClick)
+  ├── assert.js           # Assertion helpers (assertText, assertAttributeValue)
+  ├── random.js           # Random data generators (RANDOMTEXT, RNDNUMBER, etc.)
+  ├── storeToBuffer.js    # Buffer storage helpers for runtime data
+  ├── dbValidator.js      # Database field validation
+  └── ...                 # Other common actions
+
+froth_api_calls/          # API integration layer
+  ├── loginapi.js         # Authentication token retrieval
+  ├── getexecutionDetails.js   # Fetch/update execution details via TestOps API
+  ├── getsuiteDetails.js  # Fetch test suite and script mappings
+  ├── readTestdata.js     # Fetch test data by ID
+  └── browsersatckSessionInfo.js # BrowserStack session management
+
+froth_configs/            # Configuration files
+  ├── base.config.js
+  ├── wdio.common.conf.js
+  ├── commonhook.js
+  ├── setallDatailinBuffer.js
+  ├── browserstack/       # BrowserStack-specific configs
+  └── local/              # Local execution configs
+
+android/                  # Android test scripts
+android_suites/           # Android suite definitions (array of test files)
+web/                      # Web test scripts
+web_suites/               # Web suite definitions
+ymls/browserstack/        # Capability YAML files for different devices/browsers
+```
+
+### Test Data Flow
+
+1. Environment variables are loaded in `setallDatailinBuffer.js` during `onPrepare`
+2. Global state is stored in `BUFFER` (node-localstorage at `./buffer_storage`)
+3. Execution details are fetched from the Froth TestOps API
+4. Test scripts access data via `BUFFER.getItem()` / `BUFFER.setItem()`
+5. Results are posted back to the API via `updateScriptExecutionStatus` and `updateExecuitonDetails`
+
+### Test Suite Pattern
+
+Suites are defined as simple modules exporting a `tests` array:
+
+```javascript
+// Example: android_suites/samplesuite_x.js
+module.exports = {
+    tests: [
+        '/absolute/path/to/android/test_script.js'
+    ]
+};
+```
+
+### Common Actions Usage
+
+Tests import utilities from the Utils export:
+
+```javascript
+const Util = require('../froth_common_actions/Utils');
+
+// Scrolling
+await Util.scrollToEnd(2, 3);
+await Util.scrollDownToView("Some Text");
+
+// Swiping
+await Util.swipeWithCoordinates(x1, y1, x2, y2);
+
+// Random data
+const randomText = Util.randomtext(10);
+const randomNumber = Util.randomnumber(100, 999);
+
+// Buffer storage
+Util.storetext('key', 'value');
+const value = BUFFER.getItem('key');
+```
+
+## Required Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `YML_NAME` | Path to capability YAML file | `./ymls/browserstack/android/android_pixel8.yml` |
+| `SUITE` | Path to suite file | `./android_suites/samplesuite_x.js` |
+| `PLATFORM` | `browserstack`, `browserstacklocal`, or omitted for local | `browserstack` |
+| `EXECUTION_ID` | Test execution ID from TestOps | `123` |
+| `API_TOKEN` | Authentication token for TestOps API | `eyJhbG...` |
+| `ORGANISATION_DOMAIN_URL` | Froth TestOps API base URL | `https://devapi.frothtestops.com` |
+| `CICD_RUN_ID` | CI/CD pipeline run ID (optional) | `build-456` |
+| `BS_UPLOAD_MEDIA` | Comma-separated media URLs for BrowserStack (optional) | `url1,url2` |
+
+## Capability YAML Format
+
+YAML files define device/browser capabilities. Example for Android:
+
+```yaml
+userName: "bs_username"
+accessKey: "base64_encoded_key"
+platformName: "Android"
+deviceName: "Samsung Galaxy S22 Ultra"
+platformVersion: "12.0"
+debug: true
+networkLogs: true
+interactiveDebugging: false
+```
+
+## Important Notes
+
+- The framework uses `node-localstorage` to create a global `BUFFER` accessible across all modules
+- All API responses from TestOps are AES-decrypted via `aesEncryptionDecryption.js`
+- Test scripts map to TestOps via filename (script name must match `scriptName` in suite details)
+- Mobile tests use Appium selectors like `id:com.example:id/elementId` and `-android uiautomator:...`
+- Web tests use standard WebdriverIO selectors (`$`, `$$`)
+- Framework supports both BrowserStack App Automate (mobile) and Automate (web) sessions

package/froth_api_calls/browsersatckSessionInfo.js

@@ -64,8 +64,10 @@ async function getBSSessionDetails(sessionType, bsUsername, bsPassword) {
 
             BUFFER.setItem("REPORT_URL", publicUrl);
             BUFFER.setItem("FROTH_TOTAL_DURATION", duration);
+            BUFFER.setItem("BS_BUILD_HASH_ID", hashId);
 
             console.log(`Public URL: ${publicUrl}`);
+            console.log(`Build Hash ID: ${hashId}`);
         } else if (response.status === 401) {
             console.error("Unauthorized: token expired to login Browserstack");
         } else {
@@ -160,11 +162,76 @@ async function escapeForBrowserStack(message) {
         .replace(/\r/g, "\\r");
 }
 
+/* ===================== BROWSERSTACK REPORT API ===================== */
+
+/**
+ * Updates BrowserStack report details in Froth TestOps database
+ * @param {string} frothUrl - Froth TestOps API base URL
+ * @param {string} token - Authentication token
+ * @param {string} bsBuildId - BrowserStack build ID (e.g., "frothtestops-coderepo_1286_20260211")
+ * @param {number} executionId - Test execution ID
+ * @param {string} status - BrowserStack status: "in_progress" (updates public URL only) or "completed"
+ */
+async function updateBrowserStackReport(frothUrl, token, bsBuildId, executionId, status) {
+    if (!frothUrl || !token || !bsBuildId || !executionId || !status) {
+        console.error('❌ Missing required parameters for updateBrowserStackReport');
+        console.error(`frothUrl: ${frothUrl}, token: ${!!token}, bsBuildId: ${bsBuildId}, executionId: ${executionId}, status: ${status}`);
+        return null;
+    }
+
+    const validStatuses = ['in_progress', 'completed'];
+    if (!validStatuses.includes(status)) {
+        console.error(`❌ Invalid browserstack_status: ${status}. Must be one of: ${validStatuses.join(', ')}`);
+        return null;
+    }
+
+    const url = `${frothUrl}/api/download-browserstack-report/`;
+    console.log(`📤 Updating BrowserStack report [${status}]:`, url);
+
+    const payload = {
+        BS_BUILD_ID: bsBuildId,
+        execution_id: executionId,
+        browserstack_status: status
+    };
+
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(payload)
+        });
 
+        const contentType = response.headers.get('content-type') || '';
+        let data;
+        if (contentType.includes('application/json')) {
+            data = await response.json();
+        } else {
+            data = await response.text();
+        }
+
+        if (response.ok) {
+            console.log(`✅ BrowserStack report updated successfully [${status}]`);
+            return data;
+        } else if (response.status === 401) {
+            console.error('🔒 Unauthorized (401) - Token may be expired');
+            return null;
+        } else {
+            console.error(`❌ Failed to update BrowserStack report [${response.status}]:`, data);
+            return null;
+        }
 
+    } catch (error) {
+        console.error('❌ updateBrowserStackReport error:', error.message);
+        return null;
+    }
+}
 
 module.exports = {
     getBSSessionDetails,
     getBSBuildDetails,
     amend2Browserstack,
+    updateBrowserStackReport,
 };

package/froth_api_calls/getexecutionDetails.js

@@ -139,12 +139,12 @@ async function updateExecuitonDetails(frothUrl, token, id, resultdetails) {
             formData.append('excution_status', resultdetails.excution_status);
         }
 
-        if (
-            resultdetails.excution_time &&
-            resultdetails.excution_time !== 'NaN:NaN:NaN'
-        ) {
-            formData.append('excution_time', resultdetails.excution_time);
-        }
+        // if (
+        //     resultdetails.excution_time &&
+        //     resultdetails.excution_time !== 'NaN:NaN:NaN'
+        // ) {
+        //     formData.append('excution_time', resultdetails.excution_time);
+        // }
 
         if (resultdetails.comments === null)
             console.log("Comments is null")

package/froth_common_actions/Utils.js

@@ -56,6 +56,7 @@ let amendBrowserStackLog = null;
 let logJsonDataToTable = null;
 
 let extractEmailLinks = null;
+let comparator=null;
 
 if (process.env.LOCATION == null || process.env.LOCATION == 'local') {
     basepath = ".";
@@ -116,7 +117,7 @@ captureLoadNavigation = require(basepath + '/captureNavigationTime').captureLoad
 
 amendBrowserStackLog = require(basepath + '/../froth_api_calls/browsersatckSessionInfo').amend2Browserstack;
 logJsonDataToTable = require(basepath + '/logData').logJsonData2Table;
-
+comparator=require(basepath +'/dbValidator').validateDbFields
 //extractEmailLinks = require(basepath + '/emailParsing');
 //export the variabels
 module.exports = {
@@ -163,5 +164,6 @@ module.exports = {
     captureLoadNavigation,
     amendBrowserStackLog,
     logJsonDataToTable,
-    extractEmailLinks
+    extractEmailLinks,
+    comparator
 };

package/froth_common_actions/dbValidator.js

@@ -0,0 +1,219 @@
+const amendBrowserStackLog = require('../froth_api_calls/browsersatckSessionInfo').amend2Browserstack;
+
+/**
+ * Convert any timestamp string/number to milliseconds.
+ * Auto-detects multiple formats.
+ */
+async function parseTimestamp(input) {
+  if (!input) return NaN;
+
+  // Case 1: Numeric → Unix timestamp (ms or sec)
+  if (!isNaN(input)) {
+    const num = Number(input);
+
+    // If it's in seconds (10 digits), convert to ms
+    if (num.toString().length === 10) return num * 1000;
+
+    // Already ms (13 digits)
+    return num;
+  }
+
+  // Case 2: Direct Date() parseable ISO formats
+  let parsed = Date.parse(input);
+  if (!isNaN(parsed)) return parsed;
+
+  // Case 3: Common non-ISO formats → manual normalization
+  const replacements = [
+    { pattern: /\//g, replace: '-' },      // 2025/01/10 -> 2025-01-10
+    { pattern: / /g, replace: 'T' }        // 2025-01-10 12:30 -> 2025-01-10T12:30
+  ];
+
+  let normalized = input;
+  replacements.forEach(r => {
+    normalized = normalized.replace(r.pattern, r.replace);
+  });
+
+  parsed = Date.parse(normalized);
+  if (!isNaN(parsed)) return parsed;
+
+  // Case 4: Try reversing DD-MM-YYYY → YYYY-MM-DD
+  const dmY = /^(\d{2})-(\d{2})-(\d{4})(.*)$/;
+  if (dmY.test(input)) {
+    const parts = input.match(dmY);
+    normalized = `${parts[3]}-${parts[2]}-${parts[1]}${parts[4]}`;
+    parsed = Date.parse(normalized);
+    if (!isNaN(parsed)) return parsed;
+  }
+
+  return NaN;
+}
+
+/**
+ * Main DB validation utility
+ */
+async function validateDbFields(actualData, expectedData, context = 'DB Validation') {
+  await amendBrowserStackLog(`🔍 START DB VALIDATION: ${context}`, 'info');
+
+  const results = [];
+  let allPassed = true;
+
+  for (const key of Object.keys(expectedData)) {
+
+    const expectedConfig = expectedData[key];
+    const actual = actualData[key];
+    let expected = expectedConfig;
+    let status = "PASS";
+
+    // -----------------------------
+    // SKIP DYNAMIC FIELDS
+    // -----------------------------
+    if (expectedConfig === "*dynamic*") {
+      results.push({
+        key, actual, expected: "(SKIPPED - dynamic)", status: "SKIPPED"
+      });
+      continue;
+    }
+
+    // -----------------------------
+    // NULLABLE VALIDATION (allow null/empty)
+    // -----------------------------
+    if (typeof expectedConfig === "object" && expectedConfig.type === "nullable") {
+      const isNullOrEmpty = actual === null || actual === undefined || actual === "" || actual === "null";
+      status = isNullOrEmpty ? "PASS" : "PASS"; // Always pass - just validates field exists
+      results.push({
+        key,
+        actual,
+        expected: "(nullable - any value allowed)",
+        status
+      });
+      continue;
+    }
+
+    // -----------------------------
+    // NUMBER WITH TOLERANCE
+    // -----------------------------
+    if (typeof expectedConfig === "object" && expectedConfig.type === "number") {
+      expected = expectedConfig.value;
+      const tolerance = expectedConfig.tolerance || 0;
+
+      const actualNum = parseFloat(actual);
+      const expectedNum = parseFloat(expected);
+
+      if (isNaN(actualNum) || isNaN(expectedNum)) {
+        status = "FAIL";
+      } else {
+        const diff = Math.abs(actualNum - expectedNum);
+        status = diff <= tolerance ? "PASS" : "FAIL";
+      }
+
+      results.push({
+        key,
+        actual,
+        expected: `${expected} (±${tolerance})`,
+        status
+      });
+
+      if (status === "FAIL") allPassed = false;
+      continue;
+    }
+
+    // -----------------------------
+    // PARTIAL STRING MATCH
+    // -----------------------------
+    if (typeof expectedConfig === "object" && expectedConfig.type === "partial") {
+      const substring = expectedConfig.contains;
+      const actualStr = String(actual || "");
+
+      status = actualStr.includes(substring) ? "PASS" : "FAIL";
+
+      results.push({
+        key,
+        actual,
+        expected: `(contains "${substring}")`,
+        status
+      });
+
+      if (status === "FAIL") allPassed = false;
+      continue;
+    }
+
+    // -----------------------------
+    // TIMESTAMP VALIDATION
+    // -----------------------------
+    if (typeof expectedConfig === "object" && expectedConfig.type === "timestamp") {
+      expected = expectedConfig.value;
+      const tolerance = expectedConfig.toleranceMs || 0;
+
+      let actualMs = await parseTimestamp(actual);
+      let expectedMs = await parseTimestamp(expected);
+
+      if (isNaN(actualMs) || isNaN(expectedMs)) {
+        status = "FAIL";
+        results.push({
+          key,
+          actual,
+          expected,
+          status: "FAIL - Unrecognized Timestamp Format"
+        });
+        allPassed = false;
+        continue;
+      }
+
+      const diff = Math.abs(actualMs - expectedMs);
+      if (diff > tolerance) status = "FAIL";
+
+      results.push({
+        key,
+        actual,
+        expected: `${expected} (±${tolerance}ms)`,
+        status
+      });
+
+      if (status === "FAIL") allPassed = false;
+      continue;
+    }
+
+    // -----------------------------
+    // NORMAL STRING/NUMBER COMPARISON
+    // -----------------------------
+    if (String(actual) !== String(expected)) {
+      status = "FAIL";
+      allPassed = false;
+    }
+
+    results.push({ key, actual, expected, status });
+  }
+
+  // -----------------------------
+  // BROWSERSTACK LOGGING
+  // -----------------------------
+  //   const chunkSize = 800;
+  const combined = results
+    .map(r => `${r.key} => Expected: ${r.expected}, Actual: ${r.actual}, Status: ${r.status}`)
+    .join(" | ");
+
+  //   const chunks = combined.match(new RegExp(`.{1,${chunkSize}}`, "g")) || [];
+  //   for (const c of chunks) await amendBrowserStackLog(c, "info");
+
+  await amendBrowserStackLog(combined, "info");
+  // -----------------------------
+  // FINAL RESULT
+  // -----------------------------
+  await amendBrowserStackLog(
+    allPassed ? "✅ DB VALIDATION PASSED" : "❌ DB VALIDATION FAILED",
+    allPassed ? "info" : "error"
+  );
+
+  return allPassed;
+}
+
+module.exports = {
+  parseTimestamp,
+  validateDbFields
+};
+
+// async function main(){
+
+// }
+
+// main()

package/froth_configs/commonhook.js

@@ -1,7 +1,7 @@
 
 const setAllDetails = require('./setallDatailinBuffer');
 const exeDetails = require('../froth_api_calls/getexecutionDetails');
-const { getBSSessionDetails } = require('../froth_api_calls/browsersatckSessionInfo');
+const { getBSSessionDetails, updateBrowserStackReport } = require('../froth_api_calls/browsersatckSessionInfo');
 let globalErrorHandled = false;
 let suiteStartTime = 0;
 let totalTestDuration = 0;
@@ -187,11 +187,23 @@ const commonHooks = {
     suiteStartTime = Date.now();
 
     if (process.env.PLATFORM === 'browserstack' || process.env.PLATFORM === 'browserstacklocal') {
-      await getBSSessionDetails(
-        process.env.BS_SESSION_TYPE,
-        process.env.BROWSERSTACK_USERNAME,
-        process.env.BROWSERSTACK_ACCESS_KEY
-      );
+      // await getBSSessionDetails(
+      //   process.env.BS_SESSION_TYPE,
+      //   process.env.BROWSERSTACK_USERNAME,
+      //   process.env.BROWSERSTACK_ACCESS_KEY
+      // );
+
+      // Update BrowserStack report with in_progress status
+      const buildName = process.env.FROTH_TESTOPS_BUILD_NAME;
+      if (buildName) {
+        await updateBrowserStackReport(
+          BUFFER.getItem('ORGANISATION_DOMAIN_URL'),
+          BUFFER.getItem('FROTH_LOGIN_TOKEN'),
+          buildName,
+          BUFFER.getItem('FROTH_EXECUTION_ID'),
+          'in_progress'
+        );
+      }
     }
 
     await exeDetails.update_CICDRUNID_ReportUrl(
@@ -287,6 +299,20 @@ const commonHooks = {
     console.log('⏱ Final execution time (hh:mm:ss):', resultdetails.excution_time);
     await safeUpdateExecution();
 
+    // Update BrowserStack report with completed status
+    if (process.env.PLATFORM === 'browserstack' || process.env.PLATFORM === 'browserstacklocal') {
+      const bsBuildHashId = BUFFER.getItem('BS_BUILD_HASH_ID');
+      if (bsBuildHashId) {
+        await updateBrowserStackReport(
+          BUFFER.getItem('ORGANISATION_DOMAIN_URL'),
+          BUFFER.getItem('FROTH_LOGIN_TOKEN'),
+          bsBuildHashId,
+          BUFFER.getItem('FROTH_EXECUTION_ID'),
+          'completed'
+        );
+      }
+    }
+
 
   },
 

package/package.json

@@ -1,21 +1,11 @@
 {
   "name": "froth-webdriverio-framework",
-  "version": "7.0.116",
+  "version": "7.0.118-uat",
   "readme": "WebdriverIO Integration",
   "description": "WebdriverIO and BrowserStack App Automate",
   "license": "MIT",
-  "engines": {
-    "node": "18"
-  },
+ 
   "scripts": {
-    "wdio:ios": "npx wdio ./ios.conf.js",
-    "wdio:android": "npx wdio ./android.conf.js",
-    "wdio:web": "npx wdio ./web.conf.js",
-    "wdio:webbs": "npx wdio ./web.conf.bs.js",
-    "wdio:ios:local": "npx wdio ./ios.local.conf.js",
-    "android:generate-allure-report": "allure generate ./mobile/androidReports/allure-results --clean && allure open",
-    "ios:generate-allure-report": "allure generate  ./mobile/iosReports/allure-results --clean && allure open",
-    "web:generate-allure-report": "allure generate ./webReports/allure-results --clean && allure open",
     "lint": "eslint ."
   },
   "repository": {