symfonia-ai-tools 1.0.0

package/templates/packs/playwright/_ai/skills/playwright-codereview/SKILL.md

@@ -0,0 +1,642 @@
+---
+name: playwright-codereview
+description: Reviews Playwright test code for quality, best practices, maintainability, and adherence to project conventions. Provides actionable feedback on Page Object Models, selectors, test structure, data management, and performance optimization.
+---
+
+# Playwright Code Review
+
+Expert skill for reviewing Playwright E2E test code quality and ensuring adherence to best practices.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Requests code review for Playwright tests
+- Asks "review my test code"
+- Wants feedback on test quality or maintainability
+- Needs help improving existing tests
+- Asks about test refactoring opportunities
+- Wants to verify compliance with project standards
+- Requests optimization suggestions
+- Asks "is this test written correctly?"
+
+## Review Checklist
+
+### 1. File Organization & Naming
+
+**Check:**
+- File follows `NN_NN_NN_TestName.spec.ts` format
+- Located in correct module directory (`tests/NN_Module/`)
+- Numbers align with module hierarchy
+- Descriptive name with underscores
+
+**Example Issues:**
+
+```typescript
+// Wrong: Incorrect naming
+// File: login-test.spec.ts
+
+// Correct
+// File: 01_01_01_Login_scenarios.spec.ts
+```
+
+### 2. Test Structure & Organization
+
+**Check:**
+- Uses `test.describe()` with descriptive name
+- Has appropriate tags (`@verified`, `@smoke`, `@module`)
+- Uses `test.step()` for multi-step tests
+- Clear test names with scenario description
+- Proper `beforeEach`/`afterEach` setup
+
+**Example Review:**
+
+```typescript
+// Poor structure
+test('login test', async ({ page }) => {
+    await page.goto('/login');
+    await page.fill('#email', 'test@test.com');
+    await page.click('#submit');
+    expect(page.url()).toContain('/dashboard');
+});
+
+// Good structure
+test.describe('01_Login - tests', { tag: ['@login', '@verified'] }, () => {
+    let loginPage: LoginPage;
+
+    test.beforeEach(async ({ page }) => {
+        loginPage = new LoginPage(page);
+        await page.goto('/login');
+        await clearBrowserStorage(page);
+    });
+
+    test('01_01_01: Login - positive result', async ({ page }) => {
+        const credentials = await {{CREDENTIALS_LOADER}}.getCredentials();
+
+        await test.step('Fill credentials', async () => {
+            await loginPage.fillEmail(credentials.email.right);
+            await loginPage.fillPassword(credentials.password.right);
+        });
+
+        await test.step('Submit and verify', async () => {
+            await loginPage.clickLoginButton();
+            await loginPage.verifySuccessfulLogin();
+        });
+    });
+});
+```
+
+### 3. Page Object Model (POM) Usage
+
+**Check:**
+- Uses Page Objects instead of direct page interactions
+- POMs exported from `pages/index.ts`
+- Locators defined as `private readonly`
+- Methods are descriptive and focused
+- No business logic in tests
+
+**Example Review:**
+
+```typescript
+// No POM - direct page interactions
+test('login', async ({ page }) => {
+    await page.locator('[data-testid="email-input"]').fill('test@test.com');
+    await page.locator('[data-testid="password-input"]').fill('password');
+    await page.locator('[data-testid="submit-button"]').click();
+});
+
+// Proper POM usage
+test('01_01_01: Login - positive result', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    const credentials = await {{CREDENTIALS_LOADER}}.getCredentials();
+
+    await loginPage.login(credentials.email.right, credentials.password.right);
+    await loginPage.verifySuccessfulLogin();
+});
+```
+
+**POM Quality Check:**
+
+```typescript
+// Poor POM - public locators, no encapsulation
+export class LoginPage {
+    public emailInput: Locator;
+    public passwordInput: Locator;
+
+    constructor(public page: Page) {
+        this.emailInput = page.locator('#email');
+        this.passwordInput = page.locator('#password');
+    }
+}
+
+// Good POM - encapsulated, descriptive methods
+export class LoginPage {
+    protected page: Page;
+
+    private readonly emailInput: Locator;
+    private readonly passwordInput: Locator;
+    private readonly submitButton: Locator;
+
+    constructor(page: Page) {
+        this.page = page;
+        this.emailInput = page.locator('[data-testid="login-email-input"]');
+        this.passwordInput = page.locator('[data-testid="login-password-input"]');
+        this.submitButton = page.locator('[data-testid="login-submit-button"]');
+    }
+
+    /**
+     * Fill email input field
+     */
+    async fillEmail(email: string): Promise<void> {
+        await this.emailInput.waitFor({ state: 'visible' });
+        await this.emailInput.clear();
+        await this.emailInput.fill(email);
+    }
+
+    /**
+     * Complete login flow
+     */
+    async login(email: string, password: string): Promise<void> {
+        await this.fillEmail(email);
+        await this.fillPassword(password);
+        await this.submitButton.click();
+    }
+}
+```
+
+### 4. Selectors & Locators
+
+**Check:**
+- Uses `data-testid` selectors (preferred)
+- Follows naming convention: `module-element-type`
+- Uses `getByDataTestId()` helper
+- Provides fallbacks for legacy selectors
+- Avoids fragile CSS class selectors
+
+**Example Review:**
+
+```typescript
+// Bad selectors
+private emailInput = this.page.locator('.form-input.email-field');
+private submitBtn = this.page.locator('button.btn-primary');
+private error = this.page.locator('div.alert.alert-danger');
+
+// Good selectors
+private readonly emailInput: Locator = this.page.locator('[data-testid="login-email-input"]');
+private readonly submitButton: Locator = this.page.locator('[data-testid="login-submit-button"]');
+private readonly errorAlert: Locator = this.page.locator('[data-testid="login-error-alert"]');
+
+// Even better - with helper and fallbacks
+private readonly emailInput: Locator = this.page
+    .locator('[data-testid="loginViewEmailStepInput"], [data-testid="loginEmailInput"]')
+    .first();
+```
+
+**Naming Convention Check:**
+
+```typescript
+// Wrong naming
+data-testid="emailInput"           // Missing module prefix
+data-testid="login_email_input"    // Wrong separator (underscore)
+data-testid="loginEmailInput"      // camelCase instead of kebab-case
+
+// Correct naming
+data-testid="login-email-input"
+data-testid="login-password-input"
+data-testid="login-submit-button"
+data-testid="tasks-add-new-button"
+```
+
+### 5. Test Data & Fixtures
+
+**Check:**
+- Uses `{{CREDENTIALS_LOADER}}` for credentials
+- No hardcoded credentials
+- Dynamic data loading from fixtures
+- Uses environment variables appropriately
+- Proper TypeScript interfaces for data
+
+**Example Review:**
+
+```typescript
+// Hardcoded credentials
+test('login', async ({ page }) => {
+    await loginPage.login('test@example.com', 'Password123!');
+});
+
+// Dynamic credentials
+test('01_01_01: Login', async ({ page }) => {
+    const credentials = await {{CREDENTIALS_LOADER}}.getCredentials();
+    await loginPage.login(credentials.email.right, credentials.password.right);
+});
+
+// Hardcoded test data
+const userData = {
+    name: 'John Doe',
+    email: 'john@test.com'
+};
+
+// Fixture-based test data
+const appData = await {{CREDENTIALS_LOADER}}.getAllData();
+const testUser = appData.users.admin;
+```
+
+### 6. Waits & Stability
+
+**Check:**
+- Waits for visibility before interactions
+- Uses `waitForLoadState('networkidle')` when needed
+- Proper timeout configuration
+- No arbitrary `page.waitForTimeout()`
+- Handles async operations correctly
+
+**Example Review:**
+
+```typescript
+// No waits - flaky test
+await page.locator('[data-testid="button"]').click();
+await expect(page.locator('[data-testid="result"]')).toBeVisible();
+
+// Arbitrary timeout
+await page.waitForTimeout(3000);
+await page.locator('[data-testid="button"]').click();
+
+// Proper waits
+await page.locator('[data-testid="button"]').waitFor({ state: 'visible' });
+await page.locator('[data-testid="button"]').click();
+await page.waitForLoadState('networkidle');
+await expect(page.locator('[data-testid="result"]')).toBeVisible();
+
+// In POM method
+async clickSubmitButton(): Promise<void> {
+    await this.submitButton.waitFor({ state: 'visible' });
+    await this.submitButton.click();
+    await this.page.waitForLoadState('networkidle');
+}
+```
+
+### 7. Assertions & Verifications
+
+**Check:**
+- Uses specific Playwright assertions
+- Meaningful assertion messages
+- Verifies state changes
+- Tests both positive and negative scenarios
+- Appropriate timeout for assertions
+
+**Example Review:**
+
+```typescript
+// Generic assertions
+expect(await page.url()).toBe('{{BASE_URL}}/dashboard');
+expect(await page.locator('.alert').isVisible()).toBe(true);
+
+// Specific Playwright assertions
+await expect(page).toHaveURL(/\/dashboard/);
+await expect(page.locator('[data-testid="error-alert"]')).toBeVisible();
+await expect(page.locator('[data-testid="submit-button"]')).toBeDisabled();
+
+// Verification methods in POM
+async verifySuccessfulLogin(): Promise<void> {
+    await this.page.waitForURL(/\/dashboard/, { timeout: 15000 });
+    await this.page.waitForLoadState('networkidle');
+}
+
+async verifyErrorAlert(): Promise<void> {
+    await this.errorAlert.waitFor({ state: 'visible', timeout: 5000 });
+}
+```
+
+### 8. Browser State Management
+
+**Check:**
+- Clears browser storage in `beforeEach`
+- Navigates to clean state before tests
+- Uses session management when appropriate
+- Proper cleanup in `afterEach` if needed
+
+**Example Review:**
+
+```typescript
+// No cleanup - state leaks between tests
+test.beforeEach(async ({ page }) => {
+    await page.goto('/login');
+});
+
+// Proper cleanup
+test.beforeEach(async ({ page }) => {
+    loginPage = new LoginPage(page);
+    await page.goto('/login');
+
+    // Clear all browser storage
+    await clearBrowserStorage(page);
+
+    // Wait for page ready state
+    await loginPage.waitForPageReady();
+});
+```
+
+### 9. TypeScript Best Practices
+
+**Check:**
+- Proper type annotations
+- Interfaces for complex objects
+- No `any` types
+- Async/await consistency
+- Proper error handling
+
+**Example Review:**
+
+```typescript
+// Poor TypeScript
+async function getLoginData() {
+    const data: any = await {{CREDENTIALS_LOADER}}.getCredentials();
+    return data;
+}
+
+// Good TypeScript
+interface ILoginData {
+    validEmail: string;
+    validPassword: string;
+    invalidEmail: string;
+    invalidPassword: string;
+}
+
+async function getLoginData(): Promise<ILoginData> {
+    const credentials = await {{CREDENTIALS_LOADER}}.getCredentials();
+
+    return {
+        validEmail: credentials.email.right,
+        validPassword: credentials.password.right,
+        invalidEmail: credentials.email.wrong,
+        invalidPassword: credentials.password.wrong,
+    };
+}
+```
+
+### 10. Tags & Test Categories
+
+**Check:**
+- Appropriate tags assigned
+- `@verified` for stable tests
+- `@smoke` for critical paths
+- Module-specific tags (`@login`, `@tasks`)
+- Tags at describe or test level
+
+**Example Review:**
+
+```typescript
+// No tags
+test.describe('Login tests', () => {
+    test('successful login', async ({ page }) => {
+        // test
+    });
+});
+
+// Proper tagging
+test.describe('01_Login - tests', { tag: ['@login', '@verified', '@smoke'] }, () => {
+    test('01_01_01: Login - positive result', async ({ page }) => {
+        // test
+    });
+
+    // Override tags for specific test
+    test('01_01_02: Login - edge case', { tag: '@login' }, async ({ page }) => {
+        // test
+    });
+});
+```
+
+## Code Review Process
+
+### Step 1: Initial Assessment
+
+1. Check file location and naming
+2. Verify test structure basics
+3. Identify obvious anti-patterns
+4. Note missing imports or utilities
+
+### Step 2: Deep Review
+
+1. Analyze POM usage and quality
+2. Review selector strategy
+3. Check data management
+4. Verify waits and stability
+5. Assess assertions quality
+
+### Step 3: Provide Feedback
+
+**Format:**
+
+```markdown
+## Review Summary
+
+### Strengths
+- Good use of Page Objects
+- Proper test.step() usage
+- Clear test naming
+
+### Issues Found
+
+**1. Selector Quality (High Priority)**
+- Line 15: Using CSS class selector instead of data-testid
+- Line 23: Hardcoded selector without fallback
+
+**2. Missing Waits (Medium Priority)**
+- Line 30: Click without waiting for visibility
+- Line 45: No networkidle wait after navigation
+
+**3. Hardcoded Data (Low Priority)**
+- Line 12: Hardcoded email instead of {{CREDENTIALS_LOADER}}
+
+### Suggested Changes
+
+[Provide specific code examples]
+
+### Quality Score: 7/10
+
+**Areas for Improvement:**
+1. Improve selector strategy
+2. Add proper waits
+3. Use dynamic test data
+```
+
+### Step 4: Suggest Refactoring
+
+Provide concrete refactoring examples:
+
+```typescript
+// BEFORE
+test('login test', async ({ page }) => {
+    await page.goto('/login');
+    await page.locator('.email-input').fill('test@test.com');
+    await page.locator('.password-input').fill('pass123');
+    await page.locator('.submit-btn').click();
+    expect(page.url()).toContain('/dashboard');
+});
+
+// AFTER
+test('01_01_01: Login - positive result', async ({ page }) => {
+    const credentials = await {{CREDENTIALS_LOADER}}.getCredentials();
+
+    await test.step('Login with valid credentials', async () => {
+        await loginPage.login(credentials.email.right, credentials.password.right);
+    });
+
+    await test.step('Verify successful redirect', async () => {
+        await loginPage.verifySuccessfulLogin();
+        await expect(page).toHaveURL(/\/dashboard/);
+    });
+});
+```
+
+## Common Review Findings
+
+### Critical Issues (Must Fix)
+
+1. **Hardcoded Credentials**
+   - Impact: Security risk, inflexibility
+   - Fix: Use `{{CREDENTIALS_LOADER}}.getCredentials()`
+
+2. **No Page Objects**
+   - Impact: Poor maintainability, code duplication
+   - Fix: Create proper POM classes
+
+3. **CSS Class Selectors**
+   - Impact: Fragile tests, high maintenance
+   - Fix: Use `data-testid` selectors
+
+4. **Missing Waits**
+   - Impact: Flaky tests, unreliable CI/CD
+   - Fix: Add `.waitFor({ state: 'visible' })`
+
+### Medium Issues (Should Fix)
+
+1. **No Test Steps**
+   - Impact: Poor reporting, hard to debug
+   - Fix: Wrap logic in `test.step()`
+
+2. **Missing Tags**
+   - Impact: Can't filter tests effectively
+   - Fix: Add appropriate tags
+
+3. **No Browser Cleanup**
+   - Impact: State leaks between tests
+   - Fix: Use `clearBrowserStorage()` in `beforeEach`
+
+### Low Issues (Nice to Have)
+
+1. **Missing JSDoc**
+   - Impact: Reduced code clarity
+   - Fix: Add documentation comments
+
+2. **Inconsistent Naming**
+   - Impact: Harder to navigate
+   - Fix: Follow NN_NN_NN convention
+
+3. **No TypeScript Interfaces**
+   - Impact: Reduced type safety
+   - Fix: Define proper interfaces
+
+## Review Templates
+
+### Quick Review Template
+
+```markdown
+## Playwright Test Review
+
+**File**: `[file path]`
+**Reviewer**: AI Agent
+**Date**: [date]
+
+### Summary
+[Brief overview]
+
+### Checklist
+- [ ] File naming convention
+- [ ] Test structure (describe, tags, steps)
+- [ ] Page Object usage
+- [ ] Selector quality (data-testid)
+- [ ] Test data management
+- [ ] Waits and stability
+- [ ] Assertions quality
+- [ ] Browser cleanup
+- [ ] TypeScript types
+
+### Key Findings
+1. [Issue 1]
+2. [Issue 2]
+3. [Issue 3]
+
+### Recommendations
+[List of action items]
+
+### Overall Score: X/10
+```
+
+### Detailed Review Template
+
+Use the 10-point checklist above and provide specific line-by-line feedback.
+
+## Performance Review
+
+### Check for Performance Issues
+
+1. **Unnecessary waits**
+   - Avoid `page.waitForTimeout()` unless absolutely needed
+   - Use specific waits (`waitFor`, `waitForLoadState`)
+
+2. **Inefficient selectors**
+   - Use data-testid instead of complex CSS
+   - Avoid xpath when possible
+
+3. **Redundant navigation**
+   - Navigate once in `beforeEach`, not in every test
+
+4. **Missing parallel execution support**
+   - Tests should be independent
+   - No shared state between tests
+
+## Maintainability Review
+
+### Check for Maintainability
+
+1. **Code duplication**
+   - Repeated selectors -> Move to POM
+   - Repeated actions -> Create helper methods
+   - Repeated data -> Use fixtures
+
+2. **Magic numbers/strings**
+   - Hardcoded values -> Use constants or fixtures
+   - Inline timeouts -> Use config defaults
+
+3. **Poor naming**
+   - Unclear variable names
+   - Generic method names
+   - Missing context
+
+4. **Missing documentation**
+   - No JSDoc for complex methods
+   - No comments for non-obvious logic
+
+## Quick Reference: Review Priorities
+
+| Priority | Issue | Impact | Fix Effort |
+|----------|-------|--------|------------|
+| Critical | Hardcoded credentials | Security | Low |
+| Critical | No POM usage | Maintainability | High |
+| Critical | CSS class selectors | Fragility | Medium |
+| Medium | Missing waits | Flakiness | Low |
+| Medium | No test steps | Debugging | Low |
+| Medium | Missing tags | Filtering | Low |
+| Low | No JSDoc | Clarity | Medium |
+| Low | Inconsistent naming | Navigation | Low |
+
+## Resources
+
+- **Main Playwright Skill**: `.github/skills/playwright/SKILL.md`
+- **Project README**: `{{PLAYWRIGHT_DIR}}/README.md`
+- **Playwright Best Practices**: https://playwright.dev/docs/best-practices
+
+---
+
+**Remember**: Code review should be constructive and educational. Provide specific examples and actionable feedback.