digiqagent 1.2.0

package/skills/playwright-test-generator/page-object-patterns.md

@@ -0,0 +1,833 @@
+# Page Object Model Patterns
+
+Reference patterns for Playwright Page Object Model classes. Adapt these to the detected framework and component library.
+
+## Base Page
+
+All page objects extend this 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');
+  }
+
+  async getToastText(): Promise<string> {
+    await this.toastMessage.waitFor({ state: 'visible' });
+    return (await this.toastMessage.textContent()) ?? '';
+  }
+
+  get confirmDialog(): Locator {
+    return this.page.getByRole('dialog');
+  }
+
+  async confirmDialogAction() {
+    await this.confirmDialog.getByRole('button', { name: /confirm|yes|ok/i }).click();
+  }
+
+  async cancelDialogAction() {
+    await this.confirmDialog.getByRole('button', { name: /cancel|no/i }).click();
+  }
+}
+```
+
+## Login Page — Complete Example
+
+```typescript
+import { Page, Locator } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class LoginPage extends BasePage {
+  readonly path = '/login';
+
+  constructor(page: Page) {
+    super(page);
+  }
+
+  async goto() {
+    await super.goto(this.path);
+  }
+
+  // --- Locators ---
+
+  get emailInput(): Locator {
+    return this.page.getByLabel('Email');
+  }
+
+  get passwordInput(): Locator {
+    return this.page.getByLabel('Password');
+  }
+
+  get submitButton(): Locator {
+    return this.page.getByRole('button', { name: /login|sign in|submit/i });
+  }
+
+  get emailError(): Locator {
+    return this.page.getByText(/email.*required|enter.*email|valid.*email/i);
+  }
+
+  get passwordError(): Locator {
+    return this.page.getByText(/password.*required|enter.*password/i);
+  }
+
+  get generalError(): Locator {
+    return this.page.getByRole('alert');
+  }
+
+  get forgotPasswordLink(): Locator {
+    return this.page.getByRole('link', { name: /forgot.*password/i });
+  }
+
+  get registerLink(): Locator {
+    return this.page.getByRole('link', { name: /register|sign up|create.*account/i });
+  }
+
+  get rememberMeCheckbox(): Locator {
+    return this.page.getByRole('checkbox', { name: /remember/i });
+  }
+
+  get passwordToggle(): Locator {
+    return this.page.getByRole('button', { name: /show.*password|toggle.*password/i });
+  }
+
+  // --- Actions ---
+
+  async fillEmail(email: string) {
+    await this.emailInput.clear();
+    await this.emailInput.fill(email);
+  }
+
+  async fillPassword(password: string) {
+    await this.passwordInput.clear();
+    await this.passwordInput.fill(password);
+  }
+
+  async clickSubmit() {
+    await this.submitButton.click();
+  }
+
+  async login(email: string, password: string) {
+    await this.fillEmail(email);
+    await this.fillPassword(password);
+    await this.clickSubmit();
+  }
+
+  async toggleRememberMe() {
+    await this.rememberMeCheckbox.click();
+  }
+
+  async clickForgotPassword() {
+    await this.forgotPasswordLink.click();
+  }
+
+  async clickRegister() {
+    await this.registerLink.click();
+  }
+}
+```
+
+## Form Page — Angular Reactive Forms
+
+POM for a form page using Angular Material and Reactive Forms:
+
+```typescript
+import { Page, Locator } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class UserFormPage extends BasePage {
+  readonly createPath = '/users/new';
+
+  constructor(page: Page) {
+    super(page);
+  }
+
+  async gotoCreate() {
+    await super.goto(this.createPath);
+  }
+
+  async gotoEdit(userId: string) {
+    await super.goto(`/users/${userId}/edit`);
+  }
+
+  // --- Form field locators ---
+
+  get nameInput(): Locator {
+    return this.page.getByLabel('Name');
+  }
+
+  get emailInput(): Locator {
+    return this.page.getByLabel('Email');
+  }
+
+  get phoneInput(): Locator {
+    return this.page.getByLabel('Phone');
+  }
+
+  get roleSelect(): Locator {
+    // Angular Material mat-select
+    return this.page.locator('mat-select[formcontrolname="role"]');
+  }
+
+  get activeToggle(): Locator {
+    return this.page.getByRole('switch', { name: /active/i });
+  }
+
+  get dateOfBirthInput(): Locator {
+    return this.page.getByLabel(/date of birth|dob/i);
+  }
+
+  get avatarFileInput(): Locator {
+    return this.page.locator('input[type="file"]');
+  }
+
+  get submitButton(): Locator {
+    return this.page.getByRole('button', { name: /save|submit|create/i });
+  }
+
+  get cancelButton(): Locator {
+    return this.page.getByRole('button', { name: /cancel/i });
+  }
+
+  get formTitle(): Locator {
+    return this.page.getByRole('heading', { level: 1 });
+  }
+
+  // --- Validation error locators ---
+
+  get nameError(): Locator {
+    return this.page.locator('mat-error').filter({ hasText: /name/i });
+  }
+
+  get emailError(): Locator {
+    return this.page.locator('mat-error').filter({ hasText: /email/i });
+  }
+
+  get phoneError(): Locator {
+    return this.page.locator('mat-error').filter({ hasText: /phone/i });
+  }
+
+  // --- Actions ---
+
+  async fillName(name: string) {
+    await this.nameInput.clear();
+    await this.nameInput.fill(name);
+  }
+
+  async fillEmail(email: string) {
+    await this.emailInput.clear();
+    await this.emailInput.fill(email);
+  }
+
+  async fillPhone(phone: string) {
+    await this.phoneInput.clear();
+    await this.phoneInput.fill(phone);
+  }
+
+  async selectRole(role: string) {
+    await this.roleSelect.click();
+    await this.page.getByRole('option', { name: role }).click();
+  }
+
+  async toggleActive() {
+    await this.activeToggle.click();
+  }
+
+  async fillDateOfBirth(date: string) {
+    await this.dateOfBirthInput.clear();
+    await this.dateOfBirthInput.fill(date);
+  }
+
+  async uploadAvatar(filePath: string) {
+    await this.avatarFileInput.setInputFiles(filePath);
+  }
+
+  async clickSubmit() {
+    await this.submitButton.click();
+  }
+
+  async clickCancel() {
+    await this.cancelButton.click();
+  }
+
+  async fillAndSubmit(data: {
+    name: string;
+    email: string;
+    phone?: string;
+    role?: string;
+  }) {
+    await this.fillName(data.name);
+    await this.fillEmail(data.email);
+    if (data.phone) await this.fillPhone(data.phone);
+    if (data.role) await this.selectRole(data.role);
+    await this.clickSubmit();
+  }
+
+  async triggerValidation(fieldLocator: Locator) {
+    await fieldLocator.focus();
+    await fieldLocator.blur();
+  }
+}
+```
+
+## Form Page — React with MUI
+
+POM for a form page using React MUI components:
+
+```typescript
+import { Page, Locator } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class UserFormPage extends BasePage {
+  constructor(page: Page) {
+    super(page);
+  }
+
+  async gotoCreate() {
+    await super.goto('/users/new');
+  }
+
+  // --- Form field locators ---
+
+  get nameInput(): Locator {
+    return this.page.getByLabel('Name');
+  }
+
+  get emailInput(): Locator {
+    return this.page.getByLabel('Email');
+  }
+
+  get roleSelect(): Locator {
+    return this.page.getByLabel('Role');
+  }
+
+  get activeCheckbox(): Locator {
+    return this.page.getByRole('checkbox', { name: /active/i });
+  }
+
+  get submitButton(): Locator {
+    return this.page.getByRole('button', { name: /save|submit|create/i });
+  }
+
+  get cancelButton(): Locator {
+    return this.page.getByRole('button', { name: /cancel/i });
+  }
+
+  // --- MUI-specific validation error locators ---
+
+  getFieldError(fieldLabel: string): Locator {
+    return this.page.locator(`[aria-label="${fieldLabel}"]`)
+      .locator('xpath=ancestor::div[contains(@class, "MuiFormControl")]')
+      .locator('.MuiFormHelperText-root.Mui-error');
+  }
+
+  get nameError(): Locator {
+    return this.page.getByText(/name.*required|enter.*name/i);
+  }
+
+  get emailError(): Locator {
+    return this.page.getByText(/email.*required|valid.*email/i);
+  }
+
+  // --- Actions ---
+
+  async fillName(name: string) {
+    await this.nameInput.clear();
+    await this.nameInput.fill(name);
+  }
+
+  async fillEmail(email: string) {
+    await this.emailInput.clear();
+    await this.emailInput.fill(email);
+  }
+
+  async selectRole(role: string) {
+    await this.roleSelect.click();
+    await this.page.getByRole('option', { name: role }).click();
+  }
+
+  async toggleActive() {
+    await this.activeCheckbox.click();
+  }
+
+  async clickSubmit() {
+    await this.submitButton.click();
+  }
+
+  async clickCancel() {
+    await this.cancelButton.click();
+  }
+
+  async fillAndSubmit(data: { name: string; email: string; role?: string }) {
+    await this.fillName(data.name);
+    await this.fillEmail(data.email);
+    if (data.role) await this.selectRole(data.role);
+    await this.clickSubmit();
+  }
+}
+```
+
+## Table / List Page — Angular Material
+
+POM for a data table using `mat-table` and `mat-paginator`:
+
+```typescript
+import { Page, Locator } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class UserListPage extends BasePage {
+  readonly path = '/users';
+
+  constructor(page: Page) {
+    super(page);
+  }
+
+  async goto() {
+    await super.goto(this.path);
+    await this.waitForLoad();
+  }
+
+  // --- Locators ---
+
+  get pageTitle(): Locator {
+    return this.page.getByRole('heading', { name: /users/i });
+  }
+
+  get addButton(): Locator {
+    return this.page.getByRole('button', { name: /add|create|new/i });
+  }
+
+  get searchInput(): Locator {
+    return this.page.getByPlaceholder(/search|filter/i);
+  }
+
+  get table(): Locator {
+    return this.page.locator('mat-table, table');
+  }
+
+  get tableRows(): Locator {
+    return this.page.locator('mat-row, tbody tr');
+  }
+
+  get emptyState(): Locator {
+    return this.page.getByText(/no users|no data|no results|empty/i);
+  }
+
+  // --- Column header locators for sorting ---
+
+  columnHeader(name: string): Locator {
+    return this.page.getByRole('columnheader', { name: new RegExp(name, 'i') });
+  }
+
+  get sortIndicator(): Locator {
+    return this.page.locator('.mat-sort-header-arrow, [aria-sort]');
+  }
+
+  // --- Pagination ---
+
+  get paginator(): Locator {
+    return this.page.locator('mat-paginator');
+  }
+
+  get nextPageButton(): Locator {
+    return this.page.getByRole('button', { name: /next page/i });
+  }
+
+  get previousPageButton(): Locator {
+    return this.page.getByRole('button', { name: /previous page/i });
+  }
+
+  get pageSizeSelect(): Locator {
+    return this.paginator.locator('mat-select');
+  }
+
+  get paginatorLabel(): Locator {
+    return this.paginator.locator('.mat-mdc-paginator-range-label');
+  }
+
+  // --- Row actions ---
+
+  rowByIndex(index: number): Locator {
+    return this.tableRows.nth(index);
+  }
+
+  editButtonInRow(index: number): Locator {
+    return this.rowByIndex(index).getByRole('button', { name: /edit/i });
+  }
+
+  deleteButtonInRow(index: number): Locator {
+    return this.rowByIndex(index).getByRole('button', { name: /delete/i });
+  }
+
+  cellInRow(rowIndex: number, columnName: string): Locator {
+    return this.rowByIndex(rowIndex).locator(`mat-cell.mat-column-${columnName}, td.mat-column-${columnName}`);
+  }
+
+  // --- Actions ---
+
+  async clickAdd() {
+    await this.addButton.click();
+  }
+
+  async search(query: string) {
+    await this.searchInput.clear();
+    await this.searchInput.fill(query);
+  }
+
+  async clearSearch() {
+    await this.searchInput.clear();
+  }
+
+  async sortByColumn(columnName: string) {
+    await this.columnHeader(columnName).click();
+  }
+
+  async goToNextPage() {
+    await this.nextPageButton.click();
+  }
+
+  async goToPreviousPage() {
+    await this.previousPageButton.click();
+  }
+
+  async changePageSize(size: string) {
+    await this.pageSizeSelect.click();
+    await this.page.getByRole('option', { name: size }).click();
+  }
+
+  async getRowCount(): Promise<number> {
+    return this.tableRows.count();
+  }
+
+  async clickEditRow(index: number) {
+    await this.editButtonInRow(index).click();
+  }
+
+  async clickDeleteRow(index: number) {
+    await this.deleteButtonInRow(index).click();
+  }
+
+  async confirmDelete() {
+    await this.confirmDialogAction();
+  }
+
+  async cancelDelete() {
+    await this.cancelDialogAction();
+  }
+}
+```
+
+## Table / List Page — React MUI DataGrid
+
+```typescript
+import { Page, Locator } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class UserListPage extends BasePage {
+  constructor(page: Page) {
+    super(page);
+  }
+
+  async goto() {
+    await super.goto('/users');
+    await this.waitForLoad();
+  }
+
+  // --- Locators ---
+
+  get addButton(): Locator {
+    return this.page.getByRole('button', { name: /add|create|new/i });
+  }
+
+  get searchInput(): Locator {
+    return this.page.getByPlaceholder(/search|filter/i);
+  }
+
+  get dataGrid(): Locator {
+    return this.page.locator('.MuiDataGrid-root');
+  }
+
+  get rows(): Locator {
+    return this.page.locator('.MuiDataGrid-row');
+  }
+
+  get emptyState(): Locator {
+    return this.page.getByText(/no rows|no data|no results/i);
+  }
+
+  // --- Column headers ---
+
+  columnHeader(name: string): Locator {
+    return this.page.getByRole('columnheader', { name: new RegExp(name, 'i') });
+  }
+
+  // --- Pagination ---
+
+  get nextPageButton(): Locator {
+    return this.page.getByRole('button', { name: /next page/i });
+  }
+
+  get previousPageButton(): Locator {
+    return this.page.getByRole('button', { name: /previous page/i });
+  }
+
+  get rowCountLabel(): Locator {
+    return this.page.locator('.MuiTablePagination-displayedRows');
+  }
+
+  // --- Row actions ---
+
+  rowByIndex(index: number): Locator {
+    return this.rows.nth(index);
+  }
+
+  editButtonInRow(index: number): Locator {
+    return this.rowByIndex(index).getByRole('button', { name: /edit/i });
+  }
+
+  deleteButtonInRow(index: number): Locator {
+    return this.rowByIndex(index).getByRole('button', { name: /delete/i });
+  }
+
+  // --- Actions ---
+
+  async clickAdd() {
+    await this.addButton.click();
+  }
+
+  async search(query: string) {
+    await this.searchInput.clear();
+    await this.searchInput.fill(query);
+  }
+
+  async sortByColumn(columnName: string) {
+    await this.columnHeader(columnName).click();
+  }
+
+  async goToNextPage() {
+    await this.nextPageButton.click();
+  }
+
+  async getRowCount(): Promise<number> {
+    return this.rows.count();
+  }
+
+  async clickEditRow(index: number) {
+    await this.editButtonInRow(index).click();
+  }
+
+  async clickDeleteRow(index: number) {
+    await this.deleteButtonInRow(index).click();
+  }
+}
+```
+
+## Modal / Dialog Page Object
+
+Reusable POM for modals that appear across pages:
+
+```typescript
+import { Page, Locator } from '@playwright/test';
+
+export class ConfirmDialogComponent {
+  constructor(private page: Page) {}
+
+  get dialog(): Locator {
+    return this.page.getByRole('dialog');
+  }
+
+  get title(): Locator {
+    return this.dialog.getByRole('heading');
+  }
+
+  get message(): Locator {
+    return this.dialog.locator('.dialog-content, .mat-mdc-dialog-content, .MuiDialogContent-root');
+  }
+
+  get confirmButton(): Locator {
+    return this.dialog.getByRole('button', { name: /confirm|yes|ok|delete|proceed/i });
+  }
+
+  get cancelButton(): Locator {
+    return this.dialog.getByRole('button', { name: /cancel|no|close/i });
+  }
+
+  get closeIconButton(): Locator {
+    return this.dialog.getByRole('button', { name: /close/i }).first();
+  }
+
+  async confirm() {
+    await this.confirmButton.click();
+  }
+
+  async cancel() {
+    await this.cancelButton.click();
+  }
+
+  async closeWithIcon() {
+    await this.closeIconButton.click();
+  }
+
+  async closeWithEscape() {
+    await this.page.keyboard.press('Escape');
+  }
+
+  async closeWithOverlayClick() {
+    const backdrop = this.page.locator('.cdk-overlay-backdrop, .MuiBackdrop-root');
+    await backdrop.click({ force: true, position: { x: 0, y: 0 } });
+  }
+}
+```
+
+## Navigation / Sidebar Page Object
+
+```typescript
+import { Page, Locator } from '@playwright/test';
+
+export class NavigationComponent {
+  constructor(private page: Page) {}
+
+  get sidebar(): Locator {
+    return this.page.getByRole('navigation');
+  }
+
+  get hamburgerMenu(): Locator {
+    return this.page.getByRole('button', { name: /menu|toggle/i });
+  }
+
+  navLink(name: string): Locator {
+    return this.sidebar.getByRole('link', { name: new RegExp(name, 'i') });
+  }
+
+  get activeNavItem(): Locator {
+    return this.sidebar.locator('[aria-current="page"], .active, .mat-mdc-list-item-active');
+  }
+
+  get userMenu(): Locator {
+    return this.page.getByRole('button', { name: /profile|account|avatar/i });
+  }
+
+  get logoutButton(): Locator {
+    return this.page.getByRole('menuitem', { name: /logout|sign out/i });
+  }
+
+  async navigateTo(linkName: string) {
+    await this.navLink(linkName).click();
+  }
+
+  async toggleSidebar() {
+    await this.hamburgerMenu.click();
+  }
+
+  async openUserMenu() {
+    await this.userMenu.click();
+  }
+
+  async logout() {
+    await this.openUserMenu();
+    await this.logoutButton.click();
+  }
+}
+```
+
+## Auth Setup Fixture
+
+Pattern for authenticating before tests that need auth state:
+
+```typescript
+import { test as setup, expect } from '@playwright/test';
+
+const authFile = 'e2e/.auth/user.json';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('admin@example.com');
+  await page.getByLabel('Password').fill('SecureP@ss123');
+  await page.getByRole('button', { name: /login|sign in/i }).click();
+
+  await expect(page).toHaveURL(/\/dashboard/);
+
+  await page.context().storageState({ path: authFile });
+});
+```
+
+Usage in `playwright.config.ts`:
+
+```typescript
+projects: [
+  { name: 'setup', testMatch: /.*\.setup\.ts/ },
+  {
+    name: 'chromium',
+    use: {
+      ...devices['Desktop Chrome'],
+      storageState: 'e2e/.auth/user.json',
+    },
+    dependencies: ['setup'],
+  },
+]
+```
+
+## Test Data Fixture
+
+```typescript
+export const testUsers = {
+  valid: {
+    name: 'Jane Smith',
+    email: 'jane.smith@example.com',
+    password: 'SecureP@ss123',
+    phone: '+1-555-123-4567',
+    role: 'User',
+  },
+  admin: {
+    name: 'Alex Johnson',
+    email: 'alex.johnson@example.com',
+    password: 'AdminP@ss456',
+    phone: '+1-555-987-6543',
+    role: 'Admin',
+  },
+  invalidEmail: {
+    name: 'Test User',
+    email: 'not-an-email',
+    password: 'SecureP@ss123',
+  },
+  shortPassword: {
+    name: 'Test User',
+    email: 'test@example.com',
+    password: 'ab',
+  },
+  emptyFields: {
+    name: '',
+    email: '',
+    password: '',
+  },
+};
+
+export const testProducts = {
+  valid: {
+    name: 'Wireless Bluetooth Headphones',
+    description: 'Premium noise-cancelling headphones with 30-hour battery',
+    price: '149.99',
+    category: 'Electronics',
+    sku: 'WBH-2025-001',
+  },
+};
+```