vue-integration-testing

• Framework: Vitest 4 with Playwright browser mode (real browser, not jsdom)
• Database: fake-indexeddb polyfill for IndexedDB
• Queries: Vitest Browser locators with automatic retry

Commands:

```bash

pnpm test # Run all tests

pnpm test:watch # Watch mode

pnpm test:headed # Visible browser (debugging)

pnpm test:coverage # With coverage

```

Place integration tests in src/__tests__/integration/:

```typescript

import { page, userEvent } from 'vitest/browser'

import { afterEach, beforeEach, describe, expect, it } from 'vitest'

import { createTestApp } from '../helpers/createTestApp'

import { cleanupIntegrationTest, setupIntegrationTest } from '../helpers/integrationSetup'

describe('Feature Name', () => {

beforeEach(setupIntegrationTest)

afterEach(cleanupIntegrationTest)

it('describes the user journey being tested', async () => {

const app = await createTestApp()

// Use page objects for interactions

await app.builder.navigateTo()

await app.builder.addStrengthBlock('Squats')

await app.builder.startWorkout()

// Assert outcomes

await expect.poll(() => app.router.currentRoute.value.path).toMatch(/^\/workout\/active/)

app.cleanup()

})

})

```

Tests share fake-indexeddb. Always use the provided setup/cleanup helpers:

• setupIntegrationTest() - Resets workout state, benchmark state, timers, and database
• cleanupIntegrationTest() - Clears state and DOM after each test

Returns a TestApp object with:

Core Properties

| Property | Type | Purpose |

|----------|------|---------|

| router | Router | Vue Router instance for navigation/assertions |

| container | Element | Rendered DOM container |

Page Objects

Pre-instantiated helpers for domain-specific UI workflows:

| Property | Purpose |

|----------|---------|

| common | Shared UI: dialogs, navigation, exercise selection |

| builder | Workout builder operations |

| workout | Active workout view (sets, timers, menus) |

| queue | Workout queue dialog |

| benchmarks | Benchmarks list view |

| benchmarkForm | Benchmark creation form |

| benchmarkDetail | Benchmark detail view |

| logPastWorkout | Past workout logging flow |

Query Methods

Vitest Browser locators with automatic retry:

• getByRole(role, options?) - Query by ARIA role
• getByText(text, options?) - Query by text content
• getByTestId(testId) - Query by data-testid

Helper Methods

• navigateTo(route) - Programmatic navigation
• cleanup() - Unmount the app

Options

```typescript

const app = await createTestApp({ initialRoute: '/workout/active' })

```

Following Martin Fowler's Page Object pattern:

1. No assertions in POs - Return predicates/values, let tests assert
2. Return value objects - Not raw DOM elements (use SetRowPO instead of HTMLInputElement)
3. Encapsulate async - POs handle flushPromises(), waits internally
4. Use data attributes - Prefer data-set-state="active" over CSS class selectors

CommonPO (Base)

Shared across all page objects:

```typescript

await app.common.waitForDialog() // Wait for dialog to appear

await app.common.waitForDialogClose() // Wait for dialog + overlay removal

const button = app.common.getDialogButton('Confirm') // Find button in dialog

app.common.isDialogOpen() // Returns boolean (use in assertions)

await app.common.selectExercise('Squats') // Search and select exercise

await app.common.waitForRoute(/^\/workout/) // Wait for route match

// In tests, assert dialog state with:

expect(app.common.isDialogOpen()).toBe(false)

```

ActiveWorkoutPO

Active workout view interactions:

