ai-qakit 1.0.0

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

@@ -0,0 +1,689 @@
+# Scaffold Playwright Project
+
+Generate a complete Playwright test automation project following Enouvo QA standards.
+
+## Usage
+
+```
+/qakit:automation/scaffold-playwright [--type=web|mobile]
+```
+
+## Instructions
+
+### Step 1: Create Project Structure
+
+Generate the following structure:
+
+```
+tests/
+├── specs/                          # Test specifications
+│   ├── auth/
+│   │   ├── login.spec.ts
+│   │   └── logout.spec.ts
+│   ├── dashboard/
+│   │   └── dashboard.spec.ts
+│   └── smoke/
+│       └── smoke.spec.ts
+├── page-objects/                   # Page Object Model
+│   ├── common/
+│   │   ├── base.page.ts
+│   │   └── components/
+│   │       ├── header.component.ts
+│   │       └── modal.component.ts
+│   ├── auth/
+│   │   ├── login.page.ts
+│   │   ├── register.page.ts
+│   │   └── index.ts
+│   ├── dashboard/
+│   │   ├── dashboard.page.ts
+│   │   └── index.ts
+│   └── index.ts
+├── support/                        # Utilities and helpers
+│   ├── fixtures/
+│   │   ├── auth.fixture.ts
+│   │   ├── page.fixture.ts
+│   │   └── index.ts
+│   ├── helpers/
+│   │   ├── api.helper.ts
+│   │   ├── data.helper.ts
+│   │   ├── wait.helper.ts
+│   │   └── index.ts
+│   ├── seeders/
+│   │   └── user.seeder.ts
+│   └── config.ts
+├── data/                           # Test data
+│   ├── users.json
+│   ├── fixtures/
+│   │   └── login.fixture.json
+│   └── schemas/
+│       └── user.schema.json
+└── reports/                        # Generated reports
+    └── .gitkeep
+
+configs/
+├── playwright.config.ts            # Base config
+├── playwright.smoke.config.ts      # Smoke suite
+├── playwright.regression.config.ts # Regression suite
+└── projects/
+    ├── chromium.ts
+    ├── firefox.ts
+    ├── webkit.ts
+    └── mobile.ts
+
+scripts/
+├── config-doctor.ts
+├── seed-data.ts
+├── cleanup.ts
+└── run-suite.ts
+
+.env.example
+.gitignore
+tsconfig.json
+package.json
+README.md
+```
+
+### Step 2: Generate Core Files
+
+#### Base Page (tests/page-objects/common/base.page.ts)
+
+```typescript
+import { Page, Locator, expect } from '@playwright/test';
+
+export abstract class BasePage {
+  constructor(protected readonly page: Page) {}
+
+  protected abstract readonly url: string;
+  protected abstract readonly pageTitle: string;
+
+  // Navigation
+  async open(): Promise<void> {
+    await this.page.goto(this.url);
+    await this.waitForPageLoad();
+  }
+
+  async waitForPageLoad(): Promise<void> {
+    await this.page.waitForLoadState('networkidle');
+  }
+
+  async reload(): Promise<void> {
+    await this.page.reload();
+    await this.waitForPageLoad();
+  }
+
+  // Locator helpers
+  protected getByTestId(testId: string): Locator {
+    return this.page.getByTestId(testId);
+  }
+
+  protected getByRole(role: Parameters<Page['getByRole']>[0], options?: Parameters<Page['getByRole']>[1]): Locator {
+    return this.page.getByRole(role, options);
+  }
+
+  protected getByLabel(label: string): Locator {
+    return this.page.getByLabel(label);
+  }
+
+  protected getByText(text: string | RegExp): Locator {
+    return this.page.getByText(text);
+  }
+
+  protected getByPlaceholder(placeholder: string): Locator {
+    return this.page.getByPlaceholder(placeholder);
+  }
+
+  // Common actions
+  async clickButton(name: string): Promise<void> {
+    await this.getByRole('button', { name }).click();
+  }
+
+  async clickLink(name: string): Promise<void> {
+    await this.getByRole('link', { name }).click();
+  }
+
+  async fillInput(label: string, value: string): Promise<void> {
+    await this.getByLabel(label).fill(value);
+  }
+
+  // Screenshots & debugging
+  async screenshot(name: string): Promise<void> {
+    await this.page.screenshot({ 
+      path: `reports/screenshots/${name}-${Date.now()}.png`,
+      fullPage: true 
+    });
+  }
+
+  // Common assertions
+  async expectPageTitle(): Promise<void> {
+    await expect(this.page).toHaveTitle(this.pageTitle);
+  }
+
+  async expectUrl(urlPattern: string | RegExp): Promise<void> {
+    await expect(this.page).toHaveURL(urlPattern);
+  }
+
+  async expectVisible(locator: Locator): Promise<void> {
+    await expect(locator).toBeVisible();
+  }
+
+  async expectHidden(locator: Locator): Promise<void> {
+    await expect(locator).toBeHidden();
+  }
+}
+```
+
+#### Login Page (tests/page-objects/auth/login.page.ts)
+
+```typescript
+import { Page, expect } from '@playwright/test';
+import { BasePage } from '../common/base.page';
+
+export interface LoginCredentials {
+  email: string;
+  password: string;
+}
+
+export class LoginPage extends BasePage {
+  protected readonly url = '/login';
+  protected readonly pageTitle = 'Login';
+
+  // Private locators - encapsulated
+  private emailInput = () => this.getByLabel('Email');
+  private passwordInput = () => this.getByLabel('Password');
+  private submitButton = () => this.getByRole('button', { name: /sign in|login/i });
+  private errorAlert = () => this.getByRole('alert');
+  private rememberMeCheckbox = () => this.getByLabel(/remember me/i);
+  private forgotPasswordLink = () => this.getByRole('link', { name: /forgot password/i });
+  private registerLink = () => this.getByRole('link', { name: /register|sign up/i });
+
+  // Semantic actions
+  async login(credentials: LoginCredentials): Promise<void> {
+    await this.emailInput().fill(credentials.email);
+    await this.passwordInput().fill(credentials.password);
+    await this.submitButton().click();
+  }
+
+  async loginWithRememberMe(credentials: LoginCredentials): Promise<void> {
+    await this.emailInput().fill(credentials.email);
+    await this.passwordInput().fill(credentials.password);
+    await this.rememberMeCheckbox().check();
+    await this.submitButton().click();
+  }
+
+  async clearForm(): Promise<void> {
+    await this.emailInput().clear();
+    await this.passwordInput().clear();
+  }
+
+  async goToForgotPassword(): Promise<void> {
+    await this.forgotPasswordLink().click();
+  }
+
+  async goToRegister(): Promise<void> {
+    await this.registerLink().click();
+  }
+
+  // State getters - return data for spec assertions
+  async getErrorMessage(): Promise<string> {
+    return await this.errorAlert().textContent() ?? '';
+  }
+
+  async isErrorVisible(): Promise<boolean> {
+    return await this.errorAlert().isVisible();
+  }
+
+  async isSubmitEnabled(): Promise<boolean> {
+    return await this.submitButton().isEnabled();
+  }
+
+  // Assertions
+  async expectErrorMessage(message: string | RegExp): Promise<void> {
+    await expect(this.errorAlert()).toContainText(message);
+  }
+
+  async expectNoError(): Promise<void> {
+    await expect(this.errorAlert()).toBeHidden();
+  }
+
+  async expectRedirectToDashboard(): Promise<void> {
+    await expect(this.page).toHaveURL(/.*dashboard/);
+  }
+
+  async expectLoginPage(): Promise<void> {
+    await expect(this.page).toHaveURL(/.*login/);
+    await expect(this.emailInput()).toBeVisible();
+  }
+}
+```
+
+#### Auth Fixture (tests/support/fixtures/auth.fixture.ts)
+
+```typescript
+import { test as base, Page } from '@playwright/test';
+import { LoginPage } from '../../page-objects/auth/login.page';
+
+// Define fixture types
+type AuthFixtures = {
+  loginPage: LoginPage;
+  authenticatedPage: Page;
+};
+
+// Extend base test with auth fixtures
+export const test = base.extend<AuthFixtures>({
+  loginPage: async ({ page }, use) => {
+    const loginPage = new LoginPage(page);
+    await use(loginPage);
+  },
+
+  authenticatedPage: async ({ page }, use) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.open();
+    await loginPage.login({
+      email: process.env.TEST_USER_EMAIL!,
+      password: process.env.TEST_USER_PASSWORD!,
+    });
+    await loginPage.expectRedirectToDashboard();
+    await use(page);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+#### API Helper (tests/support/helpers/api.helper.ts)
+
+```typescript
+import { APIRequestContext, request } from '@playwright/test';
+
+export class ApiHelper {
+  private context: APIRequestContext | null = null;
+  private baseUrl: string;
+
+  constructor(baseUrl?: string) {
+    this.baseUrl = baseUrl || process.env.API_BASE_URL || '';
+  }
+
+  async init(): Promise<void> {
+    this.context = await request.newContext({
+      baseURL: this.baseUrl,
+    });
+  }
+
+  async dispose(): Promise<void> {
+    await this.context?.dispose();
+  }
+
+  async get<T>(endpoint: string, options?: { headers?: Record<string, string> }): Promise<T> {
+    if (!this.context) await this.init();
+    const response = await this.context!.get(endpoint, options);
+    return response.json();
+  }
+
+  async post<T>(endpoint: string, data: unknown, options?: { headers?: Record<string, string> }): Promise<T> {
+    if (!this.context) await this.init();
+    const response = await this.context!.post(endpoint, {
+      data,
+      ...options,
+    });
+    return response.json();
+  }
+
+  async delete(endpoint: string): Promise<void> {
+    if (!this.context) await this.init();
+    await this.context!.delete(endpoint);
+  }
+
+  // Auth helpers
+  async getAuthToken(email: string, password: string): Promise<string> {
+    const response = await this.post<{ token: string }>('/auth/login', { email, password });
+    return response.token;
+  }
+
+  // Data seeding helpers
+  async createUser(userData: { email: string; name: string }): Promise<{ id: string }> {
+    return this.post('/users', userData);
+  }
+
+  async deleteUser(userId: string): Promise<void> {
+    await this.delete(`/users/${userId}`);
+  }
+}
+```
+
+#### Config (tests/support/config.ts)
+
+```typescript
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+export const config = {
+  env: process.env.ENV || 'staging',
+  
+  urls: {
+    web: process.env.WEB_BASE_URL || 'http://localhost:3000',
+    api: process.env.API_BASE_URL || 'http://localhost:3001',
+  },
+
+  credentials: {
+    testUser: {
+      email: process.env.TEST_USER_EMAIL || '',
+      password: process.env.TEST_USER_PASSWORD || '',
+    },
+    adminUser: {
+      email: process.env.ADMIN_USER_EMAIL || '',
+      password: process.env.ADMIN_USER_PASSWORD || '',
+    },
+  },
+
+  timeouts: {
+    short: 5000,
+    medium: 10000,
+    long: 30000,
+  },
+
+  browserstack: {
+    username: process.env.BROWSERSTACK_USERNAME || '',
+    accessKey: process.env.BROWSERSTACK_ACCESS_KEY || '',
+  },
+
+  notifications: {
+    slackWebhook: process.env.WEBHOOK_SLACK || '',
+  },
+};
+
+// Validation
+export function validateConfig(): void {
+  const required = ['TEST_USER_EMAIL', 'TEST_USER_PASSWORD', 'WEB_BASE_URL'];
+  const missing = required.filter(key => !process.env[key]);
+  
+  if (missing.length > 0) {
+    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+  }
+}
+```
+
+#### Sample Login Spec (tests/specs/auth/login.spec.ts)
+
+```typescript
+import { test, expect } from '../../support/fixtures/auth.fixture';
+import { LoginPage } from '../../page-objects/auth/login.page';
+
+test.describe('Login Feature @auth', () => {
+  let loginPage: LoginPage;
+
+  test.beforeEach(async ({ page }) => {
+    loginPage = new LoginPage(page);
+    await loginPage.open();
+  });
+
+  test.describe('Valid Login', () => {
+    test('should login with valid credentials @smoke', async () => {
+      await test.step('Enter valid credentials', async () => {
+        await loginPage.login({
+          email: process.env.TEST_USER_EMAIL!,
+          password: process.env.TEST_USER_PASSWORD!,
+        });
+      });
+
+      await test.step('Verify redirect to dashboard', async () => {
+        await loginPage.expectRedirectToDashboard();
+      });
+    });
+
+    test('should login with remember me checked', async () => {
+      await loginPage.loginWithRememberMe({
+        email: process.env.TEST_USER_EMAIL!,
+        password: process.env.TEST_USER_PASSWORD!,
+      });
+      await loginPage.expectRedirectToDashboard();
+    });
+  });
+
+  test.describe('Invalid Login', () => {
+    test('should show error for invalid email format', async () => {
+      await loginPage.login({
+        email: 'invalid-email',
+        password: 'password123',
+      });
+      await loginPage.expectErrorMessage(/invalid email/i);
+    });
+
+    test('should show error for wrong password', async () => {
+      await loginPage.login({
+        email: process.env.TEST_USER_EMAIL!,
+        password: 'wrongpassword',
+      });
+      await loginPage.expectErrorMessage(/invalid.*password/i);
+    });
+
+    test('should show error for empty email', async () => {
+      await loginPage.login({
+        email: '',
+        password: 'password123',
+      });
+      await loginPage.expectErrorMessage(/email.*required/i);
+    });
+
+    test('should show error for empty password', async () => {
+      await loginPage.login({
+        email: process.env.TEST_USER_EMAIL!,
+        password: '',
+      });
+      await loginPage.expectErrorMessage(/password.*required/i);
+    });
+  });
+
+  test.describe('Navigation', () => {
+    test('should navigate to forgot password page', async () => {
+      await loginPage.goToForgotPassword();
+      await expect(loginPage['page']).toHaveURL(/.*forgot-password/);
+    });
+
+    test('should navigate to register page', async () => {
+      await loginPage.goToRegister();
+      await expect(loginPage['page']).toHaveURL(/.*register/);
+    });
+  });
+});
+```
+
+#### Smoke Spec (tests/specs/smoke/smoke.spec.ts)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Smoke Tests @smoke', () => {
+  test('should load homepage', async ({ page }) => {
+    await page.goto('/');
+    await expect(page).toHaveTitle(/.+/);
+  });
+
+  test('should load login page', async ({ page }) => {
+    await page.goto('/login');
+    await expect(page.getByRole('button', { name: /sign in|login/i })).toBeVisible();
+  });
+
+  test('should have working navigation', async ({ page }) => {
+    await page.goto('/');
+    // Add navigation checks
+  });
+});
+```
+
+#### Playwright Config (playwright.config.ts)
+
+```typescript
+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', open: 'never' }],
+    ['junit', { outputFile: 'reports/junit.xml' }],
+    ['json', { outputFile: 'reports/results.json' }],
+    ['list'],
+  ],
+
+  use: {
+    baseURL: process.env.WEB_BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    actionTimeout: 10000,
+    navigationTimeout: 30000,
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 12'] },
+    },
+  ],
+
+  webServer: process.env.CI ? undefined : {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+#### Package.json
+
+```json
+{
+  "name": "automation-tests",
+  "version": "1.0.0",
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep @smoke",
+    "test:regression": "playwright test --grep @regression",
+    "test:auth": "playwright test --grep @auth",
+    "test:chromium": "playwright test --project=chromium",
+    "test:firefox": "playwright test --project=firefox",
+    "test:webkit": "playwright test --project=webkit",
+    "test:mobile": "playwright test --project=mobile-chrome --project=mobile-safari",
+    "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": "rimraf reports/* && rimraf test-results/*"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.40.0",
+    "@types/node": "^20.0.0",
+    "dotenv": "^16.3.0",
+    "rimraf": "^5.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.3.0"
+  }
+}
+```
+
+### Step 3: Generate README
+
+```markdown
+# Automation Tests
+
+Playwright-based test automation following Enouvo QA standards.
+
+## Setup
+
+1. Install dependencies:
+   ```bash
+   npm install
+   npx playwright install
+   ```
+
+2. Configure environment:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your values
+   ```
+
+3. Validate configuration:
+   ```bash
+   npm run config:doctor
+   ```
+
+## Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run smoke tests
+npm run test:smoke
+
+# Run specific browser
+npm run test:chromium
+
+# Run in headed mode
+npm run test:headed
+
+# Debug mode
+npm run test:debug
+
+# Interactive UI mode
+npm run test:ui
+```
+
+## Project Structure
+
+- `tests/specs/` - Test specifications
+- `tests/page-objects/` - Page Object Model classes
+- `tests/support/` - Fixtures, helpers, utilities
+- `tests/data/` - Test data files
+- `reports/` - Generated reports
+
+## Writing Tests
+
+See `tests/specs/auth/login.spec.ts` for example patterns.
+
+## Reports
+
+After running tests:
+```bash
+npm run report
+```
+```
+
+## Output
+
+Complete Playwright project with:
+- Page Object Model structure
+- Custom fixtures
+- API helpers
+- Sample specs
+- Configuration management
+- npm scripts
+
+$ARGUMENTS