wdio-lambdatest-service-sdk 5.0.0 → 5.1.1

package/README.md

@@ -1,38 +1,317 @@
 # WDIO LambdaTest Service
 
-This WebdriverIO service provides seamless integration with LambdaTest. It automatically handles:
+WebdriverIO service and CLI for running Appium and browser tests on [LambdaTest](https://www.lambdatest.com). This SDK handles authentication, test status updates on the LambdaTest dashboard, and provides an interactive CLI to generate and setup WDIO configs that connect directly to LambdaTest automation.
 
-1.  **Authentication**: Pass `username` and `accessKey` in the service options.
-2.  **Test Status Updates**: Automatically marks tests as Passed/Failed on the LambdaTest dashboard using Lambda Hooks.
-3.  **Logs**: Provides clean, colorful status logs in the terminal.
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Try the SDK / CLI with the Sample Project](#try-the-sdk--cli-with-the-sample-project)
+- [Steps to Run the Sample Project](#steps-to-run-the-sample-project)
+- [Specs Folder & Code Design](#specs-folder--code-design)
+- [Generate Config That Connects to LT Automation](#generate-config-that-connects-to-lt-automation)
+- [CLI Commands](#cli-commands)
+- [Automated Setup](#automated-setup)
+- [Config Generator](#config-generator)
+- [Manual Configuration](#manual-configuration)
+- [Development](#development)
+- [License](#license)
+
+---
+
+## Features
+
+- **Authentication**: Pass `username` and `accessKey` in the service options or via the CLI.
+- **Test Status Updates**: Automatically marks tests as Passed/Failed on the LambdaTest dashboard using Lambda Hooks.
+- **Logs**: Clean, colorful status logs in the terminal.
+- **CLI**: Interactive config generator and setup tool (Commander, Chalk, Inquirer; runs with Bun or Node.js).
+- **Multi-select**: Choose multiple test types, device types, platforms, and app/website targets in one config.
+
+---
 
 ## Installation
 
 ```bash
 npm install wdio-lambdatest-service --save-dev
+# or with Bun
+bun add wdio-lambdatest-service --dev
 ```
 
-*(For local development, you can link the package or use the setup script described below)*
+---
 
-## Automated Setup
+## Try the SDK / CLI with the Sample Project
+
+To verify the SDK and CLI work end-to-end, clone the official LambdaTest sample project and run tests using this service.
+
+### 1. Clone the Sample Repository
+
+```bash
+git clone https://github.com/LambdaTest/LT-appium-nodejs-webdriverio
+cd LT-appium-nodejs-webdriverio
+```
+
+This repo contains:
+
+- **android-sample/** – WebdriverIO + Appium configs and scripts for Android (real/virtual).
+- **ios-sample/** – WebdriverIO + Appium configs and scripts for iOS.
+- **specs/** – Shared test specs (e.g. `android-test.js`, `ios-test.js`) used by both samples.
+
+### 2. Install the WDIO LambdaTest Service (SDK)
+
+From the **repo root** (or from inside `android-sample` / `ios-sample` if you prefer):
+
+```bash
+# From repo root – install SDK as dev dependency
+npm install ./wdio-lambdatest-service --save-dev
+# or, if the SDK is published:
+npm install wdio-lambdatest-service
+```
+
+### 3. Set LambdaTest Credentials
+
+Export your [LambdaTest](https://accounts.lambdatest.com) username and access key:
+
+**Linux / macOS:**
+
+```bash
+export LT_USERNAME="your_username"
+export LT_ACCESS_KEY="your_access_key"
+```
+
+**Windows (CMD):**
+
+```cmd
+set LT_USERNAME=your_username
+set LT_ACCESS_KEY=your_access_key
+```
+
+**Windows (PowerShell):**
+
+```powershell
+$env:LT_USERNAME = "your_username"
+$env:LT_ACCESS_KEY = "your_access_key"
+```
+
+### 4. Run the Sample Project
+
+See [Steps to Run the Sample Project](#steps-to-run-the-sample-project) below for detailed run commands (single/parallel, Android/iOS).
+
+---
+
+## Steps to Run the Sample Project
+
+After cloning [LT-appium-nodejs-webdriverio](https://github.com/LambdaTest/LT-appium-nodejs-webdriverio) and setting credentials:
+
+### Android
+
+```bash
+cd android-sample
+npm install
+# Single test
+npm run SingleAndroidApp
+# Or run parallel (if defined in package.json)
+npm run parallel
+```
+
+### iOS
+
+```bash
+cd ios-sample
+npm install
+# Single test (script name may vary, e.g. SingleIosApp)
+npm run single
+# Or run parallel
+npm run parallel
+```
+
+**Note:** Ensure config files in `android-sample` and `ios-sample` point to the correct spec paths (e.g. `../specs/android-test.js`, `../specs/ios-test.js`) and that the WDIO LambdaTest service is registered in `services` in those configs. Test results appear in the terminal and on the [LambdaTest App Automation Dashboard](https://appautomation.lambdatest.com/).
+
+---
+
+## Specs Folder & Code Design
+
+The sample repo uses a **shared `specs/` folder** at the root so both Android and iOS (and any generated configs) can reuse the same test files.
+
+Recommended layout (align with the sample repo):
+
+```
+LT-appium-nodejs-webdriverio/
+├── android-sample/
+│   ├── conf/                 # or *.conf.js in root of android-sample
+│   │   └── android.conf.js
+│   ├── package.json
+│   └── ...
+├── ios-sample/
+│   ├── conf/
+│   │   └── ios.conf.js
+│   ├── package.json
+│   └── ...
+├── specs/                    # Shared test specs
+│   ├── android-test.js
+│   ├── ios-test.js
+│   └── (your own specs)
+├── wdio-lambdatest-service/  # This SDK (if developed locally)
+└── package.json
+```
+
+**Design guidelines:**
+
+- **One spec file per flow or platform** (e.g. `android-test.js`, `ios-test.js`, `web-test.js`) so configs can reference them clearly.
+- **Use `specs: ["../specs/android-test.js"]`** (or similar relative path) in configs under `android-sample` so they point to the shared `specs/` folder.
+- **Keep assertions and page interactions in the specs**; keep capabilities and environment in the config files.
+- **Reuse the same spec** across different configs (e.g. single device vs parallel) by only changing the config, not the spec.
+
+Following this structure makes it easy to add new configs (including those generated by `wdio-lt generate`) that point to the same `specs/` folder.
+
+---
+
+## Generate Config That Connects to LT Automation
+
+Use the CLI to generate a WDIO config that is **already wired to LambdaTest** (hostname, path, services, and capabilities).
+
+### 1. Install the CLI
+
+If the SDK is in the repo:
+
+```bash
+cd LT-appium-nodejs-webdriverio
+npm install ./wdio-lambdatest-service --save-dev
+```
+
+Or install from npm (when published):
 
-You can automatically update your existing WebdriverIO configuration files (`*.conf.js`) to use this SDK using the included setup script.
+```bash
+npm install wdio-lambdatest-service --save-dev
+```
 
-Run the following command, providing the path to your project or test folder:
+### 2. Run the Config Generator
 
 ```bash
-# If installed via npm
-npx wdio-lambdatest-setup ./path/to/your/project
+# With Bun (recommended)
+bun wdio-lt generate
 
-# If running locally from source
-node wdio-lambdatest-service/bin/setup.js ./android-sample
+# With Node.js
+npx wdio-lt generate
 ```
 
-This script will:
--   Scan for `.conf.js` files recursively.
--   Inject the service configuration.
--   Set `logLevel` to `error` for cleaner output.
--   Comment out hardcoded credentials (so the SDK handles them).
+### 3. Follow the Prompts
+
+- **Test name** – Used for build name and config filename.
+- **LambdaTest Username & Access Key** – Stored in the generated config (or use env vars and leave blank if you rely on `LT_USERNAME` / `LT_ACCESS_KEY`).
+- **Test type(s)** – App Testing (Mobile) and/or Browser Testing (Desktop). You can select multiple.
+- **Device type(s)** – Real Device, Virtual Device (for App Testing). Multi-select.
+- **Platform(s)** – Android, iOS. Multi-select.
+- **What do you want to test?** – Application (Native App), Website (Mobile Browser). Multi-select.
+- **App ID(s)** – If you chose native app, enter the App URL (e.g. `lt://APP123456789`) per platform; you can use sample apps (e.g. `lt://proverbial-android`, `lt://proverbial-ios`).
+- **Parallel threads** – 0 for sequential, or a number for parallel.
+- **Spec file path** – Path to your test file, e.g. `./specs/test.js` or `../specs/android-test.js` relative to the generated config location.
+
+### 4. Generated Output
+
+The CLI writes:
+
+- **Config file:** `LT_Test/<TestName>.conf.js` – Ready to run against LambdaTest (hostname, path, services, and capabilities set).
+- **Package script:** In `LT_Test/package.json`, a script like `test:<TestName>` is added.
+
+### 5. Run the Generated Config
+
+```bash
+cd LT_Test
+npm install   # if needed
+npm run test:<TestName>
+# or
+npx wdio <TestName>.conf.js
+```
+
+To follow the same code design as the sample repo, set the **spec file path** during `wdio-lt generate` to your existing `specs/` folder, e.g. `../specs/android-test.js`, so the generated config reuses your shared specs.
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|--------|-------------|
+| `wdio-lt setup [path]` | Inject LambdaTest service into existing WDIO config files |
+| `wdio-lt generate` | Interactively generate a new WDIO config for LambdaTest |
+| `wdio-lt init` | Alias for `generate` |
+| `wdio-lt --help` | Show help |
+| `wdio-lt --version` | Show version |
+
+### Examples
+
+```bash
+# Setup – inject service into all .conf.js files in a directory
+wdio-lt setup ./android-sample
+
+# Setup – interactive mode (prompts for directory)
+wdio-lt setup
+
+# Generate – create a new config interactively
+wdio-lt generate
+```
+
+### Running with Bun
+
+```bash
+curl -fsSL https://bun.sh/install | bash   # Install Bun
+bun wdio-lt setup ./android-sample
+bun wdio-lt generate
+```
+
+### Running with Node.js
+
+```bash
+npx wdio-lt setup ./android-sample
+npx wdio-lt generate
+```
+
+### Legacy Commands (backward compatible)
+
+```bash
+wdio-lambdatest-setup ./android-sample
+wdio-lambdatest-generator
+```
+
+---
+
+## Automated Setup
+
+The `setup` command updates existing WebdriverIO config files (`*.conf.js`) to use this SDK:
+
+```bash
+wdio-lt setup ./path/to/your/project
+```
+
+It will:
+
+- Scan for `.conf.js` files recursively.
+- Inject the service configuration.
+- Set `logLevel` to `error` for cleaner output.
+- Comment out hardcoded credentials so the SDK can use env vars or service options.
+
+---
+
+## Config Generator
+
+The `generate` command creates a new WDIO config with interactive prompts:
+
+```bash
+wdio-lt generate
+```
+
+Features:
+
+- Test name with validation
+- LambdaTest username and access key (secure input)
+- **Multi-select:** Test type(s), Device type(s), Platform(s), What to test (App / Website)
+- App ID(s) per platform when testing native apps
+- Parallel threads and spec file path with smart resolution
+
+Generated configs are saved to `./LT_Test/<testName>.conf.js`.
+
+---
 
 ## Manual Configuration
 
@@ -42,39 +321,63 @@ Add the service to your `wdio.conf.js`:
 const path = require('path');
 
 exports.config = {
-    // ...
-    // user: process.env.LT_USERNAME, // handled by SDK
-    // key: process.env.LT_ACCESS_KEY, // handled by SDK
-    
-    logLevel: 'error', // Recommended to reduce noise
-    
+    // user / key can be omitted if using service options or env
+    logLevel: 'error',
+
     services: [
-        ['lambdatest', {
-            username: process.env.LT_USERNAME,
-            accessKey: process.env.LT_ACCESS_KEY
+        [path.join(__dirname, 'node_modules/wdio-lambdatest-service'), {
+            user: process.env.LT_USERNAME,
+            key: process.env.LT_ACCESS_KEY
         }]
     ],
     // ...
 };
 ```
 
-If you are using the SDK locally (without npm install), use the absolute path:
+If using the SDK from a local path (e.g. repo root):
 
 ```javascript
     services: [
-        [path.join(__dirname, '../../wdio-lambdatest-service'), {
-            username: process.env.LT_USERNAME,
-            accessKey: process.env.LT_ACCESS_KEY
+        [path.join(__dirname, '../wdio-lambdatest-service'), {
+            user: process.env.LT_USERNAME,
+            key: process.env.LT_ACCESS_KEY
         }]
     ],
 ```
 
-## Features
-
--   **Automatic Status Updates**: Checks test results in `afterTest` (Mocha/Jasmine) or `afterScenario` (Cucumber) and updates the LambdaTest job status.
--   **Credential Management**: Can inject credentials if not already present in the main config.
--   **Async Support**: Works seamlessly with both Sync and Async WebdriverIO execution modes.
+---
 
 ## Development
 
-This package exports a **Service** (worker) and a **Launcher** (main process).
+This package provides a **Service** (worker) and a **Launcher** (main process) for WebdriverIO.
+
+### Project Structure
+
+```
+wdio-lambdatest-service/
+├── bin/
+│   ├── cli.js              # Main CLI entry (Commander)
+│   ├── setup.js            # Setup command wrapper
+│   └── generate-config.js  # Generate command wrapper
+├── lib/
+│   └── cli/
+│       ├── style.js        # Chalk style utilities
+│       ├── setup.js        # Setup logic
+│       └── generate.js     # Generate logic (Inquirer prompts)
+├── src/
+│   ├── launcher.js         # WDIO Launcher
+│   └── service.js          # WDIO Service
+├── index.js                # Main entry point
+└── package.json
+```
+
+### Requirements
+
+- **Node.js**: >= 18.0.0
+- **Bun**: >= 1.0.0 (optional, for faster CLI)
+
+---
+
+## License
+
+ISC

package/bin/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env bun
+/**
+ * LambdaTest WDIO CLI - Unified command-line interface.
+ * Powered by Commander, Chalk, and Inquirer.
+ * Runs with Bun (fast) or Node.js.
+ */
+const { Command } = require('commander');
+const chalk = require('chalk');
+const { runSetup } = require('../lib/cli/setup');
+const { runGenerate } = require('../lib/cli/generate');
+const pkg = require('../package.json');
+
+const program = new Command();
+
+// ASCII Art Logo
+const logo = `
+${chalk.cyan('╔═══════════════════════════════════════════════════════════╗')}
+${chalk.cyan('║')}  ${chalk.bold.white('🚀 LambdaTest WDIO CLI')}                                   ${chalk.cyan('║')}
+${chalk.cyan('║')}  ${chalk.dim('Fast, powerful WebdriverIO configuration tool')}            ${chalk.cyan('║')}
+${chalk.cyan('╚═══════════════════════════════════════════════════════════╝')}
+`;
+
+program
+    .name('wdio-lt')
+    .description(chalk.dim('LambdaTest WebdriverIO CLI - Setup and configure WDIO projects'))
+    .version(pkg.version, '-v, --version', 'Display version number')
+    .helpOption('-h, --help', 'Display help for command')
+    .addHelpText('before', logo)
+    .addHelpText('after', `
+${chalk.bold('Examples:')}
+  ${chalk.green('$')} wdio-lt setup ./android-sample   ${chalk.dim('# Inject service into configs')}
+  ${chalk.green('$')} wdio-lt setup                    ${chalk.dim('# Interactive mode')}
+  ${chalk.green('$')} wdio-lt generate                 ${chalk.dim('# Create new config')}
+  ${chalk.green('$')} wdio-lt init                     ${chalk.dim('# Alias for generate')}
+
+${chalk.bold('Documentation:')}
+  ${chalk.cyan('https://github.com/LambdaTest')}
+`);
+
+// Setup command
+program
+    .command('setup [path]')
+    .description('Inject LambdaTest service into existing WDIO config files')
+    .action(async (targetPath) => {
+        try {
+            await runSetup(targetPath);
+        } catch (e) {
+            console.error(chalk.red.bold('\n✖ Error:'), e.message);
+            process.exit(1);
+        }
+    });
+
+// Generate command
+program
+    .command('generate')
+    .alias('gen')
+    .description('Interactively generate a new WDIO config for LambdaTest')
+    .action(async () => {
+        try {
+            await runGenerate();
+        } catch (e) {
+            console.error(chalk.red.bold('\n✖ Error:'), e.message);
+            process.exit(1);
+        }
+    });
+
+// Init command (alias for generate)
+program
+    .command('init')
+    .description('Create a new WDIO config (alias for generate)')
+    .action(async () => {
+        try {
+            await runGenerate();
+        } catch (e) {
+            console.error(chalk.red.bold('\n✖ Error:'), e.message);
+            process.exit(1);
+        }
+    });
+
+// Parse arguments
+program.parse();
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+}

package/bin/generate-config.js

@@ -1,167 +1,15 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-const readline = require('readline');
-
-const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-});
-
-const config = {
-    testName: '',
-    filename: '',
-    username: '',
-    key: '',
-    type: '', // 'app' or 'browser'
-    subType: '', // 'real', 'virtual', 'desktop', 'mobile-virtual', 'mobile-real'
-    parallel: 0,
-    specPath: ''
-};
-
-const outputDir = path.resolve(process.cwd(), 'LT_Test');
-
-// Ensure output dir exists
-if (!fs.existsSync(outputDir)) {
-    fs.mkdirSync(outputDir, { recursive: true });
-}
-
-function ask(question, defaultVal) {
-    return new Promise((resolve) => {
-        rl.question(`${question}${defaultVal ? ` (${defaultVal})` : ''}: `, (answer) => {
-            resolve(answer.trim() || defaultVal);
-        });
+#!/usr/bin/env bun
+/**
+ * LambdaTest WDIO Config Generator - Backward-compatible entry point.
+ * Delegates to lib/cli/generate.js
+ * 
+ * Usage: wdio-lambdatest-generator
+ */
+const chalk = require('chalk');
+const { runGenerate } = require('../lib/cli/generate');
+
+runGenerate()
+    .catch((e) => {
+        console.error(chalk.red.bold('\n✖ Error:'), e.message);
+        process.exit(1);
     });
-}
-
-async function run() {
-    console.log('\n--- LambdaTest WDIO Config Generator ---\n');
-
-    config.testName = await ask('Enter Test Name (e.g. AndroidAppTest)', 'AndroidAppTest');
-    config.filename = `${config.testName}.conf.js`;
-
-    config.username = await ask('Enter LambdaTest Username', process.env.LT_USERNAME || 'YOUR_USERNAME');
-    config.key = await ask('Enter LambdaTest Access Key', process.env.LT_ACCESS_KEY || 'YOUR_ACCESS_KEY');
-
-    const typeInput = await ask('Test Type (1: App, 2: Browser)', '1');
-    config.type = typeInput === '1' || typeInput.toLowerCase() === 'app' ? 'app' : 'browser';
-
-    if (config.type === 'app') {
-        const subTypeInput = await ask('Device Type (1: Real Device, 2: Virtual Device)', '1');
-        config.subType = subTypeInput === '1' ? 'real' : 'virtual';
-    } else {
-        console.log('Browser Options: 1: Desktop, 2: Mobile Browser (Virtual), 3: Mobile Browser (Real)');
-        const subTypeInput = await ask('Select Option', '1');
-        if (subTypeInput === '2') config.subType = 'mobile-virtual';
-        else if (subTypeInput === '3') config.subType = 'mobile-real';
-        else config.subType = 'desktop';
-    }
-
-    const parallelInput = await ask('Number of Parallel Threads (0 or empty for no parallel)', '0');
-    config.parallel = parseInt(parallelInput) || 0;
-
-    config.specPath = await ask('Path to Spec File (e.g. ./specs/test.js)', './specs/android-test.js');
-
-    // Generate Config Content
-    let capabilities = [];
-    const commonCaps = {
-        build: `LT_WDIO_${config.testName}_${new Date().toISOString().split('T')[0]}`,
-        name: config.testName,
-        visual: true,
-        console: true
-    };
-
-    if (config.type === 'app') {
-        const cap = {
-            "lt:options": {
-                w3c: true,
-                platformName: "Android",
-                deviceName: config.subType === 'real' ? ".*" : "Pixel 4",
-                platformVersion: config.subType === 'real' ? undefined : "11",
-                isRealMobile: config.subType === 'real',
-                app: process.env.LT_APP_ID || "lt://proverbial-android", // Default app
-            }
-        };
-        capabilities.push(cap);
-    } else {
-        if (config.subType === 'desktop') {
-            capabilities.push({
-                browserName: "chrome",
-                browserVersion: "latest",
-                "lt:options": {
-                    platformName: "Windows 10"
-                }
-            });
-        } else {
-            // Mobile Browser
-            capabilities.push({
-                "lt:options": {
-                    w3c: true,
-                    platformName: "Android",
-                    deviceName: config.subType === 'mobile-real' ? ".*" : "Pixel 4",
-                    platformVersion: config.subType === 'mobile-real' ? undefined : "11",
-                    isRealMobile: config.subType === 'mobile-real',
-                }
-            });
-        }
-    }
-
-    // Prepare template
-    const template = `const path = require('path');
-
-exports.config = {
-    // Authentication handled by SDK
-    // user: "${config.username}",
-    // key: "${config.key}",
-
-    updateJob: false,
-    specs: ["${config.specPath}"],
-    exclude: [],
-
-    maxInstances: ${config.parallel > 0 ? config.parallel : 1},
-
-    commonCapabilities: ${JSON.stringify(commonCaps, null, 4)},
-
-    capabilities: ${JSON.stringify(capabilities, null, 4)},
-
-    logLevel: 'error',
-    coloredLogs: true,
-    screenshotPath: "./errorShots/",
-    baseUrl: "https://mobile-hub.lambdatest.com",
-    waitforTimeout: 10000,
-    connectionRetryTimeout: 90000,
-    connectionRetryCount: 3,
-    path: "/wd/hub",
-    hostname: "mobile-hub.lambdatest.com",
-    port: 80,
-
-    services: [
-        [path.join(__dirname, '../wdio-lambdatest-service'), {
-            user: "${config.username}",
-            key: "${config.key}"
-        }]
-    ],
-
-    framework: "mocha",
-    mochaOpts: {
-        ui: "bdd",
-        timeout: 20000,
-    },
-};
-
-exports.config.capabilities.forEach(function (caps) {
-    for (var i in exports.config.commonCapabilities)
-        caps[i] = caps[i] || exports.config.commonCapabilities[i];
-});
-`;
-
-    const outputPath = path.join(outputDir, config.filename);
-    fs.writeFileSync(outputPath, template);
-    
-    console.log(`\nSuccessfully created configuration file at:\n${outputPath}`);
-    console.log(`\nRun it with:\n./node_modules/.bin/wdio ${path.relative(process.cwd(), outputPath)}`);
-    
-    rl.close();
-}
-
-run();