ai-qakit 1.0.0

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

@@ -0,0 +1,447 @@
+# Scaffold Automation Project
+
+Generate a complete test automation project structure following Enouvo QA standards.
+
+## Usage
+
+```
+/qakit:automation/scaffold --framework=<framework> [--type=<type>]
+```
+
+## Options
+
+| Option | Values | Default | Description |
+|--------|--------|---------|-------------|
+| `--framework` | `playwright`, `webdriverio`, `karate` | Required | Automation framework |
+| `--type` | `web`, `mobile`, `api`, `full` | `web` | Project type |
+| `--typescript` | `true`, `false` | `true` | Use TypeScript |
+
+## Instructions
+
+### Step 1: Determine Framework and Type
+
+Ask user if not specified:
+- **Framework**: Playwright (recommended for web), WebdriverIO (web + mobile), Karate (API)
+- **Type**: Web only, Mobile (Android/iOS), API only, or Full stack
+
+### Step 2: Generate Project Structure
+
+#### For Playwright (Web)
+
+```
+tests/
+├── specs/                          # Test specifications
+│   ├── auth/
+│   │   ├── login.spec.ts
+│   │   └── logout.spec.ts
+│   ├── dashboard/
+│   └── smoke/
+│       └── smoke.spec.ts
+├── page-objects/                   # Page Object Model
+│   ├── common/
+│   │   └── base.page.ts
+│   ├── auth/
+│   │   ├── login.page.ts
+│   │   ├── selectors.ts
+│   │   └── index.ts
+│   └── index.ts
+├── support/                        # Utilities and helpers
+│   ├── fixtures/
+│   │   ├── auth.fixture.ts
+│   │   └── index.ts
+│   ├── helpers/
+│   │   ├── api.helper.ts
+│   │   ├── data.helper.ts
+│   │   └── wait.helper.ts
+│   ├── seeders/
+│   │   └── user.seeder.ts
+│   └── config.ts
+├── data/                           # Test data
+│   ├── users.json
+│   └── fixtures/
+└── reports/                        # Generated reports
+    └── .gitkeep
+
+configs/
+├── playwright.config.ts            # Base config
+├── playwright.smoke.config.ts      # Smoke suite config
+└── projects/
+    ├── chromium.ts
+    ├── firefox.ts
+    └── webkit.ts
+
+scripts/
+├── config-doctor.ts                # Validate configuration
+├── seed-data.ts                    # Seed test data
+└── cleanup.ts                      # Cleanup artifacts
+
+.env.example                        # Environment template
+```
+
+#### For WebdriverIO (Web + Mobile)
+
+```
+test/
+├── specs/                          # Test specifications
+│   ├── web/
+│   │   ├── auth/
+│   │   └── smoke/
+│   ├── android/
+│   │   ├── auth/
+│   │   └── smoke/
+│   └── ios/
+│       ├── auth/
+│       └── smoke/
+├── pageObjects/                    # Page Object Model
+│   ├── commons/
+│   │   └── base.page.ts
+│   ├── web/
+│   │   └── login/
+│   │       ├── login.page.ts
+│   │       └── selectors.ts
+│   ├── android/
+│   │   └── login/
+│   └── ios/
+│       └── login/
+├── support/                        # Utilities
+│   ├── capabilities/
+│   │   ├── android.caps.ts
+│   │   ├── ios.caps.ts
+│   │   └── web.caps.ts
+│   ├── helpers/
+│   │   ├── gesture.helper.ts
+│   │   ├── scroll.helper.ts
+│   │   └── wait.helper.ts
+│   ├── specs.ts                    # Spec selectors
+│   └── env.ts                      # Environment config
+├── data/
+│   └── users.json
+└── 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.conf.ts       # BrowserStack config
+
+scripts/
+├── run-suite.ts
+└── upload-app.ts
+
+.env.example
+```
+
+#### For Karate (API)
+
+```
+src/test/java/
+├── features/                       # Feature files
+│   ├── auth/
+│   │   ├── login.feature
+│   │   └── token.feature
+│   ├── users/
+│   │   ├── create-user.feature
+│   │   └── get-user.feature
+│   └── smoke/
+│       └── health-check.feature
+├── common/                         # Reusable features
+│   ├── auth.feature
+│   ├── headers.feature
+│   └── utils.feature
+├── runners/                        # Test runners
+│   ├── SmokeRunner.java
+│   └── RegressionRunner.java
+└── karate-config.js                # Configuration
+
+src/test/resources/
+├── data/
+│   ├── users.json
+│   └── payloads/
+│       └── create-user.json
+└── schemas/
+    └── user.schema.json
+
+pom.xml                             # Maven config
+```
+
+### Step 3: Generate Base Files
+
+#### Base Page Object (Playwright)
+
+```typescript
+// tests/page-objects/common/base.page.ts
+import { Page, Locator } from '@playwright/test';
+
+export abstract class BasePage {
+  constructor(protected readonly page: Page) {}
+
+  protected abstract readonly url: string;
+
+  async open(): Promise<void> {
+    await this.page.goto(this.url);
+  }
+
+  async waitForPageLoad(): Promise<void> {
+    await this.page.waitForLoadState('networkidle');
+  }
+
+  protected getByTestId(testId: string): Locator {
+    return this.page.getByTestId(testId);
+  }
+
+  protected getByRole(role: string, options?: { name?: string }): Locator {
+    return this.page.getByRole(role as any, options);
+  }
+
+  async screenshot(name: string): Promise<void> {
+    await this.page.screenshot({ path: `reports/screenshots/${name}.png` });
+  }
+}
+```
+
+#### Login Page Object (Playwright)
+
+```typescript
+// tests/page-objects/auth/login.page.ts
+import { Page, Locator, expect } from '@playwright/test';
+import { BasePage } from '../common/base.page';
+
+export class LoginPage extends BasePage {
+  protected readonly url = '/login';
+
+  // Locators - private, encapsulated
+  private emailInput = () => this.page.getByLabel('Email');
+  private passwordInput = () => this.page.getByLabel('Password');
+  private submitButton = () => this.page.getByRole('button', { name: 'Sign in' });
+  private errorMessage = () => this.page.getByRole('alert');
+  private rememberMeCheckbox = () => this.page.getByLabel('Remember me');
+
+  // Actions - semantic, high-level
+  async login(email: string, password: string): Promise<void> {
+    await this.emailInput().fill(email);
+    await this.passwordInput().fill(password);
+    await this.submitButton().click();
+  }
+
+  async loginWithRememberMe(email: string, password: string): Promise<void> {
+    await this.emailInput().fill(email);
+    await this.passwordInput().fill(password);
+    await this.rememberMeCheckbox().check();
+    await this.submitButton().click();
+  }
+
+  // State getters - return data for assertions in specs
+  async getErrorMessage(): Promise<string> {
+    return await this.errorMessage().textContent() ?? '';
+  }
+
+  async isErrorVisible(): Promise<boolean> {
+    return await this.errorMessage().isVisible();
+  }
+
+  // Assertions - lightweight, invariant checks
+  async expectErrorMessage(message: string): Promise<void> {
+    await expect(this.errorMessage()).toContainText(message);
+  }
+
+  async expectRedirectToDashboard(): Promise<void> {
+    await expect(this.page).toHaveURL(/.*dashboard/);
+  }
+}
+```
+
+#### Sample Spec (Playwright)
+
+```typescript
+// tests/specs/auth/login.spec.ts
+import { test, expect } from '@playwright/test';
+import { LoginPage } from '../../page-objects/auth/login.page';
+
+test.describe('Login Feature', () => {
+  let loginPage: LoginPage;
+
+  test.beforeEach(async ({ page }) => {
+    loginPage = new LoginPage(page);
+    await loginPage.open();
+  });
+
+  test('should login with valid credentials', async () => {
+    await loginPage.login('user@example.com', 'password123');
+    await loginPage.expectRedirectToDashboard();
+  });
+
+  test('should show error for invalid credentials', async () => {
+    await loginPage.login('invalid@example.com', 'wrongpassword');
+    await loginPage.expectErrorMessage('Invalid email or password');
+  });
+
+  test('should show error for empty email', async () => {
+    await loginPage.login('', 'password123');
+    await loginPage.expectErrorMessage('Email is required');
+  });
+});
+```
+
+#### Playwright Config
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+export default defineConfig({
+  testDir: './tests/specs',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'reports/html' }],
+    ['junit', { outputFile: 'reports/junit.xml' }],
+    ['list']
+  ],
+  use: {
+    baseURL: process.env.WEB_BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+  ],
+});
+```
+
+#### Environment Template
+
+```ini
+# .env.example
+# Environment
+ENV=staging
+WEB_BASE_URL=https://staging.example.com
+API_BASE_URL=https://api.staging.example.com
+
+# Test Suite Selection
+SUITE=smoke
+
+# Test Credentials
+TEST_USER_EMAIL=qa.user@example.com
+TEST_USER_PASSWORD=<secret>
+
+# BrowserStack (optional)
+BROWSERSTACK_USERNAME=<your-username>
+BROWSERSTACK_ACCESS_KEY=<your-access-key>
+
+# Notifications (optional)
+WEBHOOK_SLACK=<slack-webhook-url>
+```
+
+### Step 4: Generate package.json Scripts
+
+```json
+{
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep @smoke",
+    "test:regression": "playwright test --grep @regression",
+    "test:chromium": "playwright test --project=chromium",
+    "test:firefox": "playwright test --project=firefox",
+    "test:webkit": "playwright test --project=webkit",
+    "test:headed": "playwright test --headed",
+    "test:debug": "PWDEBUG=1 playwright test --headed",
+    "test:ui": "playwright test --ui",
+    "report": "playwright show-report reports/html",
+    "trace": "playwright show-trace",
+    "config:doctor": "ts-node scripts/config-doctor.ts",
+    "seed": "ts-node scripts/seed-data.ts",
+    "cleanup": "ts-node scripts/cleanup.ts"
+  }
+}
+```
+
+### Step 5: Generate Config Doctor Script
+
+```typescript
+// scripts/config-doctor.ts
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+const requiredVars = [
+  'WEB_BASE_URL',
+  'TEST_USER_EMAIL',
+  'TEST_USER_PASSWORD',
+];
+
+const optionalVars = [
+  'API_BASE_URL',
+  'BROWSERSTACK_USERNAME',
+  'BROWSERSTACK_ACCESS_KEY',
+  'WEBHOOK_SLACK',
+];
+
+console.log('🔍 Configuration Doctor\n');
+console.log('Required Variables:');
+let hasErrors = false;
+
+for (const varName of requiredVars) {
+  const value = process.env[varName];
+  if (value) {
+    console.log(`  ✅ ${varName}: ${value.substring(0, 20)}...`);
+  } else {
+    console.log(`  ❌ ${varName}: MISSING`);
+    hasErrors = true;
+  }
+}
+
+console.log('\nOptional Variables:');
+for (const varName of optionalVars) {
+  const value = process.env[varName];
+  if (value) {
+    console.log(`  ✅ ${varName}: configured`);
+  } else {
+    console.log(`  ⚠️  ${varName}: not set`);
+  }
+}
+
+if (hasErrors) {
+  console.log('\n❌ Configuration incomplete. Please set missing variables.');
+  process.exit(1);
+} else {
+  console.log('\n✅ Configuration looks good!');
+}
+```
+
+## Output
+
+After running this command, AI will:
+1. Create complete folder structure
+2. Generate base files (page objects, configs, helpers)
+3. Create sample specs
+4. Set up npm scripts
+5. Create .env.example
+
+## Next Steps
+
+After scaffolding:
+1. Copy `.env.example` to `.env` and fill in values
+2. Run `npm install` to install dependencies
+3. Run `npm run config:doctor` to validate setup
+4. Run `npm run test:smoke` to verify everything works
+
+$ARGUMENTS

package/templates/.claude/commands/qakit/automation/update-deps.md

@@ -0,0 +1,219 @@
+# Update Automation Dependencies
+
+Safely update automation framework dependencies with compatibility checks.
+
+## Usage
+
+```
+/qakit:automation/update-deps [--check|--apply]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--check` | Check for updates without applying (default) |
+| `--apply` | Apply updates to package.json |
+
+## Instructions
+
+### Step 1: Analyze Current Dependencies
+
+Scan package.json for automation-related dependencies:
+
+```
+📦 Current Dependencies Analysis
+
+Framework: Playwright
+
+| Package | Current | Latest | Update Type |
+|---------|---------|--------|-------------|
+| @playwright/test | 1.40.0 | 1.42.0 | Minor ⚠️ |
+| typescript | 5.3.0 | 5.3.3 | Patch ✅ |
+| dotenv | 16.3.0 | 16.4.0 | Minor ⚠️ |
+| @types/node | 20.10.0 | 20.11.0 | Minor ⚠️ |
+| allure-playwright | 2.10.0 | 2.12.0 | Minor ⚠️ |
+
+Security Vulnerabilities: 0 found
+```
+
+### Step 2: Check Breaking Changes
+
+For each minor/major update, check changelog:
+
+```markdown
+## @playwright/test 1.40.0 → 1.42.0
+
+### Breaking Changes
+- None
+
+### New Features
+- New `toPass` assertion for retrying
+- Improved trace viewer
+- Better error messages
+
+### Deprecations
+- `page.waitForTimeout()` - use `expect().toPass()` instead
+
+### Migration Required
+- No migration required
+
+### Recommendation
+✅ Safe to update
+```
+
+### Step 3: Generate Update Plan
+
+```markdown
+# Dependency Update Plan
+
+**Date:** 2024-01-15
+**Framework:** Playwright
+
+## Safe Updates (Apply Now)
+
+These updates are safe to apply immediately:
+
+```bash
+npm install typescript@5.3.3 @types/node@20.11.0
+```
+
+## Minor Updates (Test First)
+
+These updates should be tested before applying:
+
+| Package | From | To | Risk |
+|---------|------|-----|------|
+| @playwright/test | 1.40.0 | 1.42.0 | Low |
+| dotenv | 16.3.0 | 16.4.0 | Low |
+| allure-playwright | 2.10.0 | 2.12.0 | Low |
+
+### Update Command
+```bash
+npm install @playwright/test@1.42.0 dotenv@16.4.0 allure-playwright@2.12.0
+```
+
+### Post-Update Steps
+1. Run `npx playwright install` to update browsers
+2. Run full test suite
+3. Check for deprecation warnings
+4. Update any deprecated API usage
+
+## Major Updates (Plan Carefully)
+
+No major updates available.
+
+## Security Updates
+
+No security vulnerabilities found.
+```
+
+### Step 4: Apply Updates
+
+If `--apply` flag is used:
+
+```bash
+# Create update branch
+git checkout -b chore/update-automation-deps
+
+# Apply safe updates
+npm install typescript@5.3.3 @types/node@20.11.0
+
+# Apply minor updates
+npm install @playwright/test@1.42.0 dotenv@16.4.0
+
+# Update browsers
+npx playwright install
+
+# Run tests
+npm test
+
+# If tests pass, commit
+git add package.json package-lock.json
+git commit -m "chore: update automation dependencies"
+```
+
+### Step 5: Post-Update Verification
+
+```markdown
+## Update Verification Report
+
+**Updated:** 2024-01-15
+
+### Dependencies Updated
+- @playwright/test: 1.40.0 → 1.42.0 ✅
+- typescript: 5.3.0 → 5.3.3 ✅
+- dotenv: 16.3.0 → 16.4.0 ✅
+
+### Test Results
+- Total: 42 specs
+- Passed: 42 ✅
+- Failed: 0
+- Skipped: 0
+
+### Deprecation Warnings
+- 2 warnings found:
+  - `page.waitForTimeout()` in checkout.spec.ts:34
+  - `page.waitForTimeout()` in search.spec.ts:56
+
+### Recommendations
+1. Replace `waitForTimeout()` with `expect().toPass()`
+2. Update CI workflow to use new Playwright version
+3. Update documentation with new features
+```
+
+## Framework-Specific Updates
+
+### Playwright
+
+```bash
+# Update Playwright
+npm install @playwright/test@latest
+
+# Update browsers (required after Playwright update)
+npx playwright install
+
+# Update Playwright dependencies
+npx playwright install-deps
+```
+
+### WebdriverIO
+
+```bash
+# Update WebdriverIO
+npm install @wdio/cli@latest
+
+# Update all WDIO packages
+npm install @wdio/local-runner@latest @wdio/mocha-framework@latest @wdio/spec-reporter@latest
+
+# Update Appium (if using mobile)
+npm install @wdio/appium-service@latest
+```
+
+### Karate
+
+```xml
+<!-- Update in pom.xml -->
+<dependency>
+  <groupId>com.intuit.karate</groupId>
+  <artifactId>karate-junit5</artifactId>
+  <version>1.4.1</version>
+</dependency>
+```
+
+## Output
+
+- Update plan document
+- Updated package.json (if --apply)
+- Verification report
+- Migration guide (if needed)
+
+## Best Practices
+
+1. **Update in dedicated branch**
+2. **Run full test suite after update**
+3. **Check for deprecation warnings**
+4. **Update documentation**
+5. **Notify team of changes**
+
+$ARGUMENTS