Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

frameworks/angular.md

View on GitHub
# Angular Testing with Playwright

## Table of Contents

1. [Configuration](#configuration)
2. [Locator Strategies](#locator-strategies)
3. [Reactive Forms](#reactive-forms)
4. [Angular Material Components](#angular-material-components)
5. [Router Navigation](#router-navigation)
6. [Lazy-Loaded Modules](#lazy-loaded-modules)
7. [Signals and Observables](#signals-and-observables)
8. [Zone.js and Change Detection](#zonejs-and-change-detection)
9. [SSR Testing](#ssr-testing)
10. [Protractor Migration Reference](#protractor-migration-reference)
11. [Build Configurations](#build-configurations)
12. [CDK Overlay Container](#cdk-overlay-container)
13. [Anti-Patterns](#anti-patterns)
14. [Related](#related)

> **When to use**: Testing Angular applications with reactive forms, Angular Material components, Router navigation, lazy-loaded modules, signals, observables, and Zone.js change detection.
> **Prerequisites**: [core/configuration.md](../core/configuration.md), [core/locators.md](../core/locators.md)

## Configuration

### Playwright Config

```typescript
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/my-app/browser -p 4200 -s' : 'npx ng serve',
		url: 'http://localhost:4200',
		reuseExistingServer: !process.env.CI,
		timeout: 120_000
	}
});
```

### Project Structure

```text
my-angular-app/
  src/
  e2e/
    tests/
      dashboard.spec.ts
      login.spec.ts
    fixtures/
      auth.fixture.ts
  playwright.config.ts
  angular.json
```

### Package Scripts

```json
{
	"scripts": {
		"e2e": "playwright test",
		"e2e:headed": "playwright test --headed",
		"e2e:debug": "playwright test --debug",
		"e2e:report": "playwright show-report"
	}
}
```

## Locator Strategies

Angular generates internal attributes (`_ngcontent-*`, `_nghost-*`, `ng-reflect-*`) that change every build. Always use semantic locators.

```typescript
test('use semantic locators for Angular apps', async ({ page }) => {
	await page.goto('/projects');

	// Role-based locators work with Angular Material and native HTML
	await page.getByRole('button', { name: 'New project' }).click();
	await expect(page.getByRole('heading', { name: 'Create Project' })).toBeVisible();

	// Label-based for form fields
	await page.getByLabel('Project title').fill('Alpha');

	// Test IDs for complex components without semantic roles
	const chart = page.getByTestId('metrics-chart');
	await expect(chart).toBeVisible();

	// Scope locators within component boundaries
	const projectTable = page.getByRole('table', { name: 'Projects' });
	const activeRow = projectTable.getByRole('row').filter({
		has: page.getByRole('cell', { name: 'Active' })
	});
	await activeRow.getByRole('button', { name: 'Edit' }).click();
});
```

## Reactive Forms

Playwright interacts with the rendered DOM, so reactive forms (`FormGroup`, `FormControl`, `FormArray`) are transparent.

```typescript
test.describe('form validation', () => {
	test.beforeEach(async ({ page }) => {
		await page.goto('/signup');
	});

	test('displays validation errors on blur', async ({ page }) => {
		const emailField = page.getByLabel('Email');
		await emailField.click();
		await emailField.blur();
		await expect(page.getByText('Email is required')).toBeVisible();

		await emailField.fill('invalid');
		await emailField.blur();
		await expect(page.getByText('Invalid email format')).toBeVisible();
	});

	test('validates password confirmation', async ({ page }) => {
		await page.getByLabel('Password', { exact: true }).fill('Secret123!');
		await page.getByLabel('Confirm password').fill('Mismatch');
		await page.getByLabel('Confirm password').blur();

		await expect(page.getByText('Passwords must match')).toBeVisible();

		await page.getByLabel('Confirm password').fill('Secret123!');
		await expect(page.getByText('Passwords must match')).toBeHidden();
	});

	test('handles FormArray add/remove', async ({ page }) => {
		await page.goto('/contacts/edit');

		await page.getByRole('button', { name: 'Add email' }).click();
		const emailInputs = page.getByLabel(/Email address/);
		await expect(emailInputs).toHaveCount(2);

		await emailInputs.nth(1).fill('backup@example.com');
		await page.getByRole('button', { name: 'Remove email 1' }).click();

		await expect(emailInputs).toHaveCount(1);
		await expect(emailInputs.first()).toHaveValue('backup@example.com');
	});

	test('disables submit until form is valid', async ({ page }) => {
		const submitBtn = page.getByRole('button', { name: 'Register' });
		await expect(submitBtn).toBeDisabled();

		await page.getByLabel('Name').fill('Alice');
		await page.getByLabel('Email').fill('alice@test.com');
		await page.getByLabel('Password', { exact: true }).fill('Secret123!');
		await page.getByLabel('Confirm password').fill('Secret123!');
		await page.getByLabel('Accept terms').check();

		await expect(submitBtn).toBeEnabled();
	});

	test('shows async validator loading state', async ({ page }) => {
		await page.route('**/api/username-check*', async (route) => {
			await new Promise((r) => setTimeout(r, 800));
			await route.fulfill({ json: { available: true } });
		});

		await page.getByLabel('Username').fill('alice');
		await page.getByLabel('Username').blur();

		await expect(page.getByTestId('username-loading')).toBeVisible();
		await expect(page.getByTestId('username-loading')).toBeHidden();
		await expect(page.getByText('Username available')).toBeVisible();
	});
});
```

## Angular Material Components

Angular Material uses proper ARIA attributes. Use role-based locators instead of CSS classes like `.mat-mdc-button`.

```typescript
test.describe('Material components', () => {
	test('mat-select dropdown', async ({ page }) => {
		await page.goto('/preferences');

		await page.getByRole('combobox', { name: 'Language' }).click();
		await page.getByRole('option', { name: 'Spanish' }).click();

		await expect(page.getByRole('combobox', { name: 'Language' })).toContainText('Spanish');
	});

	test('mat-autocomplete suggestions', async ({ page }) => {
		await page.goto('/members/add');

		const roleField = page.getByRole('combobox', { name: 'Role' });
		await roleField.fill('dev');

		await expect(page.getByRole('option', { name: 'Developer' })).toBeVisible();
		await expect(page.getByRole('option', { name: 'DevOps' })).toBeVisible();

		await page.getByRole('option', { name: 'Developer' }).click();
		await expect(roleField).toHaveValue('Developer');
	});

	test('mat-dialog interaction', async ({ page }) => {
		await page.goto('/items');

		await page.getByRole('button', { name: 'Remove item' }).first().click();

		const dialog = page.getByRole('dialog');
		await expect(dialog).toBeVisible();
		await expect(dialog.getByText('Confirm deletion?')).toBeVisible();

		await dialog.getByRole('button', { name: 'Cancel' }).click();
		await expect(dialog).toBeHidden();
	});

	test('mat-table sorting', async ({ page }) => {
		await page.goto('/members');

		await page.getByRole('columnheader', { name: 'Name' }).click();
		const header = page.getByRole('columnheader', { name: 'Name' });
		await expect(header).toHaveAttribute('aria-sort', 'ascending');

		await page.getByRole('columnheader', { name: 'Name' }).click();
		await expect(header).toHaveAttribute('aria-sort', 'descending');
	});

	test('mat-paginator navigation', async ({ page }) => {
		await page.goto('/members');

		await expect(page.getByText('1 - 10 of 100')).toBeVisible();

		await page.getByRole('button', { name: 'Next page' }).click();
		await expect(page.getByText('11 - 20 of 100')).toBeVisible();

		await page.getByRole('combobox', { name: 'Items per page' }).click();
		await page.getByRole('option', { name: '50' }).click();
		await expect(page.getByText('1 - 50 of 100')).toBeVisible();
	});

	test('mat-snack-bar notification', async ({ page }) => {
		await page.goto('/preferences');

		await page.getByRole('button', { name: 'Save' }).click();
		await expect(page.getByText('Changes saved')).toBeVisible();

		await page.getByRole('button', { name: 'Close' }).click();
		await expect(page.getByText('Changes saved')).toBeHidden();
	});

	test('mat-stepper wizard', async ({ page }) => {
		await page.goto('/wizard');

		await expect(page.getByText('Step 1 of 3')).toBeVisible();
		await page.getByLabel('Name').fill('Bob');
		await page.getByRole('button', { name: 'Next' }).click();

		await expect(page.getByText('Step 2 of 3')).toBeVisible();
		await page.getByLabel('Organization').fill('Acme');
		await page.getByRole('button', { name: 'Next' }).click();

		await expect(page.getByText('Step 3 of 3')).toBeVisible();
		await expect(page.getByText('Bob')).toBeVisible();
		await expect(page.getByText('Acme')).toBeVisible();
	});
});
```

## Router Navigation

```typescript
test.describe('Angular Router', () => {
	test('lazy-loaded module loads on navigation', async ({ page }) => {
		await page.goto('/');

		await page.getByRole('link', { name: 'Reports' }).click();
		await page.waitForURL('/reports');

		await expect(page.getByRole('heading', { name: 'Reports Dashboard' })).toBeVisible();
	});

	test('route guard redirects unauthorized users', async ({ page }) => {
		await page.goto('/admin/settings');

		await expect(page).toHaveURL(/\/login/);
		await expect(page.getByRole('heading', { name: 'Sign in' })).toBeVisible();
	});

	test('resolver prefetches data', async ({ page }) => {
		const resolverPromise = page.waitForResponse('**/api/items/*');
		await page.goto('/items/42');
		await resolverPromise;

		await expect(page.getByRole('heading', { level: 1 })).toContainText('Item');
	});

	test('nested router-outlet renders children', async ({ page }) => {
		await page.goto('/account/profile');

		await expect(page.getByRole('heading', { name: 'Account' })).toBeVisible();
		await expect(page.getByRole('heading', { name: 'Profile', level: 2 })).toBeVisible();

		await page.getByRole('link', { name: 'Security' }).click();
		await page.waitForURL('/account/security');

		await expect(page.getByRole('heading', { name: 'Account' })).toBeVisible();
		await expect(page.getByRole('heading', { name: 'Security', level: 2 })).toBeVisible();
	});

	test('query parameters drive filters', async ({ page }) => {
		await page.goto('/products?type=hardware&page=3');

		await expect(page.getByRole('heading', { name: 'Hardware' })).toBeVisible();
		await expect(page.getByText('Page 3')).toBeVisible();
	});

	test('browser back navigates 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(/\/$/);
	});
});
```

## Lazy-Loaded Modules

```typescript
test('lazy module loads without chunk errors', async ({ page }) => {
	const consoleErrors: string[] = [];
	page.on('console', (msg) => {
		if (msg.type() === 'error') consoleErrors.push(msg.text());
	});

	await page.goto('/');

	const chunkRequest = page.waitForResponse((r) => r.url().includes('.js') && r.status() === 200);
	await page.getByRole('link', { name: 'Analytics' }).click();
	await chunkRequest;

	await page.waitForURL('/analytics');
	await expect(page.getByRole('heading', { name: 'Analytics' })).toBeVisible();

	const chunkErrors = consoleErrors.filter((e) => e.includes('ChunkLoadError') || e.includes('Loading chunk'));
	expect(chunkErrors).toEqual([]);
});
```

## Signals and Observables

Playwright cannot subscribe to observables or read signals directly. Test through the rendered output.

```typescript
test.describe('signals through UI', () => {
	test('signal-based counter updates DOM', async ({ page }) => {
		await page.goto('/counter');

		await expect(page.getByTestId('value')).toHaveText('0');

		await page.getByRole('button', { name: 'Increment' }).click();
		await expect(page.getByTestId('value')).toHaveText('1');

		await page.getByRole('button', { name: 'Reset' }).click();
		await expect(page.getByTestId('value')).toHaveText('0');
	});

	test('computed signal updates derived values', async ({ page }) => {
		await page.goto('/cart');
		await expect(page.getByTestId('total')).toHaveText('$0.00');

		await page.goto('/catalog');
		await page.getByRole('listitem').filter({ hasText: '$19.99' }).getByRole('button', { name: 'Add' }).click();

		await page.getByRole('link', { name: 'Cart' }).click();
		await expect(page.getByTestId('total')).toHaveText('$19.99');
	});
});

test.describe('observables through UI', () => {
	test('debounced search batches API calls', async ({ page }) => {
		await page.goto('/search');

		const apiCalls: string[] = [];
		await page.route('**/api/search*', async (route) => {
			apiCalls.push(route.request().url());
			await route.continue();
		});

		await page.getByRole('textbox', { name: 'Search' }).pressSequentially('playwright', {
			delay: 50
		});

		await expect(page.getByRole('listitem')).toHaveCount(5);
		expect(apiCalls.length).toBeLessThanOrEqual(2);
	});

	test('switchMap cancels stale requests', async ({ page }) => {
		await page.goto('/search');

		await page.getByRole('textbox', { name: 'Search' }).fill('initial');
		await page.getByRole('textbox', { name: 'Search' }).fill('final');

		await expect(page.getByRole('listitem').first()).toContainText(/final/i);
	});
});
```

## Zone.js and Change Detection

Angular uses Zone.js for change detection. Playwright does not depend on Zone.js and interacts with the DOM directly.

- **Change detection timing**: After interactions, Angular schedules change detection via Zone.js. Playwright's auto-waiting handles this.
- **Zoneless Angular**: Angular 17+ supports zoneless change detection. Tests work identically since Playwright waits for DOM changes.
- **Long-running async**: `setInterval` or long-running observables keep Angular "not stable." This does not affect Playwright (unlike Protractor).

## SSR Testing

```typescript
// playwright.config.ts for SSR
webServer: {
  command: process.env.CI
    ? 'npx ng build --ssr && node dist/my-app/server/server.mjs'
    : 'npx ng serve --ssr',
  url: 'http://localhost:4200',
  reuseExistingServer: !process.env.CI,
  timeout: 180_000,
},
```

```typescript
test('no hydration errors', 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([]);
});
```

## Protractor Migration Reference

| Protractor                              | Playwright                                     |
| --------------------------------------- | ---------------------------------------------- |
| `element(by.css('.btn'))`               | `page.getByRole('button', { name: '...' })`    |
| `element(by.id('login'))`               | `page.getByTestId('login')`                    |
| `element(by.buttonText('Submit'))`      | `page.getByRole('button', { name: 'Submit' })` |
| `element(by.model('user.name'))`        | `page.getByLabel('Name')`                      |
| `element(by.binding('user.name'))`      | `page.getByText(expectedValue)`                |
| `element(by.repeater('item in items'))` | `page.getByRole('listitem')`                   |
| `browser.waitForAngular()`              | Not needed — Playwright auto-waits             |
| `browser.sleep(3000)`                   | `await expect(locator).toBeVisible()`          |
| `browser.get('/path')`                  | `await page.goto('/path')`                     |
| `protractor.ExpectedConditions`         | `await expect(locator).toBeVisible()`          |

## Build Configurations

| Scenario      | Command                                                       | Notes                          |
| ------------- | ------------------------------------------------------------- | ------------------------------ |
| Local dev     | `npx ng serve`                                                | Fast rebuild, source maps      |
| CI production | `npx ng build && npx http-server dist/app/browser -p 4200 -s` | Tests production bundle        |
| CI SSR        | `npx ng build --ssr && node dist/app/server/server.mjs`       | Tests server-side rendering    |
| Staging       | No `webServer`                                                | Point `baseURL` to staging URL |

The `-s` flag on `http-server` enables SPA fallback for Angular Router.

## CDK Overlay Container

Angular Material and CDK render overlays (dialogs, menus, selects) in a special container outside the component tree. Playwright sees these as regular DOM elements:

```typescript
const dialog = page.getByRole('dialog');
const menu = page.getByRole('menu');
const listbox = page.getByRole('listbox');
```

## Anti-Patterns

| Anti-Pattern                         | Problem                                        | Solution                                           |
| ------------------------------------ | ---------------------------------------------- | -------------------------------------------------- |
| `page.locator('[_ngcontent-xyz]')`   | Scoped style attributes change every build     | Use `getByRole`, `getByLabel`, `getByTestId`       |
| `page.locator('[ng-reflect-model]')` | Only exists in dev mode                        | Test rendered value: `expect(input).toHaveValue()` |
| `page.locator('app-my-component')`   | Component selectors are implementation details | Target rendered content with semantic locators     |
| `page.locator('.mat-mdc-button')`    | Material classes change between versions       | `page.getByRole('button', { name: '...' })`        |
| `page.evaluate(() => window.ng)`     | Not available in production builds             | Test through the DOM                               |
| `await page.waitForTimeout(500)`     | Zone.js timing varies                          | Use auto-retrying assertions                       |
| `browser.waitForAngular()`           | Does not exist in Playwright                   | Remove entirely                                    |
| `ng serve` in CI                     | Slower, includes debug code                    | Use `ng build && http-server`                      |

## Related

- [core/locators.md](../core/locators.md) — locator strategies for Angular Material
- [core/assertions-waiting.md](../core/assertions-waiting.md) — auto-waiting assertions
- [core/forms-validation.md](../testing-patterns/forms-validation.md) — form testing patterns
- [architecture/test-architecture.md](../architecture/test-architecture.md) — E2E vs unit tests with TestBed
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall