@assertrx/dino 1.0.0

package/skills/playwright-core/angular.md

@@ -0,0 +1,1086 @@
+# Testing Angular Apps with Playwright
+
+> **When to use**: Testing Angular applications -- reactive forms, Angular Material components, Angular Router navigation, lazy-loaded modules, signals, observables, and Zone.js-driven change detection. This guide covers E2E testing patterns specific to Angular behavior.
+> **Prerequisites**: [core/configuration.md](configuration.md), [core/locators.md](locators.md)
+
+## Quick Reference
+
+```bash
+# Install Playwright in an Angular project
+npm init playwright@latest
+
+# Run tests with Angular dev server managed by Playwright
+npx playwright test
+
+# Run against a production build (recommended for CI)
+npx playwright test --project=chromium
+
+# Debug a single test
+npx playwright test tests/home.spec.ts --headed --debug
+
+# Generate tests with codegen
+npx playwright codegen http://localhost:4200
+```
+
+## Setup
+
+### Playwright Config for Angular
+
+**TypeScript**
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  testMatch: '**/*.spec.ts',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? '50%' : undefined,
+
+  use: {
+    baseURL: 'http://localhost:4200',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'mobile',
+      use: { ...devices['iPhone 14'] },
+    },
+  ],
+
+  webServer: {
+    command: process.env.CI
+      ? 'npx ng build && npx http-server dist/your-app/browser -p 4200 -s'
+      : 'npx ng serve',
+    url: 'http://localhost:4200',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000, // Angular builds can be slow
+  },
+});
+```
+
+**JavaScript**
+```javascript
+// playwright.config.js
+const { defineConfig, devices } = require('@playwright/test');
+
+module.exports = defineConfig({
+  testDir: './e2e',
+  testMatch: '**/*.spec.js',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? '50%' : undefined,
+
+  use: {
+    baseURL: 'http://localhost:4200',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'mobile',
+      use: { ...devices['iPhone 14'] },
+    },
+  ],
+
+  webServer: {
+    command: process.env.CI
+      ? 'npx ng build && npx http-server dist/your-app/browser -p 4200 -s'
+      : 'npx ng serve',
+    url: 'http://localhost:4200',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+### Angular CLI Integration
+
+Angular projects that previously used Protractor can adopt Playwright as a direct replacement. The test directory conventionally lives at `e2e/` in Angular projects.
+
+```
+your-angular-app/
+  src/
+  e2e/
+    tests/
+      home.spec.ts
+      auth.spec.ts
+      products.spec.ts
+    fixtures/
+      auth.fixture.ts
+  playwright.config.ts
+  angular.json
+  package.json
+```
+
+Add scripts to `package.json`:
+
+```json
+{
+  "scripts": {
+    "e2e": "playwright test",
+    "e2e:headed": "playwright test --headed",
+    "e2e:debug": "playwright test --debug",
+    "e2e:report": "playwright show-report"
+  }
+}
+```
+
+### Environment Configuration
+
+Angular uses `environment.ts` and `environment.prod.ts` for build-time configuration. For test-specific settings, use environment variables passed through the Playwright config.
+
+**TypeScript**
+```typescript
+// playwright.config.ts (excerpt)
+webServer: {
+  command: process.env.CI
+    ? 'npx ng build --configuration=production && npx http-server dist/your-app/browser -p 4200 -s'
+    : 'npx ng serve --configuration=development',
+  url: 'http://localhost:4200',
+  reuseExistingServer: !process.env.CI,
+  timeout: 120_000,
+  env: {
+    NG_APP_API_URL: 'http://localhost:4200/api',
+  },
+},
+```
+
+## Patterns
+
+### Angular-Specific Locator Strategies
+
+**Use when**: Targeting elements in Angular templates. Angular generates specific attribute patterns (`_ngcontent-*`, `_nghost-*`, `ng-reflect-*`) that you must avoid in locators. Always use semantic locators.
+**Avoid when**: You are tempted to use `[_ngcontent-abc123]` or `[ng-reflect-model]` attributes -- they are internal and change on every build.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Angular locator strategies', () => {
+  test('prefer role-based locators over Angular internals', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // GOOD: Role-based locators work with Angular Material and native HTML
+    await page.getByRole('button', { name: 'Create project' }).click();
+    await expect(page.getByRole('heading', { name: 'New Project' })).toBeVisible();
+
+    // GOOD: Label-based for form fields
+    await page.getByLabel('Project name').fill('My Project');
+
+    // GOOD: Text-based for non-interactive content
+    await expect(page.getByText('3 projects total')).toBeVisible();
+
+    // BAD (never do this):
+    // page.locator('[_ngcontent-abc]')  -- changes every build
+    // page.locator('[ng-reflect-model]') -- debug attribute, stripped in prod
+    // page.locator('app-dashboard .mat-card') -- component selector + internal class
+  });
+
+  test('use test IDs for complex Angular components', async ({ page }) => {
+    await page.goto('/analytics');
+
+    // Angular components with no semantic role need test IDs
+    const chart = page.getByTestId('revenue-chart');
+    await expect(chart).toBeVisible();
+
+    // Configure the testIdAttribute if your team uses a different attribute
+    // In playwright.config.ts: use: { testIdAttribute: 'data-cy' }
+  });
+
+  test('scope locators within Angular component boundaries', async ({ page }) => {
+    await page.goto('/users');
+
+    // Scope within a table to find specific rows
+    const userTable = page.getByRole('table', { name: 'Users' });
+    const adminRow = userTable.getByRole('row').filter({
+      has: page.getByRole('cell', { name: 'Admin' }),
+    });
+    await adminRow.getByRole('button', { name: 'Edit' }).click();
+
+    await expect(page.getByRole('dialog', { name: 'Edit User' })).toBeVisible();
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Angular locator strategies', () => {
+  test('prefer role-based locators over Angular internals', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    await page.getByRole('button', { name: 'Create project' }).click();
+    await expect(page.getByRole('heading', { name: 'New Project' })).toBeVisible();
+
+    await page.getByLabel('Project name').fill('My Project');
+    await expect(page.getByText('3 projects total')).toBeVisible();
+  });
+
+  test('use test IDs for complex Angular components', async ({ page }) => {
+    await page.goto('/analytics');
+
+    const chart = page.getByTestId('revenue-chart');
+    await expect(chart).toBeVisible();
+  });
+
+  test('scope locators within Angular component boundaries', async ({ page }) => {
+    await page.goto('/users');
+
+    const userTable = page.getByRole('table', { name: 'Users' });
+    const adminRow = userTable.getByRole('row').filter({
+      has: page.getByRole('cell', { name: 'Admin' }),
+    });
+    await adminRow.getByRole('button', { name: 'Edit' }).click();
+
+    await expect(page.getByRole('dialog', { name: 'Edit User' })).toBeVisible();
+  });
+});
+```
+
+### Testing Reactive Forms
+
+**Use when**: Testing Angular reactive forms (`FormGroup`, `FormControl`, `FormArray`). Playwright interacts with the rendered DOM, so reactive forms are transparent -- test the user experience.
+**Avoid when**: Testing form validation logic in isolation -- use Angular TestBed unit tests for that.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('reactive forms', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/register');
+  });
+
+  test('shows validation errors for invalid inputs', async ({ page }) => {
+    // Touch and blur each field to trigger Angular's touched + dirty validators
+    const emailInput = page.getByLabel('Email');
+    await emailInput.click();
+    await emailInput.blur();
+
+    await expect(page.getByText('Email is required')).toBeVisible();
+
+    await emailInput.fill('not-an-email');
+    await emailInput.blur();
+
+    await expect(page.getByText('Invalid email format')).toBeVisible();
+  });
+
+  test('cross-field validation (password match)', async ({ page }) => {
+    await page.getByLabel('Password', { exact: true }).fill('Str0ng!Pass');
+    await page.getByLabel('Confirm password').fill('different-password');
+    await page.getByLabel('Confirm password').blur();
+
+    await expect(page.getByText('Passwords do not match')).toBeVisible();
+
+    // Fix the mismatch
+    await page.getByLabel('Confirm password').fill('Str0ng!Pass');
+    await page.getByLabel('Confirm password').blur();
+
+    await expect(page.getByText('Passwords do not match')).toBeHidden();
+  });
+
+  test('dynamic FormArray -- add and remove items', async ({ page }) => {
+    await page.goto('/profile/edit');
+
+    // Add a phone number (FormArray push)
+    await page.getByRole('button', { name: 'Add phone number' }).click();
+
+    const phoneInputs = page.getByLabel(/Phone number/);
+    await expect(phoneInputs).toHaveCount(2); // default + new one
+
+    await phoneInputs.nth(1).fill('+1-555-0199');
+
+    // Remove the first phone number
+    await page.getByRole('button', { name: 'Remove phone 1' }).click();
+    await expect(phoneInputs).toHaveCount(1);
+    await expect(phoneInputs.first()).toHaveValue('+1-555-0199');
+  });
+
+  test('submit button disabled when form is invalid', async ({ page }) => {
+    const submitButton = page.getByRole('button', { name: 'Create account' });
+
+    // Form starts invalid -- button should be disabled
+    await expect(submitButton).toBeDisabled();
+
+    // Fill all required fields
+    await page.getByLabel('Full name').fill('Jane Doe');
+    await page.getByLabel('Email').fill('jane@example.com');
+    await page.getByLabel('Password', { exact: true }).fill('Str0ng!Pass');
+    await page.getByLabel('Confirm password').fill('Str0ng!Pass');
+    await page.getByLabel('I agree to the terms').check();
+
+    // Now the form is valid -- button should be enabled
+    await expect(submitButton).toBeEnabled();
+  });
+
+  test('async validator shows loading state', async ({ page }) => {
+    // Slow down the username availability check
+    await page.route('**/api/check-username*', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ available: true }),
+      });
+    });
+
+    await page.getByLabel('Username').fill('janedoe');
+    await page.getByLabel('Username').blur();
+
+    // Async validator fires -- shows a loading indicator
+    await expect(page.getByTestId('username-checking')).toBeVisible();
+
+    // After the check completes
+    await expect(page.getByTestId('username-checking')).toBeHidden();
+    await expect(page.getByText('Username is available')).toBeVisible();
+  });
+
+  test('form submission posts correct data', async ({ page }) => {
+    let submittedData: Record<string, unknown> = {};
+    await page.route('**/api/register', async (route) => {
+      submittedData = route.request().postDataJSON();
+      await route.fulfill({
+        status: 201,
+        contentType: 'application/json',
+        body: JSON.stringify({ id: 1 }),
+      });
+    });
+
+    await page.getByLabel('Full name').fill('Jane Doe');
+    await page.getByLabel('Email').fill('jane@example.com');
+    await page.getByLabel('Password', { exact: true }).fill('Str0ng!Pass');
+    await page.getByLabel('Confirm password').fill('Str0ng!Pass');
+    await page.getByLabel('I agree to the terms').check();
+    await page.getByRole('button', { name: 'Create account' }).click();
+
+    expect(submittedData).toMatchObject({
+      name: 'Jane Doe',
+      email: 'jane@example.com',
+    });
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('reactive forms', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/register');
+  });
+
+  test('shows validation errors for invalid inputs', async ({ page }) => {
+    const emailInput = page.getByLabel('Email');
+    await emailInput.click();
+    await emailInput.blur();
+
+    await expect(page.getByText('Email is required')).toBeVisible();
+
+    await emailInput.fill('not-an-email');
+    await emailInput.blur();
+
+    await expect(page.getByText('Invalid email format')).toBeVisible();
+  });
+
+  test('cross-field validation (password match)', async ({ page }) => {
+    await page.getByLabel('Password', { exact: true }).fill('Str0ng!Pass');
+    await page.getByLabel('Confirm password').fill('different-password');
+    await page.getByLabel('Confirm password').blur();
+
+    await expect(page.getByText('Passwords do not match')).toBeVisible();
+
+    await page.getByLabel('Confirm password').fill('Str0ng!Pass');
+    await page.getByLabel('Confirm password').blur();
+
+    await expect(page.getByText('Passwords do not match')).toBeHidden();
+  });
+
+  test('submit button disabled when form is invalid', async ({ page }) => {
+    const submitButton = page.getByRole('button', { name: 'Create account' });
+
+    await expect(submitButton).toBeDisabled();
+
+    await page.getByLabel('Full name').fill('Jane Doe');
+    await page.getByLabel('Email').fill('jane@example.com');
+    await page.getByLabel('Password', { exact: true }).fill('Str0ng!Pass');
+    await page.getByLabel('Confirm password').fill('Str0ng!Pass');
+    await page.getByLabel('I agree to the terms').check();
+
+    await expect(submitButton).toBeEnabled();
+  });
+});
+```
+
+### Testing Angular Material Components
+
+**Use when**: Testing apps using Angular Material (mat-button, mat-input, mat-select, mat-dialog, mat-table, etc.). Angular Material components use proper ARIA attributes, making them accessible to role-based locators.
+**Avoid when**: Using CSS class selectors like `.mat-mdc-button` or `.mat-option` -- these change between Material versions.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Angular Material components', () => {
+  test('mat-select dropdown', async ({ page }) => {
+    await page.goto('/settings');
+
+    // Angular Material select has role="combobox"
+    await page.getByRole('combobox', { name: 'Theme' }).click();
+
+    // Options appear in a CDK overlay (similar to a portal)
+    await page.getByRole('option', { name: 'Dark' }).click();
+
+    // Verify the selection
+    await expect(page.getByRole('combobox', { name: 'Theme' })).toContainText('Dark');
+  });
+
+  test('mat-autocomplete with type-ahead', async ({ page }) => {
+    await page.goto('/users/new');
+
+    const roleInput = page.getByRole('combobox', { name: 'Role' });
+    await roleInput.fill('adm');
+
+    // Autocomplete suggestions appear in a CDK overlay
+    await expect(page.getByRole('option', { name: 'Admin' })).toBeVisible();
+    await expect(page.getByRole('option', { name: 'Administrator' })).toBeVisible();
+
+    await page.getByRole('option', { name: 'Admin' }).click();
+    await expect(roleInput).toHaveValue('Admin');
+  });
+
+  test('mat-dialog opens and closes', async ({ page }) => {
+    await page.goto('/projects');
+
+    await page.getByRole('button', { name: 'Delete project' }).first().click();
+
+    // MatDialog renders as a CDK overlay with role="dialog"
+    const dialog = page.getByRole('dialog');
+    await expect(dialog).toBeVisible();
+    await expect(dialog.getByText('Are you sure?')).toBeVisible();
+
+    // Cancel
+    await dialog.getByRole('button', { name: 'Cancel' }).click();
+    await expect(dialog).toBeHidden();
+  });
+
+  test('mat-table sorting', async ({ page }) => {
+    await page.goto('/users');
+
+    // Click the column header to sort
+    await page.getByRole('columnheader', { name: 'Name' }).click();
+
+    // Verify sort indicator
+    const header = page.getByRole('columnheader', { name: 'Name' });
+    await expect(header).toHaveAttribute('aria-sort', 'ascending');
+
+    // Verify rows are sorted
+    const names = await page.getByRole('cell').filter({
+      has: page.locator('[data-column="name"]'),
+    }).allTextContents();
+    const sortedNames = [...names].sort();
+    expect(names).toEqual(sortedNames);
+
+    // Click again for descending
+    await page.getByRole('columnheader', { name: 'Name' }).click();
+    await expect(header).toHaveAttribute('aria-sort', 'descending');
+  });
+
+  test('mat-paginator controls table pagination', async ({ page }) => {
+    await page.goto('/users');
+
+    await expect(page.getByText('1 - 10 of 50')).toBeVisible();
+
+    // Navigate to next page
+    await page.getByRole('button', { name: 'Next page' }).click();
+    await expect(page.getByText('11 - 20 of 50')).toBeVisible();
+
+    // Change page size
+    await page.getByRole('combobox', { name: 'Items per page' }).click();
+    await page.getByRole('option', { name: '25' }).click();
+    await expect(page.getByText('1 - 25 of 50')).toBeVisible();
+  });
+
+  test('mat-snack-bar notification appears and dismisses', async ({ page }) => {
+    await page.goto('/settings');
+
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    // Snackbar appears at the bottom of the screen
+    await expect(page.getByText('Settings saved successfully')).toBeVisible();
+
+    // Dismiss via action button
+    await page.getByRole('button', { name: 'Dismiss' }).click();
+    await expect(page.getByText('Settings saved successfully')).toBeHidden();
+  });
+
+  test('mat-stepper wizard flow', async ({ page }) => {
+    await page.goto('/onboarding');
+
+    // Step 1: Personal info
+    await expect(page.getByText('Step 1 of 3')).toBeVisible();
+    await page.getByLabel('Full name').fill('Jane Doe');
+    await page.getByRole('button', { name: 'Next' }).click();
+
+    // Step 2: Company info
+    await expect(page.getByText('Step 2 of 3')).toBeVisible();
+    await page.getByLabel('Company').fill('Acme Corp');
+    await page.getByRole('button', { name: 'Next' }).click();
+
+    // Step 3: Review
+    await expect(page.getByText('Step 3 of 3')).toBeVisible();
+    await expect(page.getByText('Jane Doe')).toBeVisible();
+    await expect(page.getByText('Acme Corp')).toBeVisible();
+
+    // Go back to step 1
+    await page.getByRole('button', { name: 'Back' }).click();
+    await page.getByRole('button', { name: 'Back' }).click();
+    await expect(page.getByText('Step 1 of 3')).toBeVisible();
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Angular Material components', () => {
+  test('mat-select dropdown', async ({ page }) => {
+    await page.goto('/settings');
+
+    await page.getByRole('combobox', { name: 'Theme' }).click();
+    await page.getByRole('option', { name: 'Dark' }).click();
+
+    await expect(page.getByRole('combobox', { name: 'Theme' })).toContainText('Dark');
+  });
+
+  test('mat-dialog opens and closes', async ({ page }) => {
+    await page.goto('/projects');
+
+    await page.getByRole('button', { name: 'Delete project' }).first().click();
+
+    const dialog = page.getByRole('dialog');
+    await expect(dialog).toBeVisible();
+    await expect(dialog.getByText('Are you sure?')).toBeVisible();
+
+    await dialog.getByRole('button', { name: 'Cancel' }).click();
+    await expect(dialog).toBeHidden();
+  });
+
+  test('mat-table sorting', async ({ page }) => {
+    await page.goto('/users');
+
+    await page.getByRole('columnheader', { name: 'Name' }).click();
+
+    const header = page.getByRole('columnheader', { name: 'Name' });
+    await expect(header).toHaveAttribute('aria-sort', 'ascending');
+  });
+
+  test('mat-snack-bar notification appears and dismisses', async ({ page }) => {
+    await page.goto('/settings');
+
+    await page.getByRole('button', { name: 'Save' }).click();
+    await expect(page.getByText('Settings saved successfully')).toBeVisible();
+
+    await page.getByRole('button', { name: 'Dismiss' }).click();
+    await expect(page.getByText('Settings saved successfully')).toBeHidden();
+  });
+});
+```
+
+### Testing Angular Router Navigation
+
+**Use when**: Testing Angular Router navigation, lazy-loaded routes, route guards, and URL parameter handling.
+**Avoid when**: Testing router configuration in isolation -- use Angular TestBed for that.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Angular Router navigation', () => {
+  test('lazy-loaded module loads on navigation', async ({ page }) => {
+    await page.goto('/');
+
+    // Navigate to a lazy-loaded route
+    await page.getByRole('link', { name: 'Admin' }).click();
+    await page.waitForURL('/admin');
+
+    // The lazy module loads and renders its component
+    await expect(page.getByRole('heading', { name: 'Admin Dashboard' })).toBeVisible();
+  });
+
+  test('route guard redirects unauthorized users', async ({ page }) => {
+    // Visit a route protected by AuthGuard (canActivate)
+    await page.goto('/admin/users');
+
+    // Guard should redirect to login
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: 'Sign in' })).toBeVisible();
+  });
+
+  test('route resolver prefetches data before navigation', async ({ page }) => {
+    // Intercept the API call that the resolver makes
+    const resolverPromise = page.waitForResponse('**/api/products/*');
+
+    await page.goto('/products/42');
+
+    // The resolver fetches data before the component renders
+    await resolverPromise;
+
+    // Component renders with pre-fetched data (no loading spinner)
+    await expect(page.getByRole('heading', { level: 1 })).toContainText('Product');
+  });
+
+  test('nested router-outlet renders child components', async ({ page }) => {
+    await page.goto('/settings/profile');
+
+    // Parent layout (SettingsComponent with its own router-outlet)
+    await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
+    await expect(page.getByRole('navigation', { name: 'Settings' })).toBeVisible();
+
+    // Child route (ProfileComponent rendered inside nested router-outlet)
+    await expect(page.getByRole('heading', { name: 'Profile', level: 2 })).toBeVisible();
+
+    // Navigate to sibling child route
+    await page.getByRole('link', { name: 'Security' }).click();
+    await page.waitForURL('/settings/security');
+
+    // Parent persists, child changes
+    await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Security', level: 2 })).toBeVisible();
+  });
+
+  test('route parameters update component state', async ({ page }) => {
+    await page.goto('/users/1');
+    await expect(page.getByRole('heading')).toContainText('User #1');
+
+    // Navigate to a different user via the URL
+    await page.goto('/users/2');
+    await expect(page.getByRole('heading')).toContainText('User #2');
+  });
+
+  test('query parameters drive filter behavior', async ({ page }) => {
+    await page.goto('/products?category=electronics&page=2');
+
+    await expect(page.getByRole('heading', { name: 'Electronics' })).toBeVisible();
+    await expect(page.getByText('Page 2')).toBeVisible();
+  });
+
+  test('browser back navigates through Angular history', async ({ page }) => {
+    await page.goto('/');
+    await page.getByRole('link', { name: 'Products' }).click();
+    await page.waitForURL('/products');
+    await page.getByRole('link', { name: 'About' }).click();
+    await page.waitForURL('/about');
+
+    await page.goBack();
+    await expect(page).toHaveURL(/\/products/);
+
+    await page.goBack();
+    await expect(page).toHaveURL(/\/$/);
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Angular Router navigation', () => {
+  test('lazy-loaded module loads on navigation', async ({ page }) => {
+    await page.goto('/');
+
+    await page.getByRole('link', { name: 'Admin' }).click();
+    await page.waitForURL('/admin');
+
+    await expect(page.getByRole('heading', { name: 'Admin Dashboard' })).toBeVisible();
+  });
+
+  test('route guard redirects unauthorized users', async ({ page }) => {
+    await page.goto('/admin/users');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: 'Sign in' })).toBeVisible();
+  });
+
+  test('nested router-outlet renders child components', async ({ page }) => {
+    await page.goto('/settings/profile');
+
+    await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Profile', level: 2 })).toBeVisible();
+
+    await page.getByRole('link', { name: 'Security' }).click();
+    await page.waitForURL('/settings/security');
+
+    await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Security', level: 2 })).toBeVisible();
+  });
+
+  test('browser back navigates through Angular history', async ({ page }) => {
+    await page.goto('/');
+    await page.getByRole('link', { name: 'Products' }).click();
+    await page.waitForURL('/products');
+    await page.getByRole('link', { name: 'About' }).click();
+    await page.waitForURL('/about');
+
+    await page.goBack();
+    await expect(page).toHaveURL(/\/products/);
+
+    await page.goBack();
+    await expect(page).toHaveURL(/\/$/);
+  });
+});
+```
+
+### Testing Lazy-Loaded Modules
+
+**Use when**: Verifying that Angular lazy-loaded feature modules load correctly when the user navigates to their routes. Lazy-loaded modules introduce network requests for JavaScript chunks.
+**Avoid when**: The module is eagerly loaded -- no separate chunk to load.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('lazy-loaded modules', () => {
+  test('lazy module loads without errors', async ({ page }) => {
+    const consoleErrors: string[] = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        consoleErrors.push(msg.text());
+      }
+    });
+
+    await page.goto('/');
+
+    // Navigate to a lazy-loaded route
+    const chunkRequest = page.waitForResponse((response) =>
+      response.url().includes('.js') && response.status() === 200
+    );
+    await page.getByRole('link', { name: 'Reports' }).click();
+    await chunkRequest;
+
+    await page.waitForURL('/reports');
+    await expect(page.getByRole('heading', { name: 'Reports' })).toBeVisible();
+
+    // No chunk loading errors
+    const chunkErrors = consoleErrors.filter(
+      (e) => e.includes('ChunkLoadError') || e.includes('Loading chunk')
+    );
+    expect(chunkErrors).toEqual([]);
+  });
+
+  test('preloaded lazy module navigates instantly', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // If preloadingStrategy is configured, the module may already be cached
+    // Navigate and verify it renders without visible delay
+    const startTime = Date.now();
+    await page.getByRole('link', { name: 'Reports' }).click();
+    await page.waitForURL('/reports');
+    await expect(page.getByRole('heading', { name: 'Reports' })).toBeVisible();
+    const loadTime = Date.now() - startTime;
+
+    // Preloaded modules should render quickly (not an exact assertion, but a sanity check)
+    expect(loadTime).toBeLessThan(3000);
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('lazy-loaded modules', () => {
+  test('lazy module loads without errors', async ({ page }) => {
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        consoleErrors.push(msg.text());
+      }
+    });
+
+    await page.goto('/');
+
+    await page.getByRole('link', { name: 'Reports' }).click();
+    await page.waitForURL('/reports');
+    await expect(page.getByRole('heading', { name: 'Reports' })).toBeVisible();
+
+    const chunkErrors = consoleErrors.filter(
+      (e) => e.includes('ChunkLoadError') || e.includes('Loading chunk')
+    );
+    expect(chunkErrors).toEqual([]);
+  });
+});
+```
+
+### Testing Signals and Observables Indirectly
+
+**Use when**: Verifying that Angular signals (`signal()`, `computed()`, `effect()`) and RxJS observables produce correct UI updates. Playwright cannot subscribe to observables or read signals directly -- test through the rendered output.
+**Avoid when**: Testing observable transformation logic in isolation -- use Jasmine/Jest with Angular TestBed for that.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('signals (tested through UI)', () => {
+  test('signal-based counter updates the DOM', async ({ page }) => {
+    await page.goto('/counter');
+
+    // The counter uses signal() internally
+    await expect(page.getByTestId('count')).toHaveText('0');
+
+    await page.getByRole('button', { name: 'Increment' }).click();
+    await expect(page.getByTestId('count')).toHaveText('1');
+
+    await page.getByRole('button', { name: 'Increment' }).click();
+    await page.getByRole('button', { name: 'Increment' }).click();
+    await expect(page.getByTestId('count')).toHaveText('3');
+
+    await page.getByRole('button', { name: 'Reset' }).click();
+    await expect(page.getByTestId('count')).toHaveText('0');
+  });
+
+  test('computed signal updates derived values', async ({ page }) => {
+    await page.goto('/cart');
+
+    // Cart total is a computed() signal derived from items
+    await expect(page.getByTestId('cart-total')).toHaveText('$0.00');
+
+    // Add item (updates the items signal, which updates the computed total)
+    await page.goto('/products');
+    await page.getByRole('listitem')
+      .filter({ hasText: '$29.99' })
+      .getByRole('button', { name: 'Add to cart' })
+      .click();
+
+    await page.getByRole('link', { name: 'Cart' }).click();
+    await expect(page.getByTestId('cart-total')).toHaveText('$29.99');
+  });
+});
+
+test.describe('observables (tested through UI)', () => {
+  test('real-time data stream updates the UI', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // The component subscribes to an observable that emits stock prices
+    const priceElement = page.getByTestId('stock-price');
+    await expect(priceElement).toBeVisible();
+
+    // Get the initial value
+    const initialPrice = await priceElement.textContent();
+
+    // Wait for the observable to emit a new value
+    // Use polling assertion instead of waitForTimeout
+    await expect(priceElement).not.toHaveText(initialPrice!, { timeout: 10_000 });
+  });
+
+  test('search with debounceTime observable', async ({ page }) => {
+    await page.goto('/search');
+
+    const apiCalls: string[] = [];
+    await page.route('**/api/search*', async (route) => {
+      apiCalls.push(route.request().url());
+      await route.continue();
+    });
+
+    // Type quickly -- the observable's debounceTime should batch
+    await page.getByRole('textbox', { name: 'Search' }).pressSequentially('angular', {
+      delay: 50,
+    });
+
+    await expect(page.getByRole('listitem')).toHaveCount(5);
+
+    // debounceTime should prevent a request per keystroke
+    expect(apiCalls.length).toBeLessThanOrEqual(2);
+  });
+
+  test('switchMap cancels previous requests on new input', async ({ page }) => {
+    await page.goto('/search');
+
+    // Type one query
+    await page.getByRole('textbox', { name: 'Search' }).fill('first query');
+
+    // Immediately type a different query before results come back
+    await page.getByRole('textbox', { name: 'Search' }).fill('second query');
+
+    // Results should match the second query, not the first
+    await expect(page.getByRole('listitem').first()).toContainText(/second query/i);
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('signals (tested through UI)', () => {
+  test('signal-based counter updates the DOM', async ({ page }) => {
+    await page.goto('/counter');
+
+    await expect(page.getByTestId('count')).toHaveText('0');
+
+    await page.getByRole('button', { name: 'Increment' }).click();
+    await expect(page.getByTestId('count')).toHaveText('1');
+
+    await page.getByRole('button', { name: 'Increment' }).click();
+    await page.getByRole('button', { name: 'Increment' }).click();
+    await expect(page.getByTestId('count')).toHaveText('3');
+
+    await page.getByRole('button', { name: 'Reset' }).click();
+    await expect(page.getByTestId('count')).toHaveText('0');
+  });
+});
+
+test.describe('observables (tested through UI)', () => {
+  test('search with debounceTime observable', async ({ page }) => {
+    await page.goto('/search');
+
+    const apiCalls = [];
+    await page.route('**/api/search*', async (route) => {
+      apiCalls.push(route.request().url());
+      await route.continue();
+    });
+
+    await page.getByRole('textbox', { name: 'Search' }).pressSequentially('angular', {
+      delay: 50,
+    });
+
+    await expect(page.getByRole('listitem')).toHaveCount(5);
+    expect(apiCalls.length).toBeLessThanOrEqual(2);
+  });
+});
+```
+
+## Framework-Specific Tips
+
+### Zone.js Considerations
+
+Angular uses Zone.js to detect async operations and trigger change detection. Playwright does not depend on Zone.js -- it interacts with the DOM directly. However, Zone.js can affect test behavior:
+
+1. **Change detection timing**: After user interactions (click, fill), Angular schedules change detection via Zone.js. Playwright's auto-waiting handles this -- `expect(locator).toHaveText('new value')` retries until the DOM updates.
+
+2. **Zoneless Angular (experimental)**: Angular 17+ supports zoneless change detection. Tests work identically with Playwright because Playwright waits for DOM changes, not Zone.js ticks.
+
+3. **Long-running async operations**: If your app has `setInterval` or long-running observables, Zone.js keeps Angular in a "not stable" state. This does not affect Playwright (unlike Protractor, which waited for Angular stability). Playwright simply interacts with whatever is on the screen.
+
+### Protractor to Playwright Migration Checklist
+
+| Protractor | Playwright Equivalent |
+|---|---|
+| `element(by.css('.btn'))` | `page.locator('.btn')` -- but prefer `page.getByRole('button', { name: '...' })` |
+| `element(by.id('login'))` | `page.getByTestId('login')` or `page.getByRole(...)` |
+| `element(by.buttonText('Submit'))` | `page.getByRole('button', { name: 'Submit' })` |
+| `element(by.model('user.name'))` | `page.getByLabel('Name')` -- Playwright cannot read ng-model |
+| `element(by.binding('user.name'))` | `page.getByText(expectedValue)` -- test the rendered output |
+| `element(by.repeater('item in items'))` | `page.getByRole('listitem')` or `page.getByTestId(...)` |
+| `browser.waitForAngular()` | Not needed -- Playwright auto-waits; remove all instances |
+| `browser.sleep(3000)` | `await expect(locator).toBeVisible()` -- never use arbitrary waits |
+| `browser.get('/path')` | `await page.goto('/path')` |
+| `protractor.ExpectedConditions` | `await expect(locator).toBeVisible/toBeHidden/toHaveText(...)` |
+
+### Angular Build Configurations
+
+| Scenario | Build Command | Notes |
+|---|---|---|
+| Local development | `npx ng serve` | Fast rebuild, source maps, no optimization |
+| CI (production build) | `npx ng build && npx http-server dist/your-app/browser -p 4200 -s` | Tests the real production bundle |
+| CI (SSR/Universal) | `npx ng build --ssr && node dist/your-app/server/server.mjs` | Tests server-side rendered Angular |
+| Staging environment | No `webServer` needed | Point `baseURL` to the staging URL |
+
+The `-s` flag on `http-server` enables SPA fallback (sends `index.html` for all routes), which is essential for Angular Router to work correctly.
+
+### CDK Overlay Container
+
+Angular Material and Angular CDK render overlays (dialogs, menus, selects, autocompletes) in a special container outside the component tree. Playwright sees these overlays in the document -- no special handling is needed. Use standard role-based locators:
+
+```typescript
+// CDK overlays render into <div class="cdk-overlay-container"> at the body level
+// Playwright sees them as regular DOM elements
+const dialog = page.getByRole('dialog');
+const menu = page.getByRole('menu');
+const listbox = page.getByRole('listbox');
+```
+
+### Testing with Angular SSR (Universal)
+
+If your Angular app uses server-side rendering:
+
+```typescript
+// playwright.config.ts (SSR-specific)
+webServer: {
+  command: process.env.CI
+    ? 'npx ng build --ssr && node dist/your-app/server/server.mjs'
+    : 'npx ng serve --ssr',
+  url: 'http://localhost:4200',
+  reuseExistingServer: !process.env.CI,
+  timeout: 180_000, // SSR builds are slower
+},
+```
+
+Test for hydration issues the same way as with other SSR frameworks:
+
+```typescript
+test('no hydration errors after SSR', async ({ page }) => {
+  const errors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error' && msg.text().includes('hydration')) {
+      errors.push(msg.text());
+    }
+  });
+
+  await page.goto('/');
+  await page.getByRole('button', { name: 'Get started' }).click();
+
+  expect(errors).toEqual([]);
+});
+```
+
+## Anti-Patterns
+
+| Don't Do This | Problem | Do This Instead |
+|---|---|---|
+| `page.locator('[_ngcontent-abc123]')` | Angular scoped style attributes are random and change every build | Use `getByRole`, `getByLabel`, `getByText`, `getByTestId` |
+| `page.locator('[ng-reflect-model="value"]')` | `ng-reflect-*` attributes only exist in dev mode; stripped in production | Test the rendered value: `expect(input).toHaveValue('value')` |
+| `page.locator('app-my-component')` | Angular component selectors are implementation details | Target the content the component renders using semantic locators |
+| `page.locator('.mat-mdc-button')` | Angular Material class names change between versions (MDC migration) | `page.getByRole('button', { name: 'Submit' })` |
+| `page.evaluate(() => (window as any).ng)` to access Angular internals | Depends on debug mode; not available in production builds | Test through the DOM; never access the Angular runtime |
+| `await page.waitForTimeout(500)` after clicking a button | Zone.js change detection timing varies; arbitrary waits are fragile | `await expect(locator).toHaveText('expected value')` auto-retries |
+| `browser.waitForAngular()` (Protractor pattern) | Does not exist in Playwright; not needed -- Playwright auto-waits | Remove entirely; use web-first assertions |
+| Test Angular services by injecting them via `page.evaluate` | Services are not accessible from the browser console in production | Test services indirectly through the UI they power; unit test with TestBed |
+| Use `ng serve` in CI | Development server is slower, includes debug code, may hide production-only bugs | Use `ng build && http-server` in CI |
+| Skip testing CDK overlay components (dialogs, selects, menus) | These are the most interactive parts of the app; bugs here are highly visible | Test overlays with role-based locators; they render in the regular DOM |
+
+## Related
+
+- [core/locators.md](locators.md) -- locator strategies for Angular Material and CDK components
+- [core/assertions-and-waiting.md](assertions-and-waiting.md) -- auto-waiting assertions that replace Protractor's waitForAngular
+- [core/forms-and-validation.md](forms-and-validation.md) -- form testing patterns for reactive and template-driven forms
+- [core/accessibility.md](accessibility.md) -- accessibility testing for Angular Material components
+- [core/authentication.md](authentication.md) -- authentication with Angular route guards
+- [migration/from-selenium.md](../migration/from-selenium.md) -- migration patterns applicable to Protractor (Protractor is built on Selenium)
+- [core/test-architecture.md](test-architecture.md) -- when to use E2E vs unit tests with Angular TestBed
+- [ci/ci-github-actions.md](../ci/ci-github-actions.md) -- CI setup with Angular build caching