froth-webdriverio-framework 7.0.119-dev1.0 → 7.0.119-dev1.10

package/README.md

@@ -0,0 +1,245 @@
+# README.md
+
+## 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. The framework uses `wdio.common.conf.js` directly without requiring platform-specific config files.
+
+```bash
+# Lint code
+npm run lint
+```
+
+### Viewing Test Results
+
+#### Local Execution Reports (Automatic)
+
+When running tests with `PLATFORM=local`, the framework **automatically generates Mochawesome HTML reports** after test execution completes:
+
+- Reports are saved in: `./reports/mochawesome/`
+- Each execution gets a **unique report directory** using `BROWSERSTACK_BUILD_NAME` and timestamp
+- Format: `./reports/mochawesome/{BUILD_NAME}-{YYYY-MM-DD}/mochawesome.html`
+- Reports **auto-open in browser** after generation
+
+**Example:**
+```bash
+# Run tests with unique build name
+BROWSERSTACK_BUILD_NAME="Web_Login_Test_20250619" \
+PLATFORM=local \
+YML_NAME="./ymls/browserstack/web/TOASTER_CHECK.yml" \
+SUITE="./web_suites/Login_RD.js" \
+npx wdio ./froth_configs/wdio.common.conf.js
+
+# ✅ Report generates automatically after execution completes!
+# 📍 Location: ./reports/mochawesome/Web_Login_Test_20250619-2025-06-19/mochawesome.html
+```
+
+**Manual report generation (if needed):**
+```bash
+# Generate latest report manually
+npm run generate:report
+
+# Generate all available reports
+npm run generate:report:all
+```
+
+#### BrowserStack Execution Reports
+
+For BrowserStack execution, test results are tracked via the Froth TestOps API. The framework automatically:
+- Updates execution status for each test script
+- Calculates total execution time
+- Posts results back to TestOps via `updateScriptExecutionStatus` and `updateExecuitonDetails`
+- Tracks BrowserStack session information
+
+View detailed results and execution logs in your Froth TestOps dashboard using the `EXECUTION_ID`.
+
+### Running Tests
+
+Tests are run by specifying environment variables and the config file:
+
+**Local execution (using BrowserStack from local machine):**
+
+```bash
+EXECUTION_ID=12995 \
+ORGANISATION_DOMAIN_URL='https://api.frothtestops.com' \
+BROWSERSTACK_BUILD_NAME="Web_Build- api-module-testing_2345_20260619" \
+PLATFORM=local \
+YML_NAME="./ymls/browserstack/web/TOASTER_CHECK.yml" \
+SUITE="./web_suites/Login_RD.js" \
+API_TOKEN="" \
+CICD_RUN_ID=1 \
+npx wdio ./froth_configs/wdio.common.conf.js
+```
+
+**BrowserStack execution:**
+
+```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://api.frothtestops.com \
+npx wdio ./froth_configs/wdio.common.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
+
+```ini
+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` | `local` for local execution, `browserstack` or `browserstacklocal` for BrowserStack | `local` or `browserstack` |
+| `EXECUTION_ID` | Test execution ID from TestOps | `12995` |
+| `API_TOKEN` | Authentication token for TestOps API | `eyJhbG...` |
+| `ORGANISATION_DOMAIN_URL` | Froth TestOps API base URL | `https://api.frothtestops.com` |
+| `CICD_RUN_ID` | CI/CD pipeline run ID (optional) | `1` |
+| `BROWSERSTACK_BUILD_NAME` | Build name for BrowserStack session tracking | `Web_Build- api-module-testing_2345_20260619` |
+| `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
+- **PLATFORM variable:**
+   - Use `PLATFORM=local` when executing tests from your local machine (even when targeting BrowserStack devices)
+   - Use `PLATFORM=browserstack` or `PLATFORM=browserstacklocal` when running from BrowserStack infrastructure

package/allure-report-utils/allure-helper.js

@@ -0,0 +1,226 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Allure Helper Utility for WebDriverIO
+ * Provides methods to add steps, screenshots, and attachments to Allure reports
+ */
+
+class AllureHelper {
+    /**
+     * Add a step to the Allure report
+     * @param {string} name - Step name
+     * @param {Function} stepFn - Step function to execute
+     */
+    static async step(name, stepFn) {
+        const allure = require('@wdio/allure-reporter').default;
+
+        console.log(`📝 Step: ${name}`);
+
+        // Create a step in Allure
+        allure.startStep(name);
+
+        try {
+            // Execute the step function
+            await stepFn();
+            allure.endStep('passed');
+        } catch (error) {
+            allure.endStep('failed');
+            throw error;
+        }
+    }
+
+    /**
+     * Add a description step
+     * @param {string} text - Description text
+     */
+    static description(text) {
+        const allure = require('@wdio/allure-reporter').default;
+        console.log(`📄 ${text}`);
+    }
+
+    /**
+     * Capture and attach screenshot to Allure report
+     * @param {string} screenshotName - Name for the screenshot
+     */
+    static async captureScreenshot(screenshotName = 'screenshot') {
+        try {
+            // Ensure screenshot directory exists
+            const screenshotDir = './allure-screenshots';
+            if (!fs.existsSync(screenshotDir)) {
+                fs.mkdirSync(screenshotDir, { recursive: true });
+            }
+
+            // Take screenshot and save to file
+            const screenshotPath = path.join(screenshotDir, `${screenshotName}.png`);
+            await browser.saveScreenshot(screenshotPath);
+
+            // Read the screenshot
+            if (fs.existsSync(screenshotPath)) {
+                const imageBuffer = fs.readFileSync(screenshotPath);
+
+                // Attach to Allure using the proper method
+                const allure = require('@wdio/allure-reporter').default;
+                allure.addAttachment(screenshotName, imageBuffer, 'image/png');
+
+                console.log(`📸 Screenshot captured: ${screenshotName}`);
+            } else {
+                console.warn(`⚠️  Screenshot file not found: ${screenshotPath}`);
+            }
+        } catch (error) {
+            console.error(`❌ Error capturing screenshot: ${error.message}`);
+        }
+    }
+
+    /**
+     * Add text attachment to Allure report
+     * @param {string} name - Attachment name
+     * @param {string} text - Text content
+     * @param {string} mimeType - MIME type (default: text/plain)
+     */
+    static addAttachment(name, text, mimeType = 'text/plain') {
+        const allure = require('@wdio/allure-reporter').default;
+        allure.addAttachment(name, text, mimeType);
+        console.log(`📎 Attachment added: ${name}`);
+    }
+
+    /**
+     * Add severity level to test
+     * @param {string} level - Severity level (blocker, critical, normal, minor, trivial)
+     */
+    static severity(level = 'normal') {
+        const allure = require('@wdio/allure-reporter').default;
+        allure.addArgument('severity', level);
+        console.log(`🔖 Severity: ${level}`);
+    }
+
+    /**
+     * Add epic label
+     * @param {string} epic - Epic name
+     */
+    static epic(epic) {
+        const allure = require('@wdio/allure-reporter').default;
+        allure.addArgument('epic', epic);
+        console.log(`📚 Epic: ${epic}`);
+    }
+
+    /**
+     * Add feature label
+     * @param {string} feature - Feature name
+     */
+    static feature(feature) {
+        const allure = require('@wdio/allure-reporter').default;
+        allure.addArgument('feature', feature);
+        console.log(`⭐ Feature: ${feature}`);
+    }
+
+    /**
+     * Add story label
+     * @param {string} story - Story name
+     */
+    static story(story) {
+        const allure = require('@wdio/allure-reporter').default;
+        allure.addArgument('story', story);
+        console.log(`📖 Story: ${story}`);
+    }
+
+    /**
+     * Add test ID/TC tag
+     * @param {string} testId - Test ID
+     */
+    static testId(testId) {
+        const allure = require('@wdio/allure-reporter').default;
+        allure.addArgument('testId', testId);
+        console.log(`🏷️  Test ID: ${testId}`);
+    }
+
+    /**
+     * Capture screenshot on test failure
+     */
+    static async captureOnFailure() {
+        const allure = require('@wdio/allure-reporter').default;
+
+        try {
+            const testName = expect.getState().currentTestName || 'test';
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const screenshotName = `${testName}-failure-${timestamp}`;
+
+            await this.captureScreenshot(screenshotName);
+        } catch (error) {
+            console.error(`❌ Error capturing failure screenshot: ${error.message}`);
+        }
+    }
+
+    /**
+     * Add environment information to report
+     * @param {object} envInfo - Environment information object
+     */
+    static addEnvironment(envInfo) {
+        const allure = require('@wdio/allure-reporter').default;
+
+        Object.entries(envInfo).forEach(([key, value]) => {
+            allure.addArgument(`env:${key}`, value);
+            console.log(`🌍 Environment: ${key} = ${value}`);
+        });
+    }
+
+    /**
+     * Log text as a step
+     * @param {string} message - Log message
+     */
+    static log(message) {
+        const allure = require('@wdio/allure-reporter').default;
+        allure.addStep(message);
+        console.log(`📝 ${message}`);
+    }
+
+    /**
+     * Take a screenshot and attach it as an attachment (simpler method)
+     * @param {string} name - Attachment name
+     */
+    static async attachScreenshot(name = 'screenshot') {
+        try {
+            // Take screenshot to buffer
+            const screenshot = await browser.takeScreenshot();
+
+            // Attach directly to Allure
+            const allure = require('@wdio/allure-reporter').default;
+            const buffer = Buffer.from(screenshot, 'base64');
+            allure.addAttachment(name, buffer, 'image/png');
+
+            console.log(`📸 Screenshot attached: ${name}`);
+        } catch (error) {
+            console.error(`❌ Error attaching screenshot: ${error.message}`);
+        }
+    }
+
+    /**
+     * Add screenshot attachment with detailed logging
+     * @param {string} stepName - Name of the current step
+     * @param {string} description - Description of what the screenshot shows
+     */
+    static async screenshot(stepName, description = 'Screenshot') {
+        try {
+            const allure = require('@wdio/allure-reporter').default;
+
+            // Start step if not already in one
+            allure.startStep(description);
+
+            // Take screenshot
+            const screenshot = await browser.takeScreenshot();
+            const buffer = Buffer.from(screenshot, 'base64');
+
+            // Attach screenshot to the step
+            allure.addAttachment(description, buffer, 'image/png');
+
+            // End the step
+            allure.endStep('passed');
+
+            console.log(`📸 Screenshot attached for step: ${stepName}`);
+        } catch (error) {
+            console.error(`❌ Error with screenshot: ${error.message}`);
+        }
+    }
+}
+
+module.exports = AllureHelper;

package/allure-report-utils/froth-report.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+/**
+ * Froth Allure Report CLI
+ * Usage:
+ *   npx froth-report open       - Open the latest Allure report in browser
+ *   npx froth-report generate   - Generate Allure HTML report from results
+ *   npx froth-report            - Shows help
+ *
+ * Works from any project folder that has the framework installed.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Commands
+const command = process.argv[2];
+
+function showHelp() {
+    console.log(`
+🎯 Froth Allure Report CLI
+============================
+
+Usage:
+  npx froth-report open        Open the latest Allure report in browser (http://localhost:8080)
+  npx froth-report generate    Generate Allure HTML report from test results
+  npx froth-report help        Show this help message
+
+Examples:
+  npx froth-report open
+  npx froth-report generate
+
+The report must be in: ./reports/allure/ (relative to current folder)
+`);
+}
+
+function findLatestReport() {
+    const REPORTS_DIR = './reports/allure';
+    if (!fs.existsSync(REPORTS_DIR)) {
+        return null;
+    }
+
+    const directories = fs.readdirSync(REPORTS_DIR)
+        .map(file => path.join(REPORTS_DIR, file))
+        .filter(file => fs.statSync(file).isDirectory())
+        .filter(file => {
+            // Check if any subdirectory ending with _report exists
+            try {
+                const subdirs = fs.readdirSync(file)
+                    .map(sub => path.join(file, sub))
+                    .filter(sub => {
+                        const stat = fs.statSync(sub);
+                        return stat.isDirectory() && path.basename(sub).endsWith('_report');
+                    });
+                return subdirs.length > 0;
+            } catch (e) {
+                return false;
+            }
+        })
+        .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+
+    return directories.length > 0 ? directories[0] : null;
+}
+
+function openReport() {
+    const reportDir = findLatestReport();
+
+    if (!reportDir) {
+        console.log('❌ No Allure HTML reports found.');
+        console.log('💡 Run tests first. Reports are generated in: ./reports/allure/');
+        console.log('💡 Or generate manually: npx froth-report generate');
+        process.exit(1);
+    }
+
+    // Find the report folder ending with _report
+    const reportSubdirs = fs.readdirSync(reportDir)
+        .map(sub => path.join(reportDir, sub))
+        .filter(sub => {
+            const stat = fs.statSync(sub);
+            return stat.isDirectory() && path.basename(sub).endsWith('_report');
+        });
+
+    if (reportSubdirs.length === 0) {
+        console.log('❌ No HTML report found in:', reportDir);
+        console.log('💡 Generate it first: npx froth-report generate');
+        process.exit(1);
+    }
+
+    const htmlReportPath = reportSubdirs[0];
+    const indexPath = path.join(htmlReportPath, 'index.html');
+
+    console.log('🎯 Opening Allure Report');
+    console.log('========================\n');
+    console.log(`📁 Report location: ${htmlReportPath}`);
+    console.log(`🏷️  Build: ${path.basename(reportDir)}\n`);
+    console.log('🌐 Opening report in browser on http://localhost:8080');
+    console.log('💡 Press Ctrl+C to stop the server\n');
+
+    try {
+        execSync(`npx allure open ${htmlReportPath} --port 8080`, { stdio: 'inherit' });
+    } catch (error) {
+        console.error(`❌ Error opening report: ${error.message}`);
+        console.log(`\n💡 To view manually, open: file://${path.resolve(indexPath)}`);
+    }
+}
+
+function generateReport() {
+    // Run the generate-allure-report.js script
+    const scriptPath = path.resolve(__dirname, 'generate-allure-report.js');
+
+    if (!fs.existsSync(scriptPath)) {
+        console.log('❌ Report generator script not found:', scriptPath);
+        process.exit(1);
+    }
+
+    try {
+        execSync(`node "${scriptPath}"`, { stdio: 'inherit' });
+    } catch (error) {
+        console.error(`❌ Error generating report: ${error.message}`);
+        process.exit(1);
+    }
+}
+
+// Main
+switch (command) {
+    case 'open':
+        openReport();
+        break;
+    case 'generate':
+        generateReport();
+        break;
+    case 'help':
+    case '--help':
+    case '-h':
+        showHelp();
+        break;
+    default:
+        console.log('\n🎯 Froth Allure Report CLI\n');
+        showHelp();
+        break;
+}