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/vue.md

View on GitHub
# Vue and Nuxt Testing

## Table of Contents

1. [Commands](#commands)
2. [Configuration](#configuration)
3. [Patterns](#patterns)
4. [Vue vs Nuxt Differences](#vue-vs-nuxt-differences)
5. [Component Testing Dependencies](#component-testing-dependencies)
6. [Testing v-model](#testing-v-model)
7. [Capturing Vue Warnings](#capturing-vue-warnings)
8. [Anti-Patterns](#anti-patterns)

> **When to use**: Testing Vue 3 applications with composition API, Pinia stores, Vue Router, Nuxt 3 apps, Teleport portals, and transitions.

## Commands

```bash
npm init playwright@latest
npm install -D @playwright/experimental-ct-vue
npx playwright test
npx playwright test -c playwright-ct.config.ts
```

## Configuration

### Vue with Vite

```typescript
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
	testDir: './tests/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:5173',
		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 ? 'npm run build && npx vite preview --port 5173' : 'npm run dev',
		url: 'http://localhost:5173',
		reuseExistingServer: !process.env.CI,
		timeout: 120_000
	}
});
```

### Nuxt 3

Nuxt uses port 3000 and requires a build step before testing.

```typescript
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
	testDir: './tests/e2e',
	testMatch: '**/*.spec.ts',
	fullyParallel: true,
	forbidOnly: !!process.env.CI,
	retries: process.env.CI ? 2 : 0,

	use: {
		baseURL: 'http://localhost:3000',
		trace: 'on-first-retry',
		screenshot: 'only-on-failure'
	},

	projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],

	webServer: {
		command: process.env.CI ? 'npx nuxi build && npx nuxi preview' : 'npx nuxi dev',
		url: 'http://localhost:3000',
		reuseExistingServer: !process.env.CI,
		timeout: 120_000,
		env: {
			NUXT_PUBLIC_API_BASE: 'http://localhost:3000/api'
		}
	}
});
```

### Component Testing

```typescript
// playwright-ct.config.ts
import { defineConfig, devices } from '@playwright/experimental-ct-vue';

export default defineConfig({
	testDir: './tests/components',
	testMatch: '**/*.ct.ts',

	use: {
		trace: 'on-first-retry',
		ctPort: 3100
	},

	projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }]
});
```

## Patterns

### Component Testing with Experimental CT

**Use when**: Testing complex interactive Vue components in isolation (data tables, form components, custom dropdowns).

**Avoid when**: Component depends heavily on Pinia stores, Vue Router, or backend data—use E2E tests instead.

```typescript
// tests/components/Stepper.ct.ts
import { test, expect } from '@playwright/experimental-ct-vue';
import Stepper from '../../src/components/Stepper.vue';

test('increments value on button click', async ({ mount }) => {
	const component = await mount(Stepper, {
		props: { value: 0 }
	});

	await expect(component.getByText('Value: 0')).toBeVisible();
	await component.getByRole('button', { name: '+' }).click();
	await expect(component.getByText('Value: 1')).toBeVisible();
});

test('emits change event', async ({ mount }) => {
	const changes: number[] = [];
	const component = await mount(Stepper, {
		props: { value: 10 },
		on: {
			change: (val: number) => changes.push(val)
		}
	});

	await component.getByRole('button', { name: '+' }).click();
	await component.getByRole('button', { name: '+' }).click();

	expect(changes).toEqual([11, 12]);
});

test('renders slot content', async ({ mount }) => {
	const component = await mount(Stepper, {
		props: { value: 0 },
		slots: {
			default: '<span class="label">Quantity</span>'
		}
	});

	await expect(component.getByText('Quantity')).toBeVisible();
});
```

### Pinia Store Testing Through UI

**Use when**: Verifying Pinia stores produce correct UI behavior. If the UI is correct, the store is correct.

**Avoid when**: Testing pure store logic with no UI side effect—use unit tests with Vitest.

```typescript
import { test, expect } from '@playwright/test';

test.describe('shopping cart store', () => {
	test('adding products updates cart badge', async ({ page }) => {
		await page.goto('/shop');

		const badge = page.getByTestId('cart-badge');
		await expect(badge).toHaveText('0');

		await page.getByRole('listitem').filter({ hasText: 'Hoodie' }).getByRole('button', { name: 'Add' }).click();
		await expect(badge).toHaveText('1');

		await page.getByRole('listitem').filter({ hasText: 'Cap' }).getByRole('button', { name: 'Add' }).click();
		await expect(badge).toHaveText('2');

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

		await expect(page.getByText('Hoodie')).toBeVisible();
		await expect(page.getByText('Cap')).toBeVisible();
	});

	test('persisted state survives reload', async ({ page }) => {
		await page.goto('/shop');

		await page.getByRole('listitem').filter({ hasText: 'Hoodie' }).getByRole('button', { name: 'Add' }).click();

		await page.reload();

		await expect(page.getByTestId('cart-badge')).toHaveText('1');
	});
});
```

### Vue Router Navigation

**Use when**: Testing client-side routing, navigation guards, URL parameters, browser history.

```typescript
import { test, expect } from '@playwright/test';

test.describe('router navigation', () => {
	test('client-side navigation preserves state', async ({ page }) => {
		await page.goto('/');

		await page.evaluate(() => {
			(window as any).__marker = 'spa';
		});

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

		const marker = await page.evaluate(() => (window as any).__marker);
		expect(marker).toBe('spa');
	});

	test('dynamic route params render content', async ({ page }) => {
		await page.goto('/items/99');

		await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
		await expect(page.getByText('Item #99')).toBeVisible();
	});

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

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

	test('browser history navigation works', async ({ page }) => {
		await page.goto('/');
		await page.getByRole('link', { name: 'Shop' }).click();
		await page.waitForURL('/shop');
		await page.getByRole('link', { name: 'Contact' }).click();
		await page.waitForURL('/contact');

		await page.goBack();
		await expect(page).toHaveURL(/\/shop/);

		await page.goBack();
		await expect(page).toHaveURL(/\/$/);

		await page.goForward();
		await expect(page).toHaveURL(/\/shop/);
	});

	test('query params update reactive state', async ({ page }) => {
		await page.goto('/items?sort=price&type=clothing');

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

		await page.getByRole('combobox', { name: 'Sort' }).selectOption('name');
		await expect(page).toHaveURL(/sort=name/);
	});

	test('catch-all route shows 404', async ({ page }) => {
		await page.goto('/nonexistent-page');

		await expect(page.getByRole('heading', { name: 'Not Found' })).toBeVisible();
	});
});
```

### Teleport Components

**Use when**: Testing components rendered via `<Teleport>` (modals, notifications, overlay menus).

```typescript
import { test, expect } from '@playwright/test';

test.describe('teleported elements', () => {
	test('modal is visible and interactive', async ({ page }) => {
		await page.goto('/items');

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

		const dialog = page.getByRole('dialog', { name: 'Confirm' });
		await expect(dialog).toBeVisible();

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

	test('notification auto-dismisses', async ({ page }) => {
		await page.goto('/profile');

		await page.getByRole('button', { name: 'Update' }).click();

		const alert = page.getByRole('alert');
		await expect(alert).toBeVisible();
		await expect(alert).toContainText('Saved');

		await expect(alert).toBeHidden({ timeout: 10_000 });
	});

	test('dropdown closes on outside click', async ({ page }) => {
		await page.goto('/home');

		await page.getByRole('button', { name: 'Menu' }).click();

		const menu = page.getByRole('menu');
		await expect(menu).toBeVisible();

		await page.locator('body').click({ position: { x: 10, y: 10 } });
		await expect(menu).toBeHidden();
	});
});
```

### Transitions and Animations

**Use when**: Verifying `<Transition>` and `<TransitionGroup>` work correctly. Focus on end state, not animation details.

```typescript
import { test, expect } from '@playwright/test';

test.describe('transitions', () => {
	test('item appears after add', async ({ page }) => {
		await page.goto('/tasks');

		await page.getByRole('textbox', { name: 'Task' }).fill('Write tests');
		await page.getByRole('button', { name: 'Add' }).click();

		await expect(page.getByText('Write tests')).toBeVisible();
	});

	test('item disappears after delete', async ({ page }) => {
		await page.goto('/tasks');

		await page.getByRole('textbox', { name: 'Task' }).fill('Temp item');
		await page.getByRole('button', { name: 'Add' }).click();
		await expect(page.getByText('Temp item')).toBeVisible();

		await page
			.getByRole('listitem')
			.filter({ hasText: 'Temp item' })
			.getByRole('button', { name: 'Remove' })
			.click();

		await expect(page.getByText('Temp item')).toBeHidden();
	});

	test('disable animations for faster tests', async ({ page }) => {
		await page.addStyleTag({
			content: `
        *, *::before, *::after {
          animation-duration: 0s !important;
          animation-delay: 0s !important;
          transition-duration: 0s !important;
          transition-delay: 0s !important;
        }
      `
		});

		await page.goto('/tasks');

		await page.getByRole('textbox', { name: 'Task' }).fill('Quick task');
		await page.getByRole('button', { name: 'Add' }).click();

		await expect(page.getByText('Quick task')).toBeVisible();
	});
});
```

### Composition API Components

**Use when**: Testing components with `<script setup>` or `setup()`. From Playwright's perspective, Composition API and Options API are identical.

```typescript
import { test, expect } from '@playwright/test';

test.describe('composition API', () => {
	test('computed properties update reactively', async ({ page }) => {
		await page.goto('/pricing');

		await page.getByLabel('Amount').fill('50');
		await page.getByLabel('Qty').fill('4');

		await expect(page.getByTestId('sum')).toHaveText('$200.00');

		await page.getByLabel('Discount').fill('20');
		await expect(page.getByTestId('sum')).toHaveText('$160.00');
	});

	test('watcher triggers on change', async ({ page }) => {
		await page.goto('/preferences');

		await page.getByRole('combobox', { name: 'Locale' }).selectOption('de');

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

	test('composable provides debounced search', async ({ page }) => {
		await page.goto('/shop');

		const input = page.getByRole('textbox', { name: 'Search' });
		await input.pressSequentially('hoodie', { delay: 50 });

		await expect(page.getByRole('listitem')).toHaveCount(2);
		await expect(page.getByText('Black Hoodie')).toBeVisible();
	});

	test('provide/inject updates all consumers', async ({ page }) => {
		await page.goto('/home');

		await page.getByRole('switch', { name: 'Dark theme' }).click();

		await expect(page.locator('body')).toHaveClass(/dark/);
	});
});
```

### Nuxt-Specific Patterns

**Use when**: Testing Nuxt 3 with SSR, auto-imports, server routes, and middleware.

```typescript
import { test, expect } from '@playwright/test';

test.describe('nuxt features', () => {
	test('SSR renders server-fetched data', async ({ page }) => {
		await page.goto('/posts');

		await expect(page.getByRole('article')).toHaveCount(10);
		await expect(page.getByRole('article').first()).toContainText(/\w+/);
	});

	test('server route returns data', async ({ request }) => {
		const response = await request.get('/api/items');

		expect(response.ok()).toBeTruthy();
		const data = await response.json();
		expect(data).toBeInstanceOf(Array);
		expect(data[0]).toHaveProperty('id');
	});

	test('middleware redirects unauthorized', async ({ page }) => {
		await page.goto('/admin');

		await expect(page).toHaveURL(/\/login/);
	});

	test('NuxtLink enables SPA navigation', async ({ page }) => {
		await page.goto('/');

		await page.evaluate(() => {
			(window as any).__marker = 'spa';
		});

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

		const marker = await page.evaluate(() => (window as any).__marker);
		expect(marker).toBe('spa');
	});

	test('useHead sets meta tags', async ({ page }) => {
		await page.goto('/posts/hello-world');

		const title = await page.title();
		expect(title).toContain('Hello World');

		const desc = await page.locator('meta[name="description"]').getAttribute('content');
		expect(desc).toBeTruthy();
		expect(desc!.length).toBeGreaterThan(50);
	});
});
```

## Vue vs Nuxt Differences

| Aspect             | Vue 3 (Vite)                        | Nuxt 3                                      |
| ------------------ | ----------------------------------- | ------------------------------------------- |
| Default port       | `5173`                              | `3000`                                      |
| Dev command        | `npm run dev`                       | `npx nuxi dev`                              |
| Build + preview    | `npm run build && npx vite preview` | `npx nuxi build && npx nuxi preview`        |
| SSR                | Optional                            | Built-in                                    |
| API routes         | External backend                    | `/server/api/` built-in                     |
| Env variables      | `VITE_*` prefix                     | `NUXT_PUBLIC_*` (client), `NUXT_*` (server) |
| File-based routing | No                                  | Yes                                         |

## Component Testing Dependencies

Components depending on Pinia or Vue Router need these provided:

```typescript
// playwright/index.ts
import { beforeMount } from '@playwright/experimental-ct-vue/hooks';
import { createPinia } from 'pinia';
import { createMemoryHistory, createRouter } from 'vue-router';

beforeMount(async ({ app, hooksConfig }) => {
	const pinia = createPinia();
	app.use(pinia);

	if (hooksConfig?.routes) {
		const router = createRouter({
			history: createMemoryHistory(),
			routes: hooksConfig.routes
		});
		app.use(router);
	}
});
```

## Testing v-model

`v-model` works through standard HTML events. Playwright methods trigger correct events automatically:

```typescript
await page.getByLabel('Email').fill('user@test.com');
await page.getByRole('checkbox', { name: 'Subscribe' }).check();
await page.getByRole('combobox', { name: 'Country' }).selectOption('US');
```

## Capturing Vue Warnings

```typescript
test('no Vue warnings during render', async ({ page }) => {
	const warnings: string[] = [];
	page.on('console', (msg) => {
		if (msg.type() === 'warning' && msg.text().includes('[Vue warn]')) {
			warnings.push(msg.text());
		}
	});

	await page.goto('/home');
	await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible();

	expect(warnings).toEqual([]);
});
```

## Anti-Patterns

| Avoid                                                                 | Problem                                            | Instead                                                   |
| --------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
| `page.evaluate(() => app.__vue_app__.config.globalProperties.$store)` | Accesses Vue internals; breaks on upgrades         | Assert on UI that state produces                          |
| `page.locator('[data-v-abc123]')`                                     | Scoped style hashes change on every build          | Use `getByRole`, `getByText`, `getByTestId`               |
| Import `.vue` files in E2E tests                                      | E2E tests run in Node.js; `.vue` needs compilation | Use `@playwright/experimental-ct-vue` for component tests |
| `page.waitForTimeout(300)` for transitions                            | Arbitrary waits are fragile                        | `await expect(locator).toBeVisible()` auto-waits          |
| Mock Pinia by patching `window.__pinia`                               | Fragile; may not trigger reactivity                | Control state through UI or mock API responses            |
| Test composables via `page.evaluate`                                  | Composables need Vue's setup context               | Test through components or unit test with Vitest          |
| `page.locator('.v-btn')` for Vuetify                                  | Class names change between versions                | `page.getByRole('button', { name: 'Submit' })`            |
| Run Nuxt dev server in CI                                             | Dev mode is slower with hot reload overhead        | Use `npx nuxi build && npx nuxi preview`                  |
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