digiqagent 1.2.0

package/skills/playwright-test-generator/SKILL.md

@@ -0,0 +1,563 @@
+---
+name: playwright-test-generator
+description: Use when generating Playwright end-to-end test scripts for Angular or React frontend applications by analyzing components, click events, forms, routing, modals, and user interactions
+---
+
+# Playwright Test Generator
+
+## Overview
+
+Analyze a frontend codebase — Angular or React — and produce a complete suite of Playwright end-to-end tests using the Page Object Model pattern. Tests cover every route, every form, every click handler, every modal, and every interactive element with both positive and negative scenarios.
+
+**Core principle:** If a user can interact with it, there must be a test for it. If it can fail, there must be a test proving the failure is handled.
+
+## When to Use
+
+- Frontend project needs E2E test coverage
+- New Angular or React application with no Playwright tests
+- Existing application with incomplete or outdated E2E tests
+- QA handoff — provide runnable Playwright scripts
+- Pre-release verification — structured UI test pass
+
+## Step 0 — Detect Project Type
+
+**This step is mandatory. Do it first, before anything else.**
+
+Examine the project root to determine the frontend framework:
+
+| Signal | Framework |
+|--------|-----------|
+| `angular.json` or `nx.json` with Angular projects | Angular |
+| `@angular/core` in `package.json` dependencies | Angular |
+| `react` and `react-dom` in `package.json` dependencies | React |
+| `next` in `package.json` dependencies | React (Next.js) |
+| `gatsby` in `package.json` dependencies | React (Gatsby) |
+| `.jsx` / `.tsx` files containing JSX syntax | React |
+| `*.component.ts` + `*.component.html` file pairs | Angular |
+
+Also detect the **component library** in use — this determines selectors:
+
+| Library | Framework | Selector Patterns |
+|---------|-----------|-------------------|
+| `@angular/material` | Angular | `mat-input`, `mat-select`, `mat-dialog-container`, `mat-table`, `mat-paginator`, `mat-tab-group` |
+| `ng-zorro-antd` | Angular | `nz-input`, `nz-select`, `nz-modal`, `nz-table`, `nz-pagination` |
+| `primeng` | Angular | `p-inputtext`, `p-dropdown`, `p-dialog`, `p-table`, `p-paginator` |
+| `@mui/material` | React | `MuiTextField`, `MuiSelect`, `MuiDialog`, `MuiDataGrid`, `MuiPagination` |
+| `antd` | React | `ant-input`, `ant-select`, `ant-modal`, `ant-table`, `ant-pagination` |
+| `@chakra-ui/react` | React | Chakra uses standard HTML with `data-*` attrs |
+| None / custom | Either | Standard HTML elements |
+
+**If the project is not Angular or React, STOP.** Inform the developer this skill supports Angular and React only. Suggest alternatives for Vue, Svelte, etc.
+
+## Step 1 — Map Pages and Routes
+
+Build a complete sitemap from the routing configuration.
+
+### Angular
+
+Scan for routing modules:
+- `app-routing.module.ts` or `app.routes.ts` (standalone)
+- Lazy-loaded feature routing modules
+- `RouterModule.forRoot(...)` and `RouterModule.forChild(...)`
+- Route guards (`canActivate`, `canDeactivate`) — note which routes are protected
+
+Extract:
+```
+/                → HomeComponent (public)
+/login           → LoginComponent (public)
+/dashboard       → DashboardComponent (auth guard)
+/users           → UserListComponent (auth guard)
+/users/:id       → UserDetailComponent (auth guard)
+/users/new       → UserFormComponent (auth + role guard)
+/settings        → SettingsComponent (auth guard)
+```
+
+### React
+
+Scan for route definitions:
+- `<Route>` elements in React Router (`react-router-dom`)
+- `<BrowserRouter>`, `<Routes>`, `<Route>`
+- Next.js: `app/` directory structure (App Router) or `pages/` directory (Pages Router)
+- Protected route wrapper components
+- `useNavigate`, `useLocation`, `useParams` usage
+
+Extract the same route → component → guard mapping.
+
+## Step 2 — Discover Components and Interactions
+
+For each page/route, scan its component tree and catalog every interactive element.
+
+### Angular Component Scanning
+
+Scan `*.component.html` templates and `*.component.ts` class files:
+
+| Template Pattern | Interaction Type | Test Action |
+|-----------------|-----------------|-------------|
+| `(click)="handler()"` | Click event | `click()` |
+| `(dblclick)="handler()"` | Double-click | `dblclick()` |
+| `(submit)="handler()"` | Form submission | Fill + submit |
+| `[(ngModel)]="field"` | Two-way binding input | `fill()` |
+| `[formGroup]` / `formControlName` | Reactive form field | `fill()` + validation |
+| `routerLink="/path"` | Navigation link | `click()` + assert URL |
+| `[routerLink]="['/path', id]"` | Dynamic navigation | `click()` + assert URL |
+| `*ngIf="condition"` | Conditional display | Assert visible/hidden |
+| `*ngFor="let item of items"` | List rendering | Assert count, content |
+| `<mat-dialog>` / `MatDialog.open()` | Modal dialog | Open, verify, close |
+| `<mat-menu>` | Dropdown menu | Open, select, close |
+| `<mat-tab-group>` | Tab navigation | Click tabs, verify content |
+| `<mat-table>` | Data table | Sort, paginate, row actions |
+| `<mat-select>` | Select dropdown | Open, pick option |
+| `<mat-checkbox>` / `<mat-radio>` | Toggle inputs | Check/uncheck |
+| `<mat-datepicker>` | Date picker | Open, select date |
+| `<input type="file">` | File upload | Set input files |
+| `<mat-snack-bar>` / toast | Notification | Assert appears + content |
+
+### React Component Scanning
+
+Scan `*.tsx` / `*.jsx` files:
+
+| Code Pattern | Interaction Type | Test Action |
+|-------------|-----------------|-------------|
+| `onClick={handler}` | Click event | `click()` |
+| `onDoubleClick={handler}` | Double-click | `dblclick()` |
+| `onSubmit={handler}` | Form submission | Fill + submit |
+| `onChange={handler}` on `<input>` | Input change | `fill()` |
+| `useForm()` / `<Formik>` / `react-hook-form` | Form with validation | Fill + validate |
+| `<Link to="/path">` | Navigation link | `click()` + assert URL |
+| `useNavigate()` | Programmatic navigation | Trigger + assert URL |
+| `useState` controlling modal/drawer | Modal/drawer toggle | Open, verify, close |
+| `<Dialog>` / `<Modal>` | Modal dialog | Open, verify, close |
+| `<Drawer>` | Side drawer | Open, verify, close |
+| `<Tabs>` / `<Tab>` | Tab navigation | Click tabs, verify content |
+| `<Select>` / `<Autocomplete>` | Select dropdown | Open, pick option |
+| `<Checkbox>` / `<Switch>` | Toggle inputs | Check/uncheck |
+| `<DataGrid>` / `<Table>` | Data table | Sort, paginate, row actions |
+| `<input type="file">` | File upload | Set input files |
+| `<Snackbar>` / `toast()` | Notification | Assert appears + content |
+| `{condition && <Component>}` | Conditional render | Assert visible/hidden |
+| `{items.map(item => ...)}` | List rendering | Assert count, content |
+
+### Interaction Catalog Output
+
+For each component, produce a structured list:
+
+```
+Page: /users
+Component: UserListComponent
+Interactions:
+  - CLICK: "Add User" button → navigates to /users/new
+  - CLICK: Edit icon per row → navigates to /users/:id
+  - CLICK: Delete icon per row → opens confirm dialog
+  - TABLE: sortable columns (Name, Email, Created)
+  - TABLE: pagination (page size selector, next/prev)
+  - SEARCH: filter input → filters table rows
+  - MODAL: delete confirmation → confirm/cancel
+  - EMPTY STATE: "No users found" when list empty
+```
+
+## Step 3 — Build Test Plan Per Page
+
+For each page, define positive and negative scenarios.
+
+### Positive Scenarios (Happy Path)
+
+Every page must have:
+- **Page load** — correct URL, title, key elements visible
+- **Content display** — expected text, images, data rendered
+- **Navigation** — links lead to correct destinations
+- **Forms** — valid data submission succeeds, success feedback shown
+- **Tables** — data displayed, sorting works, pagination works
+- **Modals** — open with correct content, actions execute, close properly
+- **Search/filter** — produces expected filtered results
+
+### Negative Scenarios (Error/Edge Cases)
+
+Every page with forms must have:
+- **Empty required fields** — submit with each required field blank, one at a time, verify field-specific error
+- **Invalid format** — wrong email format, phone format, date format
+- **Boundary values** — too short (min length), too long (max length), out of range numbers
+- **Special characters** — SQL injection attempts, XSS strings, Unicode edge cases
+- **Double submit** — rapid double-click on submit button doesn't create duplicates
+
+Every page with auth requirements must have:
+- **Unauthenticated access** — redirect to login
+- **Insufficient permissions** — forbidden message or hidden elements
+
+Every page with data must have:
+- **Empty state** — no data displays appropriate message/illustration
+- **Error state** — API failure shows error message, retry option
+- **Loading state** — skeleton/spinner during data fetch
+
+## Step 4 — Generate Playwright Test Files
+
+### File Structure
+
+```
+e2e/
+  playwright.config.ts
+  pages/
+    base.page.ts
+    login.page.ts
+    dashboard.page.ts
+    user-list.page.ts
+    user-form.page.ts
+  tests/
+    auth/
+      login.spec.ts
+      logout.spec.ts
+    users/
+      user-list.spec.ts
+      user-form.spec.ts
+      user-delete.spec.ts
+    navigation/
+      routing.spec.ts
+      protected-routes.spec.ts
+    responsive/
+      mobile-layout.spec.ts
+      tablet-layout.spec.ts
+    accessibility/
+      keyboard-navigation.spec.ts
+      aria-labels.spec.ts
+  fixtures/
+    test-data.ts
+    auth.setup.ts
+```
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Test files | `kebab-case.spec.ts` | `user-list.spec.ts` |
+| Page objects | `kebab-case.page.ts` | `user-list.page.ts` |
+| POM class | PascalCase + `Page` | `UserListPage` |
+| Test describe | Feature name | `'User List'` |
+| Test name | Action + expected result | `'should display validation error when email is empty'` |
+| Fixtures | `kebab-case.ts` | `test-data.ts` |
+
+### Locator Strategy
+
+Use locators in this priority order. Never skip to CSS selectors without trying higher-priority options:
+
+| Priority | Method | When to Use | Example |
+|----------|--------|-------------|---------|
+| 1 | `data-testid` | Best — stable, decoupled from UI | `page.getByTestId('submit-btn')` |
+| 2 | Role + name | Accessible elements | `page.getByRole('button', { name: 'Submit' })` |
+| 3 | Label | Form inputs | `page.getByLabel('Email')` |
+| 4 | Placeholder | Inputs without labels | `page.getByPlaceholder('Enter email')` |
+| 5 | Text | Static text content | `page.getByText('Welcome back')` |
+| 6 | CSS selector | Last resort | `page.locator('.custom-widget')` |
+
+**If the codebase lacks `data-testid` attributes**, note this in the output and recommend adding them. Generate tests using role/label/text locators, but include a comment suggesting `data-testid` for stability.
+
+### Positive Test Example
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { LoginPage } from '../pages/login.page';
+
+test.describe('Login', () => {
+  let loginPage: LoginPage;
+
+  test.beforeEach(async ({ page }) => {
+    loginPage = new LoginPage(page);
+    await loginPage.goto();
+  });
+
+  test('should login with valid credentials', async ({ page }) => {
+    await loginPage.fillEmail('admin@example.com');
+    await loginPage.fillPassword('SecureP@ss123');
+    await loginPage.clickSubmit();
+
+    await expect(page).toHaveURL(/\/dashboard/);
+    await expect(page.getByRole('heading', { name: /dashboard/i })).toBeVisible();
+  });
+
+  test('should display welcome message after login', async ({ page }) => {
+    await loginPage.login('admin@example.com', 'SecureP@ss123');
+    await expect(page.getByText(/welcome/i)).toBeVisible();
+  });
+});
+```
+
+### Negative Test Example
+
+```typescript
+test.describe('Login - Validation', () => {
+  test('should show error when email is empty', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.fillPassword('SecureP@ss123');
+    await loginPage.clickSubmit();
+
+    await expect(loginPage.emailError).toBeVisible();
+    await expect(loginPage.emailError).toContainText(/required|email/i);
+  });
+
+  test('should show error for invalid email format', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.fillEmail('not-an-email');
+    await loginPage.fillPassword('SecureP@ss123');
+    await loginPage.clickSubmit();
+
+    await expect(loginPage.emailError).toBeVisible();
+    await expect(loginPage.emailError).toContainText(/valid|format|email/i);
+  });
+
+  test('should show error for incorrect credentials', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.login('wrong@example.com', 'WrongPass123');
+
+    await expect(loginPage.generalError).toBeVisible();
+    await expect(loginPage.generalError).toContainText(/invalid|incorrect|failed/i);
+  });
+
+  test('should not submit form when required fields are empty', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.clickSubmit();
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(loginPage.emailError).toBeVisible();
+    await expect(loginPage.passwordError).toBeVisible();
+  });
+});
+```
+
+### Responsive Test Example
+
+```typescript
+import { test, expect, devices } from '@playwright/test';
+
+test.describe('Responsive - Mobile', () => {
+  test.use({ ...devices['iPhone 13'] });
+
+  test('should show hamburger menu on mobile', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.getByRole('button', { name: /menu/i })).toBeVisible();
+    await expect(page.getByRole('navigation')).not.toBeVisible();
+  });
+
+  test('should open sidebar on hamburger click', async ({ page }) => {
+    await page.goto('/');
+    await page.getByRole('button', { name: /menu/i }).click();
+    await expect(page.getByRole('navigation')).toBeVisible();
+  });
+});
+
+test.describe('Responsive - Desktop', () => {
+  test.use({ viewport: { width: 1440, height: 900 } });
+
+  test('should show sidebar navigation on desktop', async ({ page }) => {
+    await page.goto('/dashboard');
+    await expect(page.getByRole('navigation')).toBeVisible();
+  });
+});
+```
+
+### Accessibility Test Example
+
+```typescript
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test.describe('Accessibility', () => {
+  test('login page has no accessibility violations', async ({ page }) => {
+    await page.goto('/login');
+    const results = await new AxeBuilder({ page }).analyze();
+    expect(results.violations).toEqual([]);
+  });
+
+  test('form inputs are keyboard navigable', async ({ page }) => {
+    await page.goto('/login');
+    await page.keyboard.press('Tab');
+    await expect(page.getByLabel('Email')).toBeFocused();
+    await page.keyboard.press('Tab');
+    await expect(page.getByLabel('Password')).toBeFocused();
+    await page.keyboard.press('Tab');
+    await expect(page.getByRole('button', { name: /submit|login/i })).toBeFocused();
+  });
+
+  test('modal can be closed with Escape key', async ({ page }) => {
+    await page.goto('/users');
+    await page.getByRole('button', { name: /delete/i }).first().click();
+    await expect(page.getByRole('dialog')).toBeVisible();
+    await page.keyboard.press('Escape');
+    await expect(page.getByRole('dialog')).not.toBeVisible();
+  });
+});
+```
+
+## Step 5 — Generate Page Objects
+
+Create a Page Object Model class for every page. See @page-object-patterns.md for complete patterns.
+
+### Base Page
+
+Every POM extends a base class:
+
+```typescript
+import { Page, Locator } from '@playwright/test';
+
+export class BasePage {
+  constructor(protected page: Page) {}
+
+  async goto(path: string) {
+    await this.page.goto(path);
+  }
+
+  async getTitle(): Promise<string> {
+    return this.page.title();
+  }
+
+  get loadingSpinner(): Locator {
+    return this.page.getByRole('progressbar');
+  }
+
+  async waitForLoad() {
+    await this.loadingSpinner.waitFor({ state: 'hidden', timeout: 10000 });
+  }
+
+  get toastMessage(): Locator {
+    return this.page.getByRole('alert');
+  }
+}
+```
+
+### Page Object Rules
+
+- One POM per page/route
+- Locators as getter properties (not methods)
+- Actions as async methods (fill, click, submit)
+- Assertions stay in test files, not in POMs
+- Composite actions for common flows (e.g., `login(email, password)`)
+- No test logic in POMs — they are pure page interaction wrappers
+
+## Step 6 — Generate Playwright Config
+
+If `playwright.config.ts` does not already exist, generate one:
+
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e/tests',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { open: 'never' }],
+    ['list']
+  ],
+  use: {
+    baseURL: 'http://localhost:4200', // Angular default; use 3000 for React
+    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'] },
+    },
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+  ],
+  webServer: {
+    command: 'npm start', // Adjust per project
+    url: 'http://localhost:4200',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+Adjust `baseURL`, `webServer.command`, and `webServer.url` based on the detected framework:
+- **Angular:** port `4200`, command `ng serve`
+- **React (CRA):** port `3000`, command `react-scripts start`
+- **React (Vite):** port `5173`, command `vite`
+- **Next.js:** port `3000`, command `next dev`
+
+## Step 7 — Verify
+
+Before claiming test generation is complete:
+
+### Coverage Verification
+
+- [ ] Every route from the router config has at least one test file
+- [ ] Every form has positive tests (valid submission) and negative tests (each validation rule)
+- [ ] Every click handler has a test verifying the expected outcome
+- [ ] Every modal/dialog has open, content verification, and close tests (button, overlay, Escape)
+- [ ] Every table has sort, paginate, and empty state tests
+- [ ] Every dropdown/select has open, select option, and close tests
+- [ ] Auth-protected routes have unauthenticated redirect tests
+- [ ] Role-based features have permission tests
+
+### Quality Verification
+
+- [ ] No hardcoded `waitForTimeout()` calls — use proper Playwright auto-waiting
+- [ ] No flaky CSS-only selectors when role/label/testid alternatives exist
+- [ ] Every `test()` has at least one `expect()` assertion
+- [ ] Page objects cover all page interactions (no raw locators in test files)
+- [ ] Test names describe the scenario: `should [action] when [condition]`
+- [ ] Test data uses realistic values, not `test` or `foo`
+
+### Structural Verification
+
+- [ ] `playwright.config.ts` generated with correct baseURL and webServer
+- [ ] Page objects follow the base class pattern
+- [ ] Tests organized by feature in subdirectories
+- [ ] Responsive tests use device presets, not arbitrary viewport sizes
+- [ ] Accessibility tests use `@axe-core/playwright` for automated checks
+
+Apply `digiqagent:verification-before-completion` — evidence before claims.
+
+## Red Flags — STOP and Fix
+
+| Problem | Fix |
+|---------|-----|
+| Using `page.waitForTimeout(5000)` | Replace with `await expect(locator).toBeVisible()` or proper auto-wait |
+| Using `page.locator('#app > div:nth-child(3) > button')` | Use `page.getByRole('button', { name: '...' })` or `data-testid` |
+| Test has no assertions | Add `expect()` calls — a test without assertions proves nothing |
+| Assertions in page objects | Move assertions to test files; POMs are interaction wrappers only |
+| All tests in one massive file | Split by feature/page into separate `.spec.ts` files |
+| Form has only positive tests | Add negative tests for every validation rule |
+| Auth routes have no guard tests | Add unauthenticated redirect test |
+| No responsive tests | Add mobile/tablet viewport tests for layout changes |
+| No accessibility tests | Add keyboard navigation and `@axe-core` tests |
+| Hardcoded test data in tests | Extract to fixtures or `test-data.ts` |
+| Using `page.evaluate()` for simple interactions | Use Playwright's built-in actions (`click`, `fill`, `check`) |
+| Tests depend on execution order | Each test should be independent; use `beforeEach` for setup |
+| No POM — raw locators everywhere | Generate page objects; tests should read like user stories |
+
+## Common Patterns
+
+See @page-object-patterns.md for Page Object Model reference:
+- Angular Material component POMs
+- React MUI component POMs
+- Login, form, table, and modal POM examples
+
+See @interaction-test-patterns.md for test code patterns:
+- Forms, clicks, navigation, modals, dropdowns, tables
+- Responsive, accessibility, auth flows, error handling
+
+## Integration with Other Skills
+
+- Use `digiqagent:verification-before-completion` before claiming tests are complete
+- Use `digiqagent:test-driven-development` if writing tests for new features being built
+- Use `digiqagent:systematic-debugging` when Playwright tests fail unexpectedly