aigroup-workflow 2.1.2 → 2.2.0

package/skills/quality/playwright-expert/references/configuration.md

@@ -0,0 +1,155 @@
+# Configuration
+
+## Full Configuration
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html'],
+    ['json', { outputFile: 'results.json' }],
+    ['junit', { outputFile: 'results.xml' }],
+  ],
+
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    testIdAttribute: 'data-testid',
+  },
+
+  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 13'] },
+    },
+  ],
+
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+## Authentication Setup
+
+```typescript
+// global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  await page.goto('http://localhost:3000/login');
+  await page.getByLabel('Email').fill('user@test.com');
+  await page.getByLabel('Password').fill('password');
+  await page.getByRole('button', { name: 'Log in' }).click();
+  await page.waitForURL(/dashboard/);
+
+  // Save auth state
+  await page.context().storageState({ path: 'auth.json' });
+  await browser.close();
+}
+
+export default globalSetup;
+
+// playwright.config.ts
+export default defineConfig({
+  globalSetup: require.resolve('./global-setup'),
+  use: {
+    storageState: 'auth.json',
+  },
+});
+```
+
+## Project Dependencies
+
+```typescript
+projects: [
+  {
+    name: 'setup',
+    testMatch: /global.setup\.ts/,
+  },
+  {
+    name: 'chromium',
+    use: { ...devices['Desktop Chrome'] },
+    dependencies: ['setup'],
+  },
+],
+```
+
+## Environment Variables
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+  },
+});
+
+// .env
+BASE_URL=https://staging.example.com
+```
+
+## CI Configuration
+
+```yaml
+# .github/workflows/playwright.yml
+name: Playwright Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npx playwright test
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+```
+
+## Quick Reference
+
+| Option | Purpose |
+|--------|---------|
+| `testDir` | Test files location |
+| `fullyParallel` | Run tests in parallel |
+| `retries` | Retry failed tests |
+| `trace` | Record trace on failure |
+| `webServer` | Start dev server |
+| `globalSetup` | Run before all tests |
+| `storageState` | Reuse auth state |

package/skills/quality/playwright-expert/references/debugging-flaky.md

@@ -0,0 +1,150 @@
+# Debugging & Flaky Tests
+
+## Debugging Tools
+
+```typescript
+// Pause execution and open inspector
+await page.pause();
+
+// Enable step-by-step mode
+PWDEBUG=1 npx playwright test
+
+// Slow motion
+test.use({ launchOptions: { slowMo: 500 } });
+
+// Headed mode
+npx playwright test --headed
+```
+
+## Trace Viewer
+
+```bash
+# View trace from failed test
+npx playwright show-trace trace.zip
+
+# Generate trace always
+test.use({ trace: 'on' });
+
+# View in UI mode
+npx playwright test --ui
+```
+
+## Common Flaky Test Causes
+
+### 1. Race Conditions
+
+```typescript
+// ❌ Bad: Element may not exist yet
+await page.click('.submit-btn');
+
+// ✅ Good: Auto-waiting built in
+await page.getByRole('button', { name: 'Submit' }).click();
+```
+
+### 2. Animation/Transitions
+
+```typescript
+// ❌ Bad: Click during animation
+await page.click('.menu-item');
+
+// ✅ Good: Wait for stable state
+await page.getByRole('menuitem').click();
+await expect(page.getByRole('menu')).toBeVisible();
+```
+
+### 3. Network Timing
+
+```typescript
+// ❌ Bad: Assumes data loaded
+await page.goto('/dashboard');
+expect(await page.textContent('.user-name')).toBe('John');
+
+// ✅ Good: Wait for network
+await page.goto('/dashboard');
+await page.waitForResponse('**/api/user');
+await expect(page.getByTestId('user-name')).toHaveText('John');
+```
+
+### 4. Test Isolation
+
+```typescript
+// ❌ Bad: Tests share state
+test('test 1', async () => { /* creates user */ });
+test('test 2', async () => { /* assumes user exists */ });
+
+// ✅ Good: Each test is independent
+test.beforeEach(async ({ page }) => {
+  await page.request.post('/api/test/reset');
+});
+```
+
+## Proper Waiting
+
+```typescript
+// Wait for element state
+await expect(page.getByText('Success')).toBeVisible();
+await expect(page.getByRole('button')).toBeEnabled();
+await expect(page.getByRole('dialog')).toBeHidden();
+
+// Wait for navigation
+await page.waitForURL(/dashboard/);
+
+// Wait for response
+await page.waitForResponse(r => r.url().includes('/api/data'));
+
+// Wait for load state
+await page.waitForLoadState('networkidle');
+
+// AVOID arbitrary waits
+await page.waitForTimeout(3000); // ❌ BAD
+```
+
+## Retry Strategies
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  retries: process.env.CI ? 2 : 0,
+
+  // Retry only specific tests
+  expect: {
+    timeout: 10000, // Increase assertion timeout
+  },
+});
+
+// Per-test retry
+test('flaky test', async ({ page }) => {
+  test.info().annotations.push({ type: 'issue', description: 'Known flaky' });
+  // ...
+});
+```
+
+## Debugging Output
+
+```typescript
+// Console output
+test('debug test', async ({ page }) => {
+  page.on('console', msg => console.log(msg.text()));
+  page.on('pageerror', err => console.log(err.message));
+});
+
+// Screenshot on step
+await page.screenshot({ path: 'debug.png' });
+```
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `PWDEBUG=1` | Enable inspector |
+| `--headed` | Show browser |
+| `--ui` | UI mode |
+| `page.pause()` | Pause execution |
+| `show-trace` | View trace file |
+
+| Fix | Flaky Cause |
+|-----|-------------|
+| Auto-wait locators | Race conditions |
+| `waitForResponse` | Network timing |
+| Test isolation | Shared state |
+| Increase timeout | Slow operations |

