1# Vue and Nuxt Testing
2 
3## Table of Contents
4 
51. [Commands](#commands)
62. [Configuration](#configuration)
73. [Patterns](#patterns)
84. [Vue vs Nuxt Differences](#vue-vs-nuxt-differences)
95. [Component Testing Dependencies](#component-testing-dependencies)
106. [Testing v-model](#testing-v-model)
117. [Capturing Vue Warnings](#capturing-vue-warnings)
128. [Anti-Patterns](#anti-patterns)
13 
14> **When to use**: Testing Vue 3 applications with composition API, Pinia stores, Vue Router, Nuxt 3 apps, Teleport portals, and transitions.
15 
16## Commands
17 
18```bash
19npm init playwright@latest
20npm install -D @playwright/experimental-ct-vue
21npx playwright test
22npx playwright test -c playwright-ct.config.ts
23```
24 
25## Configuration
26 
27### Vue with Vite
28 
29```typescript
30// playwright.config.ts
31import { defineConfig, devices } from '@playwright/test';
32 
33export default defineConfig({
34  testDir: './tests/e2e',
35  testMatch: '**/*.spec.ts',
36  fullyParallel: true,
37  forbidOnly: !!process.env.CI,
38  retries: process.env.CI ? 2 : 0,
39  workers: process.env.CI ? '50%' : undefined,
40 
41  use: {
42    baseURL: 'http://localhost:5173',
43    trace: 'on-first-retry',
44    screenshot: 'only-on-failure',
45  },
46 
47  projects: [
48    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
49    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
50    { name: 'mobile', use: { ...devices['iPhone 14'] } },
51  ],
52 
53  webServer: {
54    command: process.env.CI
55      ? 'npm run build && npx vite preview --port 5173'
56      : 'npm run dev',
57    url: 'http://localhost:5173',
58    reuseExistingServer: !process.env.CI,
59    timeout: 120_000,
60  },
61});
62```
63 
64### Nuxt 3
65 
66Nuxt uses port 3000 and requires a build step before testing.
67 
68```typescript
69// playwright.config.ts
70import { defineConfig, devices } from '@playwright/test';
71 
72export default defineConfig({
73  testDir: './tests/e2e',
74  testMatch: '**/*.spec.ts',
75  fullyParallel: true,
76  forbidOnly: !!process.env.CI,
77  retries: process.env.CI ? 2 : 0,
78 
79  use: {
80    baseURL: 'http://localhost:3000',
81    trace: 'on-first-retry',
82    screenshot: 'only-on-failure',
83  },
84 
85  projects: [
86    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
87  ],
88 
89  webServer: {
90    command: process.env.CI
91      ? 'npx nuxi build && npx nuxi preview'
92      : 'npx nuxi dev',
93    url: 'http://localhost:3000',
94    reuseExistingServer: !process.env.CI,
95    timeout: 120_000,
96    env: {
97      NUXT_PUBLIC_API_BASE: 'http://localhost:3000/api',
98    },
99  },
100});
101```
102 
103### Component Testing
104 
105```typescript
106// playwright-ct.config.ts
107import { defineConfig, devices } from '@playwright/experimental-ct-vue';
108 
109export default defineConfig({
110  testDir: './tests/components',
111  testMatch: '**/*.ct.ts',
112 
113  use: {
114    trace: 'on-first-retry',
115    ctPort: 3100,
116  },
117 
118  projects: [
119    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
120  ],
121});
122```
123 
124## Patterns
125 
126### Component Testing with Experimental CT
127 
128**Use when**: Testing complex interactive Vue components in isolation (data tables, form components, custom dropdowns).
129 
130**Avoid when**: Component depends heavily on Pinia stores, Vue Router, or backend data—use E2E tests instead.
131 
132```typescript
133// tests/components/Stepper.ct.ts
134import { test, expect } from '@playwright/experimental-ct-vue';
135import Stepper from '../../src/components/Stepper.vue';
136 
137test('increments value on button click', async ({ mount }) => {
138  const component = await mount(Stepper, {
139    props: { value: 0 },
140  });
141 
142  await expect(component.getByText('Value: 0')).toBeVisible();
143  await component.getByRole('button', { name: '+' }).click();
144  await expect(component.getByText('Value: 1')).toBeVisible();
145});
146 
147test('emits change event', async ({ mount }) => {
148  const changes: number[] = [];
149  const component = await mount(Stepper, {
150    props: { value: 10 },
151    on: {
152      change: (val: number) => changes.push(val),
153    },
154  });
155 
156  await component.getByRole('button', { name: '+' }).click();
157  await component.getByRole('button', { name: '+' }).click();
158 
159  expect(changes).toEqual([11, 12]);
160});
161 
162test('renders slot content', async ({ mount }) => {
163  const component = await mount(Stepper, {
164    props: { value: 0 },
165    slots: {
166      default: '<span class="label">Quantity</span>',
167    },
168  });
169 
170  await expect(component.getByText('Quantity')).toBeVisible();
171});
172```
173 
174### Pinia Store Testing Through UI
175 
176**Use when**: Verifying Pinia stores produce correct UI behavior. If the UI is correct, the store is correct.
177 
178**Avoid when**: Testing pure store logic with no UI side effect—use unit tests with Vitest.
179 
180```typescript
181import { test, expect } from '@playwright/test';
182 
183test.describe('shopping cart store', () => {
184  test('adding products updates cart badge', async ({ page }) => {
185    await page.goto('/shop');
186 
187    const badge = page.getByTestId('cart-badge');
188    await expect(badge).toHaveText('0');
189 
190    await page.getByRole('listitem')
191      .filter({ hasText: 'Hoodie' })
192      .getByRole('button', { name: 'Add' })
193      .click();
194    await expect(badge).toHaveText('1');
195 
196    await page.getByRole('listitem')
197      .filter({ hasText: 'Cap' })
198      .getByRole('button', { name: 'Add' })
199      .click();
200    await expect(badge).toHaveText('2');
201 
202    await page.getByRole('link', { name: 'Cart' }).click();
203    await page.waitForURL('/cart');
204 
205    await expect(page.getByText('Hoodie')).toBeVisible();
206    await expect(page.getByText('Cap')).toBeVisible();
207  });
208 
209  test('persisted state survives reload', async ({ page }) => {
210    await page.goto('/shop');
211 
212    await page.getByRole('listitem')
213      .filter({ hasText: 'Hoodie' })
214      .getByRole('button', { name: 'Add' })
215      .click();
216 
217    await page.reload();
218 
219    await expect(page.getByTestId('cart-badge')).toHaveText('1');
220  });
221});
222```
223 
224### Vue Router Navigation
225 
226**Use when**: Testing client-side routing, navigation guards, URL parameters, browser history.
227 
228```typescript
229import { test, expect } from '@playwright/test';
230 
231test.describe('router navigation', () => {
232  test('client-side navigation preserves state', async ({ page }) => {
233    await page.goto('/');
234 
235    await page.evaluate(() => {
236      (window as any).__marker = 'spa';
237    });
238 
239    await page.getByRole('link', { name: 'Shop' }).click();
240    await page.waitForURL('/shop');
241 
242    const marker = await page.evaluate(() => (window as any).__marker);
243    expect(marker).toBe('spa');
244  });
245 
246  test('dynamic route params render content', async ({ page }) => {
247    await page.goto('/items/99');
248 
249    await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
250    await expect(page.getByText('Item #99')).toBeVisible();
251  });
252 
253  test('navigation guard redirects unauthorized users', async ({ page }) => {
254    await page.goto('/admin/dashboard');
255 
256    await expect(page).toHaveURL(/\/login/);
257    await expect(page.getByRole('heading', { name: 'Login' })).toBeVisible();
258  });
259 
260  test('browser history navigation works', async ({ page }) => {
261    await page.goto('/');
262    await page.getByRole('link', { name: 'Shop' }).click();
263    await page.waitForURL('/shop');
264    await page.getByRole('link', { name: 'Contact' }).click();
265    await page.waitForURL('/contact');
266 
267    await page.goBack();
268    await expect(page).toHaveURL(/\/shop/);
269 
270    await page.goBack();
271    await expect(page).toHaveURL(/\/$/);
272 
273    await page.goForward();
274    await expect(page).toHaveURL(/\/shop/);
275  });
276 
277  test('query params update reactive state', async ({ page }) => {
278    await page.goto('/items?sort=price&type=clothing');
279 
280    await expect(page.getByRole('heading', { name: 'Clothing' })).toBeVisible();
281 
282    await page.getByRole('combobox', { name: 'Sort' }).selectOption('name');
283    await expect(page).toHaveURL(/sort=name/);
284  });
285 
286  test('catch-all route shows 404', async ({ page }) => {
287    await page.goto('/nonexistent-page');
288 
289    await expect(page.getByRole('heading', { name: 'Not Found' })).toBeVisible();
290  });
291});
292```
293 
294### Teleport Components
295 
296**Use when**: Testing components rendered via `<Teleport>` (modals, notifications, overlay menus).
297 
298```typescript
299import { test, expect } from '@playwright/test';
300 
301test.describe('teleported elements', () => {
302  test('modal is visible and interactive', async ({ page }) => {
303    await page.goto('/items');
304 
305    await page.getByRole('button', { name: 'Remove' }).first().click();
306 
307    const dialog = page.getByRole('dialog', { name: 'Confirm' });
308    await expect(dialog).toBeVisible();
309 
310    await dialog.getByRole('button', { name: 'Cancel' }).click();
311    await expect(dialog).toBeHidden();
312  });
313 
314  test('notification auto-dismisses', async ({ page }) => {
315    await page.goto('/profile');
316 
317    await page.getByRole('button', { name: 'Update' }).click();
318 
319    const alert = page.getByRole('alert');
320    await expect(alert).toBeVisible();
321    await expect(alert).toContainText('Saved');
322 
323    await expect(alert).toBeHidden({ timeout: 10_000 });
324  });
325 
326  test('dropdown closes on outside click', async ({ page }) => {
327    await page.goto('/home');
328 
329    await page.getByRole('button', { name: 'Menu' }).click();
330 
331    const menu = page.getByRole('menu');
332    await expect(menu).toBeVisible();
333 
334    await page.locator('body').click({ position: { x: 10, y: 10 } });
335    await expect(menu).toBeHidden();
336  });
337});
338```
339 
340### Transitions and Animations
341 
342**Use when**: Verifying `<Transition>` and `<TransitionGroup>` work correctly. Focus on end state, not animation details.
343 
344```typescript
345import { test, expect } from '@playwright/test';
346 
347test.describe('transitions', () => {
348  test('item appears after add', async ({ page }) => {
349    await page.goto('/tasks');
350 
351    await page.getByRole('textbox', { name: 'Task' }).fill('Write tests');
352    await page.getByRole('button', { name: 'Add' }).click();
353 
354    await expect(page.getByText('Write tests')).toBeVisible();
355  });
356 
357  test('item disappears after delete', async ({ page }) => {
358    await page.goto('/tasks');
359 
360    await page.getByRole('textbox', { name: 'Task' }).fill('Temp item');
361    await page.getByRole('button', { name: 'Add' }).click();
362    await expect(page.getByText('Temp item')).toBeVisible();
363 
364    await page.getByRole('listitem')
365      .filter({ hasText: 'Temp item' })
366      .getByRole('button', { name: 'Remove' })
367      .click();
368 
369    await expect(page.getByText('Temp item')).toBeHidden();
370  });
371 
372  test('disable animations for faster tests', async ({ page }) => {
373    await page.addStyleTag({
374      content: `
375        *, *::before, *::after {
376          animation-duration: 0s !important;
377          animation-delay: 0s !important;
378          transition-duration: 0s !important;
379          transition-delay: 0s !important;
380        }
381      `,
382    });
383 
384    await page.goto('/tasks');
385 
386    await page.getByRole('textbox', { name: 'Task' }).fill('Quick task');
387    await page.getByRole('button', { name: 'Add' }).click();
388 
389    await expect(page.getByText('Quick task')).toBeVisible();
390  });
391});
392```
393 
394### Composition API Components
395 
396**Use when**: Testing components with `<script setup>` or `setup()`. From Playwright's perspective, Composition API and Options API are identical.
397 
398```typescript
399import { test, expect } from '@playwright/test';
400 
401test.describe('composition API', () => {
402  test('computed properties update reactively', async ({ page }) => {
403    await page.goto('/pricing');
404 
405    await page.getByLabel('Amount').fill('50');
406    await page.getByLabel('Qty').fill('4');
407 
408    await expect(page.getByTestId('sum')).toHaveText('$200.00');
409 
410    await page.getByLabel('Discount').fill('20');
411    await expect(page.getByTestId('sum')).toHaveText('$160.00');
412  });
413 
414  test('watcher triggers on change', async ({ page }) => {
415    await page.goto('/preferences');
416 
417    await page.getByRole('combobox', { name: 'Locale' }).selectOption('de');
418 
419    await expect(page.getByRole('heading', { name: 'Einstellungen' })).toBeVisible();
420  });
421 
422  test('composable provides debounced search', async ({ page }) => {
423    await page.goto('/shop');
424 
425    const input = page.getByRole('textbox', { name: 'Search' });
426    await input.pressSequentially('hoodie', { delay: 50 });
427 
428    await expect(page.getByRole('listitem')).toHaveCount(2);
429    await expect(page.getByText('Black Hoodie')).toBeVisible();
430  });
431 
432  test('provide/inject updates all consumers', async ({ page }) => {
433    await page.goto('/home');
434 
435    await page.getByRole('switch', { name: 'Dark theme' }).click();
436 
437    await expect(page.locator('body')).toHaveClass(/dark/);
438  });
439});
440```
441 
442### Nuxt-Specific Patterns
443 
444**Use when**: Testing Nuxt 3 with SSR, auto-imports, server routes, and middleware.
445 
446```typescript
447import { test, expect } from '@playwright/test';
448 
449test.describe('nuxt features', () => {
450  test('SSR renders server-fetched data', async ({ page }) => {
451    await page.goto('/posts');
452 
453    await expect(page.getByRole('article')).toHaveCount(10);
454    await expect(page.getByRole('article').first()).toContainText(/\w+/);
455  });
456 
457  test('server route returns data', async ({ request }) => {
458    const response = await request.get('/api/items');
459 
460    expect(response.ok()).toBeTruthy();
461    const data = await response.json();
462    expect(data).toBeInstanceOf(Array);
463    expect(data[0]).toHaveProperty('id');
464  });
465 
466  test('middleware redirects unauthorized', async ({ page }) => {
467    await page.goto('/admin');
468 
469    await expect(page).toHaveURL(/\/login/);
470  });
471 
472  test('NuxtLink enables SPA navigation', async ({ page }) => {
473    await page.goto('/');
474 
475    await page.evaluate(() => {
476      (window as any).__marker = 'spa';
477    });
478 
479    await page.getByRole('link', { name: 'Posts' }).click();
480    await page.waitForURL('/posts');
481 
482    const marker = await page.evaluate(() => (window as any).__marker);
483    expect(marker).toBe('spa');
484  });
485 
486  test('useHead sets meta tags', async ({ page }) => {
487    await page.goto('/posts/hello-world');
488 
489    const title = await page.title();
490    expect(title).toContain('Hello World');
491 
492    const desc = await page.locator('meta[name="description"]').getAttribute('content');
493    expect(desc).toBeTruthy();
494    expect(desc!.length).toBeGreaterThan(50);
495  });
496});
497```
498 
499## Vue vs Nuxt Differences
500 
501| Aspect | Vue 3 (Vite) | Nuxt 3 |
502| --- | --- | --- |
503| Default port | `5173` | `3000` |
504| Dev command | `npm run dev` | `npx nuxi dev` |
505| Build + preview | `npm run build && npx vite preview` | `npx nuxi build && npx nuxi preview` |
506| SSR | Optional | Built-in |
507| API routes | External backend | `/server/api/` built-in |
508| Env variables | `VITE_*` prefix | `NUXT_PUBLIC_*` (client), `NUXT_*` (server) |
509| File-based routing | No | Yes |
510 
511## Component Testing Dependencies
512 
513Components depending on Pinia or Vue Router need these provided:
514 
515```typescript
516// playwright/index.ts
517import { beforeMount } from '@playwright/experimental-ct-vue/hooks';
518import { createPinia } from 'pinia';
519import { createMemoryHistory, createRouter } from 'vue-router';
520 
521beforeMount(async ({ app, hooksConfig }) => {
522  const pinia = createPinia();
523  app.use(pinia);
524 
525  if (hooksConfig?.routes) {
526    const router = createRouter({
527      history: createMemoryHistory(),
528      routes: hooksConfig.routes,
529    });
530    app.use(router);
531  }
532});
533```
534 
535## Testing v-model
536 
537`v-model` works through standard HTML events. Playwright methods trigger correct events automatically:
538 
539```typescript
540await page.getByLabel('Email').fill('[email protected]');
541await page.getByRole('checkbox', { name: 'Subscribe' }).check();
542await page.getByRole('combobox', { name: 'Country' }).selectOption('US');
543```
544 
545## Capturing Vue Warnings
546 
547```typescript
548test('no Vue warnings during render', async ({ page }) => {
549  const warnings: string[] = [];
550  page.on('console', (msg) => {
551    if (msg.type() === 'warning' && msg.text().includes('[Vue warn]')) {
552      warnings.push(msg.text());
553    }
554  });
555 
556  await page.goto('/home');
557  await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible();
558 
559  expect(warnings).toEqual([]);
560});
561```
562 
563## Anti-Patterns
564 
565| Avoid | Problem | Instead |
566| --- | --- | --- |
567| `page.evaluate(() => app.__vue_app__.config.globalProperties.$store)` | Accesses Vue internals; breaks on upgrades | Assert on UI that state produces |
568| `page.locator('[data-v-abc123]')` | Scoped style hashes change on every build | Use `getByRole`, `getByText`, `getByTestId` |
569| Import `.vue` files in E2E tests | E2E tests run in Node.js; `.vue` needs compilation | Use `@playwright/experimental-ct-vue` for component tests |
570| `page.waitForTimeout(300)` for transitions | Arbitrary waits are fragile | `await expect(locator).toBeVisible()` auto-waits |
571| Mock Pinia by patching `window.__pinia` | Fragile; may not trigger reactivity | Control state through UI or mock API responses |
572| Test composables via `page.evaluate` | Composables need Vue's setup context | Test through components or unit test with Vitest |
573| `page.locator('.v-btn')` for Vuetify | Class names change between versions | `page.getByRole('button', { name: 'Submit' })` |
574| Run Nuxt dev server in CI | Dev mode is slower with hot reload overhead | Use `npx nuxi build && npx nuxi preview` |
575