ai-qakit 1.0.0

package/templates/.claude/skills/webdriverio/SKILL.md

@@ -0,0 +1,433 @@
+# WebdriverIO Automation Skill
+
+## Overview
+
+Expert knowledge in WebdriverIO test automation framework for Web and Mobile (Appium) testing. This skill provides patterns, best practices, and code examples following Enouvo QA standards.
+
+## Triggers
+
+This skill activates when:
+- Writing WebdriverIO tests
+- Setting up WebdriverIO project
+- Creating Page Objects for Web/Mobile
+- Configuring Appium for mobile testing
+- Integrating with BrowserStack/Sauce Labs
+
+## Core Concepts
+
+### Framework Architecture
+
+| Layer | Responsibility | Location |
+|-------|---------------|----------|
+| Test Specs | Describe business flows | `test/specs/**` |
+| Page Objects | Encapsulate selectors and actions | `test/pageObjects/**` |
+| Support | Helpers, capabilities, hooks | `test/support/**` |
+| Config | Runner configs, services | `config/*.conf.ts` |
+| Reports | Allure, JUnit, screenshots | `reports/**` |
+
+### Design Principles
+
+1. **Separation of concerns** - Tests describe *what*, page objects handle *how*
+2. **Single source of truth** - Capabilities and credentials in dedicated modules
+3. **Extensibility** - Add platforms via capability sets, not rewriting specs
+4. **Idempotent specs** - Tests reset their own data dependencies
+5. **Observability-first** - Every failure provides actionable logs
+
+## Page Object Pattern
+
+### Base Page (Web)
+
+```typescript
+export class BasePage {
+  async waitForDisplayed(element: WebdriverIO.Element, timeout = 10000): Promise<void> {
+    await element.waitForDisplayed({ timeout });
+  }
+
+  async waitForClickable(element: WebdriverIO.Element, timeout = 10000): Promise<void> {
+    await element.waitForClickable({ timeout });
+  }
+
+  async safeClick(element: WebdriverIO.Element): Promise<void> {
+    await this.waitForClickable(element);
+    await element.click();
+  }
+
+  async safeSetValue(element: WebdriverIO.Element, value: string): Promise<void> {
+    await this.waitForDisplayed(element);
+    await element.clearValue();
+    await element.setValue(value);
+  }
+
+  async open(path: string): Promise<void> {
+    await browser.url(path);
+  }
+}
+```
+
+### Base Mobile Page
+
+```typescript
+export class BaseMobilePage {
+  async safeTap(element: WebdriverIO.Element): Promise<void> {
+    await element.waitForDisplayed({ timeout: 15000 });
+    await element.click();
+  }
+
+  async hideKeyboard(): Promise<void> {
+    if (await driver.isKeyboardShown()) {
+      await driver.hideKeyboard();
+    }
+  }
+
+  async scroll(direction: 'up' | 'down'): Promise<void> {
+    const { height } = await driver.getWindowSize();
+    const startY = direction === 'down' ? height * 0.8 : height * 0.2;
+    const endY = direction === 'down' ? height * 0.2 : height * 0.8;
+
+    await driver.touchAction([
+      { action: 'press', x: 200, y: startY },
+      { action: 'wait', ms: 300 },
+      { action: 'moveTo', x: 200, y: endY },
+      { action: 'release' },
+    ]);
+  }
+
+  get isAndroid(): boolean { return driver.isAndroid; }
+  get isIOS(): boolean { return driver.isIOS; }
+}
+```
+
+### Page Implementation
+
+```typescript
+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"]'); }
+
+  // Actions
+  async open(): Promise<void> {
+    await super.open('/login');
+  }
+
+  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);
+  }
+
+  // Assertions
+  async expectErrorMessage(message: string): Promise<void> {
+    const error = await (await this.errorMessage).getText();
+    expect(error).toContain(message);
+  }
+
+  async expectDashboard(): Promise<void> {
+    await browser.waitUntil(
+      async () => (await browser.getUrl()).includes('/dashboard'),
+      { timeout: 10000 }
+    );
+  }
+}
+
+export default new LoginPage();
+```
+
+## Mobile Selectors
+
+### Android Selectors
+
+```typescript
+// Accessibility ID (recommended)
+$('~login-button')
+
+// Resource ID
+$('android=new UiSelector().resourceId("com.app:id/login_button")')
+
+// Text
+$('android=new UiSelector().text("Login")')
+
+// Class + Text
+$('android=new UiSelector().className("android.widget.Button").text("Login")')
+
+// Scrollable
+$('android=new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text("Item"))')
+```
+
+### iOS Selectors
+
+```typescript
+// Accessibility ID (recommended)
+$('~login-button')
+
+// Predicate String
+$('-ios predicate string:name == "Login"')
+
+// Class Chain
+$('-ios class chain:**/XCUIElementTypeButton[`name == "Login"`]')
+
+// XPath (slow, avoid)
+$('//XCUIElementTypeButton[@name="Login"]')
+```
+
+## Gesture Helpers
+
+```typescript
+export class GestureHelper {
+  // Scroll to element
+  static async scrollToElement(selector: string, maxScrolls = 10): Promise<void> {
+    const { height } = await driver.getWindowSize();
+    
+    for (let i = 0; i < maxScrolls; i++) {
+      try {
+        const element = await $(selector);
+        if (await element.isDisplayed()) return;
+      } catch {}
+
+      await driver.touchAction([
+        { action: 'press', x: 200, y: height * 0.8 },
+        { action: 'wait', ms: 300 },
+        { action: 'moveTo', x: 200, y: height * 0.2 },
+        { action: 'release' },
+      ]);
+    }
+  }
+
+  // Swipe left (delete action)
+  static async swipeLeft(element: WebdriverIO.Element): Promise<void> {
+    const location = await element.getLocation();
+    const size = await element.getSize();
+    
+    await driver.touchAction([
+      { action: 'press', x: location.x + size.width * 0.9, y: location.y + size.height / 2 },
+      { action: 'wait', ms: 300 },
+      { action: 'moveTo', x: location.x + size.width * 0.1, y: location.y + size.height / 2 },
+      { action: 'release' },
+    ]);
+  }
+
+  // Pull to refresh
+  static async pullToRefresh(): Promise<void> {
+    const { width, height } = await driver.getWindowSize();
+    
+    await driver.touchAction([
+      { action: 'press', x: width / 2, y: height * 0.3 },
+      { action: 'wait', ms: 500 },
+      { action: 'moveTo', x: width / 2, y: height * 0.8 },
+      { action: 'release' },
+    ]);
+  }
+
+  // Long press
+  static async longPress(element: WebdriverIO.Element, duration = 2000): Promise<void> {
+    await driver.touchAction([
+      { action: 'press', element },
+      { action: 'wait', ms: duration },
+      { action: 'release' },
+    ]);
+  }
+}
+```
+
+## Configuration
+
+### Common Config
+
+```typescript
+// config/wdio.common.conf.ts
+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' }],
+  ],
+
+  afterTest: async function (test, context, { error }) {
+    if (error) {
+      await browser.saveScreenshot(`./reports/screenshots/${test.title}.png`);
+    }
+  },
+};
+```
+
+### Web Config
+
+```typescript
+// config/wdio.web.conf.ts
+export const config: Options.Testrunner = {
+  ...commonConfig,
+  specs: ['./test/specs/web/**/*.spec.ts'],
+  capabilities: [{
+    browserName: 'chrome',
+    'goog:chromeOptions': {
+      args: process.env.HEADLESS === 'true' ? ['--headless'] : [],
+    },
+  }],
+  baseUrl: process.env.WEB_BASE_URL,
+  services: ['chromedriver'],
+};
+```
+
+### Android Config
+
+```typescript
+// config/wdio.android.conf.ts
+export const config: Options.Testrunner = {
+  ...commonConfig,
+  specs: ['./test/specs/android/**/*.spec.ts'],
+  capabilities: [{
+    platformName: 'Android',
+    'appium:deviceName': 'Pixel_5_API_31',
+    'appium:platformVersion': '12.0',
+    'appium:automationName': 'UiAutomator2',
+    'appium:app': './apps/android/app.apk',
+  }],
+  services: [['appium', { args: { address: 'localhost', port: 4723 } }]],
+  port: 4723,
+  path: '/wd/hub',
+};
+```
+
+### BrowserStack Config
+
+```typescript
+// config/wdio.browserstack.conf.ts
+export const config: Options.Testrunner = {
+  ...commonConfig,
+  user: process.env.BROWSERSTACK_USERNAME,
+  key: process.env.BROWSERSTACK_ACCESS_KEY,
+  capabilities: [{
+    'bstack:options': {
+      projectName: 'Automation Tests',
+      buildName: `Build ${Date.now()}`,
+      debug: true,
+      networkLogs: true,
+    },
+  }],
+  services: ['browserstack'],
+};
+```
+
+## Test Patterns
+
+### Spec Structure
+
+```typescript
+import LoginPage from '../pageObjects/web/login/login.page';
+
+describe('Login Feature', () => {
+  beforeEach(async () => {
+    await LoginPage.open();
+  });
+
+  it('should login with valid credentials', async () => {
+    await LoginPage.login('user@example.com', 'password123');
+    await LoginPage.expectDashboard();
+  });
+
+  it('should show error for invalid credentials', async () => {
+    await LoginPage.login('invalid@example.com', 'wrong');
+    await LoginPage.expectErrorMessage('Invalid credentials');
+  });
+});
+```
+
+### Mobile Spec
+
+```typescript
+import AndroidLoginPage from '../pageObjects/android/login/login.page';
+
+describe('Android Login', () => {
+  it('should login successfully', async () => {
+    await AndroidLoginPage.login('user@example.com', 'password123');
+    await AndroidLoginPage.expectDashboard();
+  });
+});
+```
+
+## Best Practices
+
+### Selector Strategy
+
+1. **Accessibility ID** (`~id`) - Cross-platform, recommended
+2. **Test ID** (`[data-testid]`) - Web, explicit
+3. **Resource ID** - Android specific
+4. **Predicate/Class Chain** - iOS specific
+5. **XPath** - Last resort, slow
+
+### Waiting Strategy
+
+```typescript
+// ✅ Good - Explicit wait
+await element.waitForDisplayed({ timeout: 10000 });
+await element.waitForClickable({ timeout: 10000 });
+
+// ✅ Good - Custom condition
+await browser.waitUntil(
+  async () => (await element.getText()) === 'Expected',
+  { timeout: 10000, timeoutMsg: 'Text did not match' }
+);
+
+// ❌ Bad - Hard-coded pause
+await browser.pause(5000);
+```
+
+### Error Handling
+
+```typescript
+async safeClick(element: WebdriverIO.Element): Promise<void> {
+  try {
+    await element.waitForClickable({ timeout: 10000 });
+    await element.click();
+  } catch (error) {
+    await browser.saveScreenshot(`./reports/error-${Date.now()}.png`);
+    throw error;
+  }
+}
+```
+
+## npm Scripts
+
+```json
+{
+  "scripts": {
+    "test:web": "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",
+    "report:allure": "allure generate reports/allure-results -o reports/allure-report && allure open"
+  }
+}
+```
+
+## References
+
+- [WebdriverIO Documentation](https://webdriver.io/docs/gettingstarted)
+- [Appium Documentation](https://appium.io/docs/en/latest/)
+- [BrowserStack Integration](https://www.browserstack.com/docs/automate/selenium/getting-started/nodejs/webdriverio)
+
+## Examples
+
+See `examples/` for:
+- Web page objects
+- Mobile page objects
+- Gesture helpers
+- BrowserStack setup