package/skills/quality/playwright-expert/references/page-object-model.md

@@ -0,0 +1,152 @@
+# Page Object Model
+
+## Basic Page Object
+
+```typescript
+// pages/LoginPage.ts
+import { Page, Locator } from '@playwright/test';
+
+export class LoginPage {
+  readonly page: Page;
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly submitButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.emailInput = page.getByLabel('Email');
+    this.passwordInput = page.getByLabel('Password');
+    this.submitButton = page.getByRole('button', { name: 'Log in' });
+    this.errorMessage = page.getByRole('alert');
+  }
+
+  async goto() {
+    await this.page.goto('/login');
+  }
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }
+
+  async getErrorMessage() {
+    return this.errorMessage.textContent();
+  }
+}
+```
+
+## Using Page Objects in Tests
+
+```typescript
+// tests/login.spec.ts
+import { test, expect } from '@playwright/test';
+import { LoginPage } from '../pages/LoginPage';
+
+test('successful login redirects to dashboard', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+
+  await loginPage.goto();
+  await loginPage.login('user@test.com', 'password123');
+
+  await expect(page).toHaveURL(/dashboard/);
+});
+
+test('invalid credentials show error', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+
+  await loginPage.goto();
+  await loginPage.login('user@test.com', 'wrongpassword');
+
+  await expect(loginPage.errorMessage).toBeVisible();
+});
+```
+
+## Custom Fixtures
+
+```typescript
+// fixtures.ts
+import { test as base } from '@playwright/test';
+import { LoginPage } from './pages/LoginPage';
+import { DashboardPage } from './pages/DashboardPage';
+
+type Fixtures = {
+  loginPage: LoginPage;
+  dashboardPage: DashboardPage;
+  authenticatedPage: Page;
+};
+
+export const test = base.extend<Fixtures>({
+  loginPage: async ({ page }, use) => {
+    await use(new LoginPage(page));
+  },
+
+  dashboardPage: async ({ page }, use) => {
+    await use(new DashboardPage(page));
+  },
+
+  authenticatedPage: async ({ page }, use) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.login('user@test.com', 'password123');
+    await page.waitForURL(/dashboard/);
+    await use(page);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+## Using Fixtures
+
+```typescript
+// tests/dashboard.spec.ts
+import { test, expect } from '../fixtures';
+
+test('shows user profile', async ({ authenticatedPage, dashboardPage }) => {
+  await expect(dashboardPage.userProfile).toBeVisible();
+});
+```
+
+## Component Page Objects
+
+```typescript
+// components/NavBar.ts
+export class NavBar {
+  constructor(private page: Page) {}
+
+  readonly homeLink = () => this.page.getByRole('link', { name: 'Home' });
+  readonly profileLink = () => this.page.getByRole('link', { name: 'Profile' });
+  readonly logoutButton = () => this.page.getByRole('button', { name: 'Logout' });
+
+  async logout() {
+    await this.logoutButton().click();
+  }
+}
+
+// pages/DashboardPage.ts
+export class DashboardPage {
+  readonly navBar: NavBar;
+
+  constructor(private page: Page) {
+    this.navBar = new NavBar(page);
+  }
+}
+```
+
+## Quick Reference
+
+| Pattern | Purpose |
+|---------|---------|
+| Page Object | Encapsulate page interactions |
+| Fixture | Share setup across tests |
+| Component PO | Reusable UI components |
+| Locator methods | Lazy evaluation |
+
+| Best Practice | Reason |
+|---------------|--------|
+| Methods for actions | Readable tests |
+| Locators as getters | Lazy evaluation |
+| No assertions in PO | Flexibility |
+| Fixtures for setup | DRY, maintainable |

package/skills/quality/playwright-expert/references/selectors-locators.md

@@ -0,0 +1,119 @@
+# Selectors & Locators
+
+## Selector Priority (Best to Worst)
+
+```typescript
+// 1. Role-based (BEST - accessible)
+await page.getByRole('button', { name: 'Submit' });
+await page.getByRole('textbox', { name: 'Email' });
+await page.getByRole('link', { name: 'Home' });
+await page.getByRole('heading', { level: 1 });
+
+// 2. Label/placeholder (good for forms)
+await page.getByLabel('Email address');
+await page.getByPlaceholder('Enter your email');
+
+// 3. Test ID (good for non-semantic elements)
+await page.getByTestId('user-avatar');
+await page.getByTestId('submit-button');
+
+// 4. Text content
+await page.getByText('Welcome back');
+await page.getByText(/welcome/i);  // Case insensitive
+
+// 5. CSS/XPath (AVOID - brittle)
+await page.locator('.submit-btn');  // Last resort
+await page.locator('#email-input');
+```
+
+## Role-Based Selectors
+
+```typescript
+// Buttons
+page.getByRole('button', { name: 'Submit' });
+page.getByRole('button', { name: /save/i });
+
+// Links
+page.getByRole('link', { name: 'Documentation' });
+
+// Inputs
+page.getByRole('textbox', { name: 'Username' });
+page.getByRole('checkbox', { name: 'Remember me' });
+page.getByRole('combobox', { name: 'Country' });
+
+// Navigation
+page.getByRole('navigation');
+page.getByRole('main');
+page.getByRole('banner');
+
+// Tables
+page.getByRole('row', { name: 'John Doe' });
+page.getByRole('cell', { name: 'Active' });
+```
+
+## Filtering Locators
+
+```typescript
+// Filter by text
+page.getByRole('listitem').filter({ hasText: 'Product A' });
+
+// Filter by child locator
+page.getByRole('listitem').filter({
+  has: page.getByRole('button', { name: 'Delete' })
+});
+
+// Filter by NOT having
+page.getByRole('listitem').filter({
+  hasNot: page.getByText('Sold out')
+});
+
+// Chain locators
+page.getByTestId('product-card').getByRole('button', { name: 'Buy' });
+```
+
+## Handling Multiple Elements
+
+```typescript
+// Get nth element (0-indexed)
+page.getByRole('listitem').nth(0);
+page.getByRole('listitem').first();
+page.getByRole('listitem').last();
+
+// Count elements
+const count = await page.getByRole('listitem').count();
+
+// Iterate
+for (const item of await page.getByRole('listitem').all()) {
+  console.log(await item.textContent());
+}
+```
+
+## Test IDs
+
+```html
+<!-- Add in HTML -->
+<button data-testid="submit-button">Submit</button>
+```
+
+```typescript
+// Configure custom attribute
+// playwright.config.ts
+use: {
+  testIdAttribute: 'data-test-id'
+}
+
+// Use in tests
+page.getByTestId('submit-button');
+```
+
+## Quick Reference
+
+| Locator | Best For |
+|---------|----------|
+| `getByRole()` | Buttons, links, inputs |
+| `getByLabel()` | Form fields |
+| `getByPlaceholder()` | Inputs without labels |
+| `getByTestId()` | Non-semantic elements |
+| `getByText()` | Static text |
+| `filter()` | Narrowing results |
+| `nth()` / `first()` | Multiple matches |