---

name: vue-integration-testing description: Write Vue 3 integration tests using Vitest Browser Mode and Page Objects. Use proactively whenever adding tests for views, components with routing, user flows, or features that span multiple components. Triggers include "add tests", "write tests", "test this", "needs tests", "integration tests", "test the feature", "test user flow", or any task involving testing UI interactions, navigation, dialogs, forms, or multi-step workflows.

Vue Integration Testing

Write integration tests that verify complete user flows using Vitest Browser Mode (Playwright) with the createTestApp helper and Page Objects.

Test Infrastructure

• 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:

pnpm test              # Run all tests
pnpm test:watch        # Watch mode
pnpm test:headed       # Visible browser (debugging)
pnpm test:coverage     # With coverage

Test File Structure

Place integration tests in src/__tests__/integration/:

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()
  })
})

Test Isolation

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

createTestApp API

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

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

Page Object Design Principles

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

Page Object Reference

CommonPO (Base)

Shared across all page objects:

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:

// 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()):

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:

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:

await app.queue.open()
const items = app.queue.getItems()       // Get all queue items
const active = app.queue.getActiveItem() // Get active item

Query & Assertion Patterns

Vitest Browser Locators (Preferred)

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

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:

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:

// 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:

// 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)

Interaction Patterns

Dialog Flow

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

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

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()
})

Query Selection Guide

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.

Factory Usage

In-Memory Factories (composable tests)

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

const workout = workoutBuilder()
  .withName('Leg Day')
  .withStrengthBlock({ name: 'Squats' })
  .build()

Database Factories (integration tests)

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.

Common Gotchas

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

Navigation Reliability

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.

// ❌ 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