```typescript

// Wait for UI

await app.workout.waitForTableVisible()

// Set interactions via SetRowPO (preferred - abstracts DOM)

const setRow = app.workout.getSet(0) // Get SetRowPO by index

const activeSet = await app.workout.getActiveSet() // Get active SetRowPO

const values = await setRow.getValues() // { weight, reps, rir }

await setRow.fill({ kg: 100, reps: 8, rir: 2 })

await setRow.complete()

await setRow.isCompleted() // Returns boolean

// High-level operations

await app.workout.fillCardSetAndComplete({ weight: '60', reps: '12', rir: '3' })

await app.workout.endWorkoutAndNavigateToSummary()

// UI queries

const menu = await app.workout.getMenuTrigger()

const nextBtn = await app.workout.getFooterButton('next')

await app.workout.isSetCompleted(0) // Check set completion

```

SetRowPO

Encapsulates a single set row (returned by workout.getSet() or workout.getActiveSet()):

```typescript

const setRow = app.workout.getSet(0)

// Get current values as strings (not raw DOM)

const { weight, reps, rir } = await setRow.getValues()

// Fill values

await setRow.fill({ kg: 100, reps: 8, rir: 2 })

// Complete the set

await setRow.complete()

// Or fill and complete in one call

await setRow.fillAndComplete({ weight: '100', reps: '8', rir: '2' })

// Check state (returns boolean for test assertions)

await setRow.isCompleted()

await setRow.isActive()

```

BuilderPO

Workout builder operations:

```typescript

await app.builder.clickStartNewWorkout() // Click home page button

await app.builder.navigateTo() // Alias for clickStartNewWorkout

await app.builder.openAddBlockDialog() // Open add block dialog

await app.builder.addStrengthBlock('Squats') // Full flow to add block

await app.builder.addTimedBlock('AMRAP') // Add timed block

await app.builder.startWorkout() // Start the workout

```

QueuePO

Workout queue dialog:

```typescript

await app.queue.open()

const items = app.queue.getItems() // Get all queue items

const active = app.queue.getActiveItem() // Get active item

```

Vitest Browser Locators (Preferred)

Locators have built-in retry, pass them directly to userEvent:

```typescript

import { page, userEvent } from 'vitest/browser'

// Click with locator (retries automatically)

await userEvent.click(page.getByRole('button', { name: /submit/i }))

// Fill input

await userEvent.fill(page.getByRole('textbox', { name: /email/i }), 'test@example.com')

// Click directly on locator

await page.getByRole('button', { name: /save/i }).click()

```

DOM Assertions

Use expect.element() for DOM element assertions:

```typescript

await expect.element(page.getByRole('dialog')).toBeVisible()

await expect.element(page.getByRole('button')).toBeDisabled()

await expect.element(page.getByRole('button')).toHaveClass('opacity-0')

await expect.element(page.getByText('Success')).not.toBeInTheDocument()

```

State/Async Assertions

Use expect.poll() for non-DOM state or async values:

```typescript

// Router state

await expect.poll(() => app.router.currentRoute.value.path).toBe('/workout')

// Database queries

await expect.poll(async () => {

const workout = await db.workouts.get('id')

return workout?.name

}).toBe('My Workout')

// With custom timeout

await expect.element(page.getByText('Loaded'), { timeout: 5000 }).toBeVisible()

```

When to Use .element()

Only use .element() when you need the actual DOM element:

```typescript

// Need DOM properties

const input = await page.getByRole('textbox').element()

const value = input.value

// DON'T pass .element() to userEvent (loses retry)

// BAD: await userEvent.click(await button.element())

// GOOD: await userEvent.click(button)

```

Dialog Flow

```typescript

await userEvent.click(page.getByRole('button', { name: /open/i }))

await app.common.waitForDialog()

await userEvent.click(app.common.getDialogButton('Confirm'))

await app.common.waitForDialogClose()

```

Dropdown Menu

```typescript

const menuTrigger = await app.workout.getMenuTrigger()

await userEvent.click(menuTrigger)

await expect.element(page.getByRole('menuitem', { name: /end workout/i })).toBeVisible()

await userEvent.click(page.getByRole('menuitem', { name: /end workout/i }))

```

Complete Workout Flow Example

