ai-qakit 1.0.0

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

@@ -0,0 +1,303 @@
+# Playwright Automation Skill
+
+## Overview
+
+Expert knowledge in Playwright test automation framework for cross-browser UI testing. This skill provides patterns, best practices, and code examples following Enouvo QA standards.
+
+## Triggers
+
+This skill activates when:
+- Writing Playwright tests
+- Setting up Playwright project
+- Creating Page Objects for Playwright
+- Debugging Playwright tests
+- Configuring Playwright for CI/CD
+
+## Core Concepts
+
+### Framework Architecture
+
+| Layer | Responsibility | Location |
+|-------|---------------|----------|
+| Tests | Describe user flows with fixtures | `tests/specs/**` |
+| Page Objects | Encapsulate selectors and actions | `tests/page-objects/**` |
+| Support | Utilities, fixtures, helpers | `tests/support/**` |
+| Config | Browser profiles, reporters | `playwright.config.ts` |
+| Reports | HTML, traces, videos | `reports/**` |
+
+### Design Principles
+
+1. **Strict Page Object Model** - Expose semantic methods, hide locator details
+2. **Stateless helpers** - Pure functions injected via fixtures
+3. **Deterministic setups** - Seed data via APIs or fixtures
+4. **Artifacts first** - Enable traces, screenshots, videos on failure
+
+## Page Object Pattern
+
+### Base Page
+
+```typescript
+import { Page, Locator, expect } 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');
+  }
+
+  // Locator helpers
+  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);
+  }
+
+  protected getByLabel(label: string): Locator {
+    return this.page.getByLabel(label);
+  }
+}
+```
+
+### Page Implementation
+
+```typescript
+export class LoginPage extends BasePage {
+  protected readonly url = '/login';
+
+  // Private locators - encapsulated
+  private emailInput = () => this.page.getByLabel('Email');
+  private passwordInput = () => this.page.getByLabel('Password');
+  private submitButton = () => this.getByRole('button', { name: 'Sign in' });
+  private errorAlert = () => this.page.getByRole('alert');
+
+  // Semantic actions
+  async login(email: string, password: string): Promise<void> {
+    await this.emailInput().fill(email);
+    await this.passwordInput().fill(password);
+    await this.submitButton().click();
+  }
+
+  // State getters
+  async getErrorMessage(): Promise<string> {
+    return await this.errorAlert().textContent() ?? '';
+  }
+
+  // Assertions
+  async expectErrorMessage(message: string): Promise<void> {
+    await expect(this.errorAlert()).toContainText(message);
+  }
+
+  async expectRedirectToDashboard(): Promise<void> {
+    await expect(this.page).toHaveURL(/.*dashboard/);
+  }
+}
+```
+
+## Fixtures
+
+### Custom Fixtures
+
+```typescript
+import { test as base } from '@playwright/test';
+import { LoginPage } from '../page-objects/auth/login.page';
+
+type Fixtures = {
+  loginPage: LoginPage;
+  authenticatedPage: Page;
+};
+
+export const test = base.extend<Fixtures>({
+  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(
+      process.env.TEST_USER_EMAIL!,
+      process.env.TEST_USER_PASSWORD!
+    );
+    await use(page);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+## Test Patterns
+
+### Spec Structure
+
+```typescript
+import { test, expect } from '../support/fixtures';
+
+test.describe('Feature @tag', () => {
+  test.beforeEach(async ({ page }) => {
+    // Setup
+  });
+
+  test('should do something @smoke', async ({ loginPage }) => {
+    await test.step('Step 1: Action', async () => {
+      await loginPage.open();
+    });
+
+    await test.step('Step 2: Verify', async () => {
+      await loginPage.expectLoginPage();
+    });
+  });
+});
+```
+
+### Tagging Convention
+
+| Tag | Purpose |
+|-----|---------|
+| `@smoke` | Critical path tests |
+| `@regression` | Full regression suite |
+| `@auth` | Authentication tests |
+| `@api` | API-related tests |
+| `@flaky` | Known flaky tests |
+
+## Configuration
+
+### playwright.config.ts
+
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/specs',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  
+  reporter: [
+    ['html', { outputFolder: 'reports/html' }],
+    ['junit', { outputFile: 'reports/junit.xml' }],
+  ],
+
+  use: {
+    baseURL: process.env.WEB_BASE_URL,
+    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'] } },
+  ],
+});
+```
+
+## API Testing
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('API Tests', () => {
+  test('should create user', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: { name: 'Test User', email: 'test@example.com' },
+    });
+    
+    expect(response.ok()).toBeTruthy();
+    const user = await response.json();
+    expect(user).toHaveProperty('id');
+  });
+});
+```
+
+## Best Practices
+
+### Locator Strategy (Priority Order)
+
+1. `getByRole()` - Accessibility-first
+2. `getByLabel()` - Form inputs
+3. `getByText()` - Visible text
+4. `getByTestId()` - Custom test IDs
+5. `locator()` - CSS/XPath (last resort)
+
+### Waiting Strategy
+
+```typescript
+// ✅ Good - Auto-waiting
+await page.getByRole('button').click();
+
+// ✅ Good - Explicit wait for condition
+await expect(page.getByText('Success')).toBeVisible();
+
+// ❌ Bad - Hard-coded wait
+await page.waitForTimeout(5000);
+```
+
+### Assertions
+
+```typescript
+// ✅ Good - Specific assertions
+await expect(page).toHaveURL('/dashboard');
+await expect(locator).toHaveText('Welcome');
+await expect(locator).toBeVisible();
+
+// ❌ Bad - Generic assertions
+expect(await page.url()).toBe('/dashboard');
+```
+
+## Debugging
+
+```bash
+# Debug mode with inspector
+PWDEBUG=1 npx playwright test
+
+# UI mode
+npx playwright test --ui
+
+# Headed mode
+npx playwright test --headed
+
+# Trace viewer
+npx playwright show-trace trace.zip
+```
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions
+- name: Run Playwright tests
+  run: npx playwright test
+  env:
+    CI: true
+    WEB_BASE_URL: ${{ secrets.WEB_BASE_URL }}
+
+- name: Upload report
+  uses: actions/upload-artifact@v3
+  if: always()
+  with:
+    name: playwright-report
+    path: reports/
+```
+
+## References
+
+- [Playwright Documentation](https://playwright.dev/docs/intro)
+- [Best Practices](https://playwright.dev/docs/best-practices)
+- [API Reference](https://playwright.dev/docs/api/class-playwright)
+
+## Examples
+
+See `examples/` for:
+- Complete page object examples
+- Fixture patterns
+- API testing examples
+- Visual testing setup

package/templates/.claude/skills/playwright/examples/auth.fixture.ts

@@ -0,0 +1,172 @@
+/**
+ * Authentication Fixtures - Playwright
+ * Following Enouvo QA Standards
+ */
+import { test as base, Page, BrowserContext } from '@playwright/test';
+import { LoginPage } from './login.page';
+
+// ============================================
+// Fixture Types
+// ============================================
+
+interface AuthFixtures {
+  /** Login page object */
+  loginPage: LoginPage;
+  
+  /** Page with authenticated user session */
+  authenticatedPage: Page;
+  
+  /** Page with admin user session */
+  adminPage: Page;
+  
+  /** Context with stored auth state */
+  authenticatedContext: BrowserContext;
+}
+
+interface TestCredentials {
+  email: string;
+  password: string;
+}
+
+// ============================================
+// Test Credentials
+// ============================================
+
+const testUser: TestCredentials = {
+  email: process.env.TEST_USER_EMAIL || 'test@example.com',
+  password: process.env.TEST_USER_PASSWORD || 'password123',
+};
+
+const adminUser: TestCredentials = {
+  email: process.env.ADMIN_USER_EMAIL || 'admin@example.com',
+  password: process.env.ADMIN_USER_PASSWORD || 'admin123',
+};
+
+// ============================================
+// Extended Test with Fixtures
+// ============================================
+
+export const test = base.extend<AuthFixtures>({
+  /**
+   * Login page fixture - provides LoginPage instance
+   */
+  loginPage: async ({ page }, use) => {
+    const loginPage = new LoginPage(page);
+    await use(loginPage);
+  },
+
+  /**
+   * Authenticated page fixture - logs in before test
+   */
+  authenticatedPage: async ({ page }, use) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.login(testUser);
+    await loginPage.expectRedirectToDashboard();
+    await use(page);
+  },
+
+  /**
+   * Admin page fixture - logs in as admin before test
+   */
+  adminPage: async ({ page }, use) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.login(adminUser);
+    await loginPage.expectRedirectToDashboard();
+    await use(page);
+  },
+
+  /**
+   * Authenticated context fixture - reuses auth state
+   * More efficient for multiple tests
+   */
+  authenticatedContext: async ({ browser }, use) => {
+    // Create new context
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    
+    // Login
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.login(testUser);
+    await loginPage.expectRedirectToDashboard();
+    
+    // Store auth state
+    await context.storageState({ path: '.auth/user.json' });
+    
+    await use(context);
+    await context.close();
+  },
+});
+
+export { expect } from '@playwright/test';
+
+// ============================================
+// Usage Examples
+// ============================================
+
+/*
+// Example 1: Using loginPage fixture
+test('should show login form', async ({ loginPage }) => {
+  await loginPage.goto();
+  await loginPage.expectLoginPage();
+});
+
+// Example 2: Using authenticatedPage fixture
+test('should access dashboard when logged in', async ({ authenticatedPage }) => {
+  // Already logged in, directly on dashboard
+  await expect(authenticatedPage).toHaveURL(/.*dashboard/);
+});
+
+// Example 3: Using adminPage fixture
+test('should access admin panel', async ({ adminPage }) => {
+  await adminPage.goto('/admin');
+  await expect(adminPage).toHaveURL(/.*admin/);
+});
+
+// Example 4: Combining fixtures
+test.describe('User Dashboard', () => {
+  test('should display user info', async ({ authenticatedPage }) => {
+    const userInfo = authenticatedPage.getByTestId('user-info');
+    await expect(userInfo).toBeVisible();
+  });
+});
+*/
+
+// ============================================
+// Global Setup for Auth State (optional)
+// ============================================
+
+/*
+// global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+import { LoginPage } from './page-objects/auth/login.page';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  
+  const loginPage = new LoginPage(page);
+  await loginPage.goto();
+  await loginPage.login({
+    email: process.env.TEST_USER_EMAIL!,
+    password: process.env.TEST_USER_PASSWORD!,
+  });
+  
+  // Save auth state
+  await page.context().storageState({ path: '.auth/user.json' });
+  
+  await browser.close();
+}
+
+export default globalSetup;
+
+// playwright.config.ts
+export default defineConfig({
+  globalSetup: require.resolve('./global-setup'),
+  use: {
+    storageState: '.auth/user.json',
+  },
+});
+*/

package/templates/.claude/skills/playwright/examples/login.page.ts

@@ -0,0 +1,232 @@
+/**
+ * Login Page Object - Playwright
+ * Following Enouvo QA Standards
+ */
+import { Page, Locator, expect } from '@playwright/test';
+
+export interface LoginCredentials {
+  email: string;
+  password: string;
+}
+
+export class LoginPage {
+  readonly page: Page;
+
+  // Private locators - encapsulated, not exposed to specs
+  private readonly emailInput: Locator;
+  private readonly passwordInput: Locator;
+  private readonly submitButton: Locator;
+  private readonly errorAlert: Locator;
+  private readonly rememberMeCheckbox: Locator;
+  private readonly forgotPasswordLink: Locator;
+  private readonly registerLink: Locator;
+  private readonly loadingSpinner: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    
+    // Initialize locators using recommended strategies
+    this.emailInput = page.getByLabel('Email');
+    this.passwordInput = page.getByLabel('Password');
+    this.submitButton = page.getByRole('button', { name: /sign in|login/i });
+    this.errorAlert = page.getByRole('alert');
+    this.rememberMeCheckbox = page.getByLabel(/remember me/i);
+    this.forgotPasswordLink = page.getByRole('link', { name: /forgot password/i });
+    this.registerLink = page.getByRole('link', { name: /register|sign up/i });
+    this.loadingSpinner = page.getByTestId('loading-spinner');
+  }
+
+  // ============================================
+  // Navigation
+  // ============================================
+
+  async goto(): Promise<void> {
+    await this.page.goto('/login');
+    await this.waitForPageReady();
+  }
+
+  async waitForPageReady(): Promise<void> {
+    await this.page.waitForLoadState('networkidle');
+    await expect(this.emailInput).toBeVisible();
+  }
+
+  // ============================================
+  // Actions - Semantic, high-level operations
+  // ============================================
+
+  /**
+   * Login with email and password
+   */
+  async login(credentials: LoginCredentials): Promise<void> {
+    await this.emailInput.fill(credentials.email);
+    await this.passwordInput.fill(credentials.password);
+    await this.submitButton.click();
+  }
+
+  /**
+   * Login with remember me option
+   */
+  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();
+  }
+
+  /**
+   * Clear the login form
+   */
+  async clearForm(): Promise<void> {
+    await this.emailInput.clear();
+    await this.passwordInput.clear();
+  }
+
+  /**
+   * Navigate to forgot password page
+   */
+  async goToForgotPassword(): Promise<void> {
+    await this.forgotPasswordLink.click();
+  }
+
+  /**
+   * Navigate to registration page
+   */
+  async goToRegister(): Promise<void> {
+    await this.registerLink.click();
+  }
+
+  // ============================================
+  // State Getters - Return data for spec assertions
+  // ============================================
+
+  /**
+   * Get error message text
+   */
+  async getErrorMessage(): Promise<string> {
+    await expect(this.errorAlert).toBeVisible();
+    return await this.errorAlert.textContent() ?? '';
+  }
+
+  /**
+   * Check if error is visible
+   */
+  async isErrorVisible(): Promise<boolean> {
+    return await this.errorAlert.isVisible();
+  }
+
+  /**
+   * Check if submit button is enabled
+   */
+  async isSubmitEnabled(): Promise<boolean> {
+    return await this.submitButton.isEnabled();
+  }
+
+  /**
+   * Check if loading spinner is visible
+   */
+  async isLoading(): Promise<boolean> {
+    return await this.loadingSpinner.isVisible();
+  }
+
+  /**
+   * Get current email value
+   */
+  async getEmailValue(): Promise<string> {
+    return await this.emailInput.inputValue();
+  }
+
+  // ============================================
+  // Assertions - Lightweight, invariant checks
+  // ============================================
+
+  /**
+   * Assert error message contains text
+   */
+  async expectErrorMessage(message: string | RegExp): Promise<void> {
+    await expect(this.errorAlert).toBeVisible();
+    await expect(this.errorAlert).toContainText(message);
+  }
+
+  /**
+   * Assert no error is displayed
+   */
+  async expectNoError(): Promise<void> {
+    await expect(this.errorAlert).toBeHidden();
+  }
+
+  /**
+   * Assert redirect to dashboard after login
+   */
+  async expectRedirectToDashboard(): Promise<void> {
+    await expect(this.page).toHaveURL(/.*dashboard/, { timeout: 10000 });
+  }
+
+  /**
+   * Assert still on login page
+   */
+  async expectLoginPage(): Promise<void> {
+    await expect(this.page).toHaveURL(/.*login/);
+    await expect(this.emailInput).toBeVisible();
+  }
+
+  /**
+   * Assert email field has validation error
+   */
+  async expectEmailValidationError(): Promise<void> {
+    await expect(this.emailInput).toHaveAttribute('aria-invalid', 'true');
+  }
+
+  /**
+   * Assert password field has validation error
+   */
+  async expectPasswordValidationError(): Promise<void> {
+    await expect(this.passwordInput).toHaveAttribute('aria-invalid', 'true');
+  }
+
+  /**
+   * Assert loading state
+   */
+  async expectLoading(): Promise<void> {
+    await expect(this.loadingSpinner).toBeVisible();
+  }
+
+  /**
+   * Assert not loading
+   */
+  async expectNotLoading(): Promise<void> {
+    await expect(this.loadingSpinner).toBeHidden();
+  }
+}
+
+// ============================================
+// Usage Example in Spec
+// ============================================
+/*
+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.goto();
+  });
+
+  test('should login with valid credentials', async () => {
+    await loginPage.login({
+      email: 'user@example.com',
+      password: 'password123',
+    });
+    await loginPage.expectRedirectToDashboard();
+  });
+
+  test('should show error for invalid credentials', async () => {
+    await loginPage.login({
+      email: 'invalid@example.com',
+      password: 'wrongpassword',
+    });
+    await loginPage.expectErrorMessage(/invalid.*credentials/i);
+  });
+});
+*/