ai-qakit 1.0.0

package/templates/.claude/commands/qakit/automation/scaffold-webdriverio.md

@@ -0,0 +1,802 @@
+# Scaffold WebdriverIO Project
+
+Generate a complete WebdriverIO test automation project for Web and Mobile testing following Enouvo QA standards.
+
+## Usage
+
+```
+/qakit:automation/scaffold-webdriverio [--type=web|mobile|full]
+```
+
+## Instructions
+
+### Step 1: Create Project Structure
+
+Generate the following structure:
+
+```
+test/
+├── specs/                          # Test specifications
+│   ├── web/
+│   │   ├── auth/
+│   │   │   ├── login.spec.ts
+│   │   │   └── logout.spec.ts
+│   │   └── smoke/
+│   │       └── smoke.spec.ts
+│   ├── android/
+│   │   ├── auth/
+│   │   │   └── login.spec.ts
+│   │   └── smoke/
+│   │       └── smoke.spec.ts
+│   └── ios/
+│       ├── auth/
+│       │   └── login.spec.ts
+│       └── smoke/
+│           └── smoke.spec.ts
+├── pageObjects/                    # Page Object Model
+│   ├── commons/
+│   │   ├── base.page.ts
+│   │   └── base.mobile.page.ts
+│   ├── web/
+│   │   ├── login/
+│   │   │   ├── login.page.ts
+│   │   │   ├── selectors.ts
+│   │   │   └── index.ts
+│   │   └── dashboard/
+│   │       └── dashboard.page.ts
+│   ├── android/
+│   │   └── login/
+│   │       ├── login.page.ts
+│   │       └── selectors.ts
+│   └── ios/
+│       └── login/
+│           ├── login.page.ts
+│           └── selectors.ts
+├── support/                        # Utilities
+│   ├── capabilities/
+│   │   ├── android.caps.ts
+│   │   ├── ios.caps.ts
+│   │   ├── web.caps.ts
+│   │   └── browserstack.caps.ts
+│   ├── helpers/
+│   │   ├── gesture.helper.ts
+│   │   ├── scroll.helper.ts
+│   │   ├── wait.helper.ts
+│   │   ├── api.helper.ts
+│   │   └── index.ts
+│   ├── hooks/
+│   │   └── global.hooks.ts
+│   ├── reporters/
+│   │   └── slack.reporter.ts
+│   ├── specs.ts                    # Spec selectors
+│   └── env.ts                      # Environment config
+├── data/
+│   ├── users.json
+│   └── fixtures/
+└── reports/
+    └── .gitkeep
+
+config/
+├── wdio.common.conf.ts             # Base config
+├── wdio.web.conf.ts                # Web config
+├── wdio.android.conf.ts            # Android config
+├── wdio.ios.conf.ts                # iOS config
+├── wdio.browserstack.web.conf.ts   # BrowserStack Web
+├── wdio.browserstack.android.conf.ts
+└── wdio.browserstack.ios.conf.ts
+
+scripts/
+├── run-suite.ts
+├── upload-app.ts
+└── config-doctor.ts
+
+apps/                               # Mobile app files
+├── android/
+│   └── .gitkeep
+└── ios/
+    └── .gitkeep
+
+.env.example
+.gitignore
+tsconfig.json
+package.json
+README.md
+```
+
+### Step 2: Generate Core Files
+
+#### Base Page - Web (test/pageObjects/commons/base.page.ts)
+
+```typescript
+export class BasePage {
+  /**
+   * Wait for element to be displayed
+   */
+  async waitForDisplayed(element: WebdriverIO.Element, timeout = 10000): Promise<void> {
+    await element.waitForDisplayed({ timeout });
+  }
+
+  /**
+   * Wait for element to be clickable
+   */
+  async waitForClickable(element: WebdriverIO.Element, timeout = 10000): Promise<void> {
+    await element.waitForClickable({ timeout });
+  }
+
+  /**
+   * Safe click with wait
+   */
+  async safeClick(element: WebdriverIO.Element): Promise<void> {
+    await this.waitForClickable(element);
+    await element.click();
+  }
+
+  /**
+   * Safe setValue with clear
+   */
+  async safeSetValue(element: WebdriverIO.Element, value: string): Promise<void> {
+    await this.waitForDisplayed(element);
+    await element.clearValue();
+    await element.setValue(value);
+  }
+
+  /**
+   * Get text safely
+   */
+  async getText(element: WebdriverIO.Element): Promise<string> {
+    await this.waitForDisplayed(element);
+    return element.getText();
+  }
+
+  /**
+   * Check if element is displayed
+   */
+  async isDisplayed(element: WebdriverIO.Element): Promise<boolean> {
+    try {
+      return await element.isDisplayed();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Open URL
+   */
+  async open(path: string): Promise<void> {
+    await browser.url(path);
+  }
+
+  /**
+   * Wait for page load
+   */
+  async waitForPageLoad(): Promise<void> {
+    await browser.waitUntil(
+      async () => (await browser.execute(() => document.readyState)) === 'complete',
+      { timeout: 30000, timeoutMsg: 'Page did not load in time' }
+    );
+  }
+
+  /**
+   * Take screenshot
+   */
+  async screenshot(name: string): Promise<void> {
+    await browser.saveScreenshot(`./reports/screenshots/${name}-${Date.now()}.png`);
+  }
+}
+```
+
+#### Base Mobile Page (test/pageObjects/commons/base.mobile.page.ts)
+
+```typescript
+export class BaseMobilePage {
+  /**
+   * Wait for element to be displayed
+   */
+  async waitForDisplayed(element: WebdriverIO.Element, timeout = 15000): Promise<void> {
+    await element.waitForDisplayed({ timeout });
+  }
+
+  /**
+   * Safe tap with wait
+   */
+  async safeTap(element: WebdriverIO.Element): Promise<void> {
+    await this.waitForDisplayed(element);
+    await element.click();
+  }
+
+  /**
+   * Safe setValue for mobile
+   */
+  async safeSetValue(element: WebdriverIO.Element, value: string): Promise<void> {
+    await this.waitForDisplayed(element);
+    await element.clearValue();
+    await element.setValue(value);
+  }
+
+  /**
+   * Hide keyboard (mobile)
+   */
+  async hideKeyboard(): Promise<void> {
+    if (await driver.isKeyboardShown()) {
+      await driver.hideKeyboard();
+    }
+  }
+
+  /**
+   * Scroll to element (mobile)
+   */
+  async scrollToElement(selector: string, direction: 'up' | 'down' = 'down', maxScrolls = 5): Promise<void> {
+    let scrollCount = 0;
+    while (scrollCount < maxScrolls) {
+      try {
+        const element = await $(selector);
+        if (await element.isDisplayed()) {
+          return;
+        }
+      } catch {
+        // Element not found, continue scrolling
+      }
+
+      await this.scroll(direction);
+      scrollCount++;
+    }
+    throw new Error(`Element ${selector} not found after ${maxScrolls} scrolls`);
+  }
+
+  /**
+   * Scroll gesture
+   */
+  async scroll(direction: 'up' | 'down' | 'left' | 'right'): Promise<void> {
+    const { width, height } = await driver.getWindowSize();
+    const startX = width / 2;
+    const startY = height / 2;
+    
+    let endX = startX;
+    let endY = startY;
+
+    switch (direction) {
+      case 'up':
+        endY = height * 0.2;
+        break;
+      case 'down':
+        endY = height * 0.8;
+        break;
+      case 'left':
+        endX = width * 0.2;
+        break;
+      case 'right':
+        endX = width * 0.8;
+        break;
+    }
+
+    await driver.touchAction([
+      { action: 'press', x: startX, y: startY },
+      { action: 'wait', ms: 500 },
+      { action: 'moveTo', x: endX, y: endY },
+      { action: 'release' },
+    ]);
+  }
+
+  /**
+   * Swipe gesture
+   */
+  async swipe(startX: number, startY: number, endX: number, endY: number, duration = 500): Promise<void> {
+    await driver.touchAction([
+      { action: 'press', x: startX, y: startY },
+      { action: 'wait', ms: duration },
+      { action: 'moveTo', x: endX, y: endY },
+      { action: 'release' },
+    ]);
+  }
+
+  /**
+   * Take screenshot
+   */
+  async screenshot(name: string): Promise<void> {
+    await driver.saveScreenshot(`./reports/screenshots/${name}-${Date.now()}.png`);
+  }
+
+  /**
+   * Get platform
+   */
+  get isAndroid(): boolean {
+    return driver.isAndroid;
+  }
+
+  get isIOS(): boolean {
+    return driver.isIOS;
+  }
+}
+```
+
+#### Web Login Page (test/pageObjects/web/login/login.page.ts)
+
+```typescript
+import { BasePage } from '../../commons/base.page';
+
+class LoginPage extends BasePage {
+  // Selectors
+  get emailInput() { return $('[data-testid="email-input"]'); }
+  get passwordInput() { return $('[data-testid="password-input"]'); }
+  get submitButton() { return $('[data-testid="login-button"]'); }
+  get errorMessage() { return $('[data-testid="error-message"]'); }
+  get rememberMeCheckbox() { return $('[data-testid="remember-me"]'); }
+
+  // Actions
+  async open(): Promise<void> {
+    await super.open('/login');
+    await this.waitForPageLoad();
+  }
+
+  async login(email: string, password: string): Promise<void> {
+    await this.safeSetValue(await this.emailInput, email);
+    await this.safeSetValue(await this.passwordInput, password);
+    await this.safeClick(await this.submitButton);
+  }
+
+  async loginWithRememberMe(email: string, password: string): Promise<void> {
+    await this.safeSetValue(await this.emailInput, email);
+    await this.safeSetValue(await this.passwordInput, password);
+    await this.safeClick(await this.rememberMeCheckbox);
+    await this.safeClick(await this.submitButton);
+  }
+
+  // Getters
+  async getErrorMessage(): Promise<string> {
+    return this.getText(await this.errorMessage);
+  }
+
+  async isErrorDisplayed(): Promise<boolean> {
+    return this.isDisplayed(await this.errorMessage);
+  }
+
+  // Assertions
+  async expectErrorMessage(message: string): Promise<void> {
+    const error = await this.getErrorMessage();
+    expect(error).toContain(message);
+  }
+
+  async expectDashboard(): Promise<void> {
+    await browser.waitUntil(
+      async () => (await browser.getUrl()).includes('/dashboard'),
+      { timeout: 10000, timeoutMsg: 'Did not redirect to dashboard' }
+    );
+  }
+}
+
+export default new LoginPage();
+```
+
+#### Android Login Page (test/pageObjects/android/login/login.page.ts)
+
+```typescript
+import { BaseMobilePage } from '../../commons/base.mobile.page';
+
+class AndroidLoginPage extends BaseMobilePage {
+  // Selectors - using accessibility ID for cross-platform
+  get emailInput() { return $('~email-input'); }
+  get passwordInput() { return $('~password-input'); }
+  get submitButton() { return $('~login-button'); }
+  get errorMessage() { return $('~error-message'); }
+
+  // Alternative selectors using resource-id (Android specific)
+  get emailInputById() { return $('android=new UiSelector().resourceId("com.app:id/email_input")'); }
+  get passwordInputById() { return $('android=new UiSelector().resourceId("com.app:id/password_input")'); }
+
+  // Actions
+  async login(email: string, password: string): Promise<void> {
+    await this.safeSetValue(await this.emailInput, email);
+    await this.safeSetValue(await this.passwordInput, password);
+    await this.hideKeyboard();
+    await this.safeTap(await this.submitButton);
+  }
+
+  // Getters
+  async getErrorMessage(): Promise<string> {
+    await this.waitForDisplayed(await this.errorMessage);
+    return (await this.errorMessage).getText();
+  }
+
+  // Assertions
+  async expectErrorMessage(message: string): Promise<void> {
+    const error = await this.getErrorMessage();
+    expect(error).toContain(message);
+  }
+
+  async expectDashboard(): Promise<void> {
+    // Wait for dashboard element to appear
+    const dashboardElement = await $('~dashboard-header');
+    await this.waitForDisplayed(dashboardElement, 15000);
+  }
+}
+
+export default new AndroidLoginPage();
+```
+
+#### Capabilities - Android (test/support/capabilities/android.caps.ts)
+
+```typescript
+export const androidCapabilities = {
+  local: {
+    platformName: 'Android',
+    'appium:deviceName': process.env.ANDROID_DEVICE_NAME || 'Pixel_5_API_31',
+    'appium:platformVersion': process.env.ANDROID_PLATFORM_VERSION || '12.0',
+    'appium:automationName': 'UiAutomator2',
+    'appium:app': process.env.ANDROID_APP_PATH || './apps/android/app-debug.apk',
+    'appium:noReset': false,
+    'appium:fullReset': false,
+    'appium:newCommandTimeout': 240,
+  },
+
+  browserstack: {
+    platformName: 'Android',
+    'appium:deviceName': 'Samsung Galaxy S21',
+    'appium:platformVersion': '12.0',
+    'appium:app': process.env.BROWSERSTACK_ANDROID_APP_URL,
+    'bstack:options': {
+      userName: process.env.BROWSERSTACK_USERNAME,
+      accessKey: process.env.BROWSERSTACK_ACCESS_KEY,
+      projectName: 'Automation Tests',
+      buildName: `Android Build ${Date.now()}`,
+      sessionName: 'Android Tests',
+      debug: true,
+      networkLogs: true,
+    },
+  },
+};
+```
+
+#### Capabilities - iOS (test/support/capabilities/ios.caps.ts)
+
+```typescript
+export const iosCapabilities = {
+  local: {
+    platformName: 'iOS',
+    'appium:deviceName': process.env.IOS_DEVICE_NAME || 'iPhone 14',
+    'appium:platformVersion': process.env.IOS_PLATFORM_VERSION || '16.0',
+    'appium:automationName': 'XCUITest',
+    'appium:app': process.env.IOS_APP_PATH || './apps/ios/App.app',
+    'appium:noReset': false,
+    'appium:fullReset': false,
+    'appium:newCommandTimeout': 240,
+  },
+
+  browserstack: {
+    platformName: 'iOS',
+    'appium:deviceName': 'iPhone 14',
+    'appium:platformVersion': '16.0',
+    'appium:app': process.env.BROWSERSTACK_IOS_APP_URL,
+    'bstack:options': {
+      userName: process.env.BROWSERSTACK_USERNAME,
+      accessKey: process.env.BROWSERSTACK_ACCESS_KEY,
+      projectName: 'Automation Tests',
+      buildName: `iOS Build ${Date.now()}`,
+      sessionName: 'iOS Tests',
+      debug: true,
+      networkLogs: true,
+    },
+  },
+};
+```
+
+#### Gesture Helper (test/support/helpers/gesture.helper.ts)
+
+```typescript
+/**
+ * Gesture helpers for mobile testing
+ */
+export class GestureHelper {
+  /**
+   * Scroll down until element is visible
+   */
+  static async scrollDownToElement(
+    selector: string,
+    maxScrolls = 10,
+    scrollPercent = 0.5
+  ): Promise<WebdriverIO.Element> {
+    const { height } = await driver.getWindowSize();
+    const startY = height * 0.8;
+    const endY = height * (1 - scrollPercent);
+
+    for (let i = 0; i < maxScrolls; i++) {
+      try {
+        const element = await $(selector);
+        if (await element.isDisplayed()) {
+          return element;
+        }
+      } catch {
+        // Element not found
+      }
+
+      await driver.touchAction([
+        { action: 'press', x: 200, y: startY },
+        { action: 'wait', ms: 300 },
+        { action: 'moveTo', x: 200, y: endY },
+        { action: 'release' },
+      ]);
+    }
+
+    throw new Error(`Element ${selector} not found after ${maxScrolls} scrolls`);
+  }
+
+  /**
+   * Swipe left on element (e.g., for delete action)
+   */
+  static async swipeLeft(element: WebdriverIO.Element): Promise<void> {
+    const location = await element.getLocation();
+    const size = await element.getSize();
+    
+    const startX = location.x + size.width * 0.9;
+    const endX = location.x + size.width * 0.1;
+    const y = location.y + size.height / 2;
+
+    await driver.touchAction([
+      { action: 'press', x: startX, y },
+      { action: 'wait', ms: 300 },
+      { action: 'moveTo', x: endX, y },
+      { action: 'release' },
+    ]);
+  }
+
+  /**
+   * Pull to refresh
+   */
+  static async pullToRefresh(): Promise<void> {
+    const { width, height } = await driver.getWindowSize();
+    const startY = height * 0.3;
+    const endY = height * 0.8;
+    const x = width / 2;
+
+    await driver.touchAction([
+      { action: 'press', x, y: startY },
+      { action: 'wait', ms: 500 },
+      { action: 'moveTo', x, y: endY },
+      { action: 'release' },
+    ]);
+  }
+
+  /**
+   * Long press on element
+   */
+  static async longPress(element: WebdriverIO.Element, duration = 2000): Promise<void> {
+    await driver.touchAction([
+      { action: 'press', element },
+      { action: 'wait', ms: duration },
+      { action: 'release' },
+    ]);
+  }
+
+  /**
+   * Double tap
+   */
+  static async doubleTap(element: WebdriverIO.Element): Promise<void> {
+    await element.click();
+    await driver.pause(100);
+    await element.click();
+  }
+
+  /**
+   * Pinch zoom in
+   */
+  static async pinchZoomIn(): Promise<void> {
+    const { width, height } = await driver.getWindowSize();
+    const centerX = width / 2;
+    const centerY = height / 2;
+
+    await driver.touchAction([
+      [
+        { action: 'press', x: centerX - 50, y: centerY },
+        { action: 'moveTo', x: centerX - 150, y: centerY },
+        { action: 'release' },
+      ],
+      [
+        { action: 'press', x: centerX + 50, y: centerY },
+        { action: 'moveTo', x: centerX + 150, y: centerY },
+        { action: 'release' },
+      ],
+    ]);
+  }
+}
+```
+
+#### Common Config (config/wdio.common.conf.ts)
+
+```typescript
+import type { Options } from '@wdio/types';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+export const commonConfig: Partial<Options.Testrunner> = {
+  runner: 'local',
+  autoCompileOpts: {
+    autoCompile: true,
+    tsNodeOpts: {
+      project: './tsconfig.json',
+      transpileOnly: true,
+    },
+  },
+  
+  maxInstances: 1,
+  
+  logLevel: 'info',
+  bail: 0,
+  waitforTimeout: 10000,
+  connectionRetryTimeout: 120000,
+  connectionRetryCount: 3,
+  
+  framework: 'mocha',
+  mochaOpts: {
+    ui: 'bdd',
+    timeout: 60000,
+  },
+  
+  reporters: [
+    'spec',
+    ['allure', {
+      outputDir: 'reports/allure-results',
+      disableWebdriverStepsReporting: true,
+      disableWebdriverScreenshotsReporting: false,
+    }],
+  ],
+
+  beforeSession: async function () {
+    // Validate required env vars
+    const required = ['WEB_BASE_URL'];
+    const missing = required.filter(key => !process.env[key]);
+    if (missing.length > 0) {
+      throw new Error(`Missing env vars: ${missing.join(', ')}`);
+    }
+  },
+
+  afterTest: async function (test, context, { error }) {
+    if (error) {
+      await browser.saveScreenshot(`./reports/screenshots/${test.title}-${Date.now()}.png`);
+    }
+  },
+};
+```
+
+#### Web Config (config/wdio.web.conf.ts)
+
+```typescript
+import { commonConfig } from './wdio.common.conf';
+import type { Options } from '@wdio/types';
+
+export const config: Options.Testrunner = {
+  ...commonConfig,
+  
+  specs: ['./test/specs/web/**/*.spec.ts'],
+  exclude: [],
+  
+  capabilities: [{
+    browserName: 'chrome',
+    'goog:chromeOptions': {
+      args: process.env.HEADLESS === 'true' 
+        ? ['--headless', '--disable-gpu', '--window-size=1920,1080']
+        : ['--window-size=1920,1080'],
+    },
+  }],
+  
+  baseUrl: process.env.WEB_BASE_URL || 'http://localhost:3000',
+  
+  services: ['chromedriver'],
+};
+```
+
+#### Android Config (config/wdio.android.conf.ts)
+
+```typescript
+import { commonConfig } from './wdio.common.conf';
+import { androidCapabilities } from '../test/support/capabilities/android.caps';
+import type { Options } from '@wdio/types';
+
+export const config: Options.Testrunner = {
+  ...commonConfig,
+  
+  specs: ['./test/specs/android/**/*.spec.ts'],
+  exclude: [],
+  
+  capabilities: [androidCapabilities.local],
+  
+  services: [
+    ['appium', {
+      args: {
+        address: 'localhost',
+        port: 4723,
+      },
+      logPath: './reports/appium-logs',
+    }],
+  ],
+  
+  port: 4723,
+  path: '/wd/hub',
+};
+```
+
+#### Package.json
+
+```json
+{
+  "name": "wdio-automation",
+  "version": "1.0.0",
+  "scripts": {
+    "test:web": "wdio run config/wdio.web.conf.ts",
+    "test:web:headless": "HEADLESS=true wdio run config/wdio.web.conf.ts",
+    "test:android": "wdio run config/wdio.android.conf.ts",
+    "test:ios": "wdio run config/wdio.ios.conf.ts",
+    "test:bs:web": "wdio run config/wdio.browserstack.web.conf.ts",
+    "test:bs:android": "wdio run config/wdio.browserstack.android.conf.ts",
+    "test:bs:ios": "wdio run config/wdio.browserstack.ios.conf.ts",
+    "report:allure": "allure generate reports/allure-results --clean -o reports/allure-report && allure open reports/allure-report",
+    "config:doctor": "ts-node scripts/config-doctor.ts",
+    "upload:android": "ts-node scripts/upload-app.ts android",
+    "upload:ios": "ts-node scripts/upload-app.ts ios"
+  },
+  "devDependencies": {
+    "@wdio/allure-reporter": "^8.0.0",
+    "@wdio/appium-service": "^8.0.0",
+    "@wdio/browserstack-service": "^8.0.0",
+    "@wdio/cli": "^8.0.0",
+    "@wdio/local-runner": "^8.0.0",
+    "@wdio/mocha-framework": "^8.0.0",
+    "@wdio/spec-reporter": "^8.0.0",
+    "allure-commandline": "^2.0.0",
+    "chromedriver": "^120.0.0",
+    "dotenv": "^16.0.0",
+    "ts-node": "^10.0.0",
+    "typescript": "^5.0.0",
+    "wdio-chromedriver-service": "^8.0.0"
+  }
+}
+```
+
+### Step 3: Generate .env.example
+
+```ini
+# Environment
+ENV=staging
+WEB_BASE_URL=https://staging.example.com
+API_BASE_URL=https://api.staging.example.com
+
+# Test Suite
+SUITE=smoke
+
+# Test Credentials
+TEST_USER_EMAIL=qa.user@example.com
+TEST_USER_PASSWORD=<secret>
+
+# Web Testing
+HEADLESS=false
+
+# Android Testing
+ANDROID_DEVICE_NAME=Pixel_5_API_31
+ANDROID_PLATFORM_VERSION=12.0
+ANDROID_APP_PATH=./apps/android/app-debug.apk
+
+# iOS Testing
+IOS_DEVICE_NAME=iPhone 14
+IOS_PLATFORM_VERSION=16.0
+IOS_APP_PATH=./apps/ios/App.app
+
+# BrowserStack
+BROWSERSTACK_USERNAME=<your-username>
+BROWSERSTACK_ACCESS_KEY=<your-access-key>
+BROWSERSTACK_ANDROID_APP_URL=bs://<app-id>
+BROWSERSTACK_IOS_APP_URL=bs://<app-id>
+
+# Notifications
+WEBHOOK_SLACK=<slack-webhook-url>
+```
+
+## Output
+
+Complete WebdriverIO project with:
+- Web + Mobile (Android/iOS) support
+- Page Object Model for all platforms
+- Gesture helpers for mobile
+- BrowserStack integration
+- Allure reporting
+- Configuration management
+
+$ARGUMENTS