```typescript

it('completes a strength workout', async () => {

const app = await createTestApp()

// Build workout

await app.builder.navigateTo()

await app.builder.addStrengthBlock('Squats')

await app.builder.startWorkout()

// Wait for table and complete sets

await app.workout.waitForTableVisible()

await app.workout.fillCardSetAndComplete({ weight: '100', reps: '5', rir: '2' })

// Verify prefilled values in next set using SetRowPO

const activeSet = await app.workout.getActiveSet()

const values = await activeSet!.getValues()

expect(values.weight).toBe('100')

// Complete remaining sets

await app.workout.fillCardSetAndComplete({ weight: '100', reps: '5', rir: '2' })

// End workout

await app.workout.endWorkoutAndNavigateToSummary()

// Verify

await expect.element(page.getByText(/workout complete/i)).toBeVisible()

app.cleanup()

})

```

| Need | Query |

|------|-------|

| Button by label | page.getByRole('button', { name: /label/i }) |

| Link | page.getByRole('link', { name: /text/i }) |

| Heading | page.getByRole('heading', { name: /title/i }) |

| Text input | page.getByRole('textbox', { name: /label/i }) |

| Checkbox | page.getByRole('checkbox', { name: /label/i }) |

| Menu item | page.getByRole('menuitem', { name: /text/i }) |

| Toggle button | page.getByRole('button', { pressed: true }) |

| Any text | page.getByText(/partial text/i) |

| Test ID | page.getByTestId('my-element') |

Use case-insensitive regex (/text/i) for resilience.

In-Memory Factories (composable tests)

```typescript

import { workoutBuilder } from '@/__tests__/factories'

const workout = workoutBuilder()

.withName('Leg Day')

.withStrengthBlock({ name: 'Squats' })

.build()

```

Database Factories (integration tests)

```typescript

import { dbWorkoutBuilder } from '@/__tests__/factories'

const workout = await dbWorkoutBuilder()

.withName('Test Workout')

.withStrengthBlock()

.withDuration(3600)

.build()

await db.workouts.add(workout)

```

See src/__tests__/factories/ for available factories.

| Problem | Solution |

|---------|----------|

| Dialog blocks clicks after close | Use waitForDialogClose() - waits for dialog AND overlay |

| Number inputs not updating | Page objects use setInputValueDirectly() with native setter |

| Animations prevent assertions | Wait for animation or use .not.toHaveClass('opacity-0') |

| State leaks between tests | Always use beforeEach(setupIntegrationTest) |

| Multiple elements match text | Use specific role query: getByRole('heading', { name: /title/i }) |

| SVG vs HTML element type | Use ensureHTMLElement() helper from domHelpers.ts |

| Need to check dialog state | Use expect(common.isDialogOpen()).toBe(false) - POs return predicates |

| Accessing input values | Use setRow.getValues() not raw .value - POs return value objects |

| CSS class selectors brittle | Components use data-set-state attributes for testability |

| UI button navigation flaky | Use navigateTo('/path') instead of clicking nav buttons |

Prefer direct router navigation over UI button clicks when moving between pages in tests.

UI button clicks for navigation can be flaky in Vitest Browser Mode due to timing issues with button visibility, element overlays, and Vue Router transitions.

```typescript

// ❌ FLAKY - clicking UI buttons for navigation

await userEvent.click(page.getByRole('button', { name: /go back/i }))

await expect.element(page.getByRole('button', { name: /resume workout/i })).toBeVisible()

// ✅ RELIABLE - direct router navigation

await navigateTo('/exercises')

await expect.element(page.getByRole('button', { name: /some button/i })).toBeVisible()

```

When to use direct navigation:

• Moving between pages to test a global component (e.g., FAB visibility)
• Setting up test preconditions (navigating to a specific starting route)
• Any navigation that isn't the primary behavior being tested

When to use UI navigation:

• Testing the navigation behavior itself (e.g., "clicking Submit navigates to success page")
• User flow tests where the navigation is part of what's being verified