Simple and complete Vue DOM testing utilities that encourage good testing practices.
@testing-library/vue is a lightweight adapter that brings DOM Testing Library's philosophy to Vue.js component testing. It wraps @vue/test-utils with a simplified API centered around a single render() function that returns queries like getByText, getByRole, and getByLabelText—encouraging developers to interact with components the way users do rather than through internal APIs or implementation details.
The library exists to address a fundamental problem in component testing: tests that rely on component internals (instance methods, internal state, CSS selectors) break easily during refactoring even when user-facing behavior remains unchanged. By forcing developers to query elements through accessible text, labels, and roles, @testing-library/vue produces more resilient tests that survive implementation changes and better reflect actual user experience.
With over 500,000 weekly downloads, it's widely adopted by teams building Vue 3 applications who want maintainable test suites. The library integrates seamlessly with Vitest and Jest, and pairs naturally with @testing-library/jest-dom for enhanced DOM assertions. It's particularly popular among developers already familiar with Testing Library's philosophy from React or other frameworks, as it provides a consistent testing approach across ecosystems.
Under the hood, @testing-library/vue delegates mounting and DOM manipulation to @vue/test-utils while intentionally hiding methods that expose component internals. This opinionated approach trades some flexibility for test durability—you can't access vm instances or wrapper.findComponent(), but your tests become documentation of how users actually interact with your UI.
import { render, screen, fireEvent, waitFor } from '@testing-library/vue'
import { describe, it, expect } from 'vitest'
import TodoList from './TodoList.vue'
describe('TodoList', () => {
it('adds and completes todos based on user interaction', async () => {
render(TodoList)
const input = screen.getByLabelText(/add new todo/i)
const addButton = screen.getByRole('button', { name: /add/i })
await fireEvent.update(input, 'Buy groceries')
await fireEvent.click(addButton)
const todoItem = screen.getByText('Buy groceries')
expect(todoItem).toBeTruthy()
const checkbox = screen.getByRole('checkbox', { name: /buy groceries/i })
await fireEvent.click(checkbox)
await waitFor(() => {
expect(screen.getByText('Buy groceries')).toHaveClass('completed')
})
expect(screen.getByText(/1 completed/i)).toBeTruthy()
})
it('shows empty state when no todos exist', () => {
render(TodoList)
expect(screen.getByText(/no todos yet/i)).toBeTruthy()
expect(screen.queryByRole('checkbox')).toBeNull()
})
})Form Validation Testing: Verify form behavior by filling inputs using getByLabelText, triggering submissions, and asserting error messages appear—exactly how a user would interact with the form, without inspecting computed properties or validation methods.
Accessibility-Driven Development: Use getByRole queries to ensure interactive elements have proper ARIA roles and labels, catching accessibility issues during development. If you can't query a button by its accessible name, neither can screen reader users.
Conditional Rendering Logic: Test that UI elements appear or disappear based on user actions (clicks, toggles, selections) by asserting DOM presence with queryByText or waitFor, avoiding brittle checks on v-if conditions or internal state flags.
Integration with Vue Router: Render components that use router-link or programmatic navigation, simulate link clicks with fireEvent, and verify the correct content renders—testing the full user journey through routing without mocking Vue Router internals.
Component Library Documentation: Provide executable examples in component library docs that demonstrate real usage patterns. Tests written with Testing Library serve as living documentation showing how consumers should interact with your components.
npm install @testing-library/vuepnpm add @testing-library/vuebun add @testing-library/vue