Vue Component Testing: @testing-library/vue vs @vue/test-utils

Both @testing-library/vue and @vue/test-utils help you verify that your Vue components work as expected, but they approach testing from opposite directions. One focuses on the user experience, while the other focuses on the component internals. Let's compare how they handle common testing tasks.

🧠 Core Philosophy: User Behavior vs Implementation Details

@testing-library/vue encourages testing behavior.

• You query elements by their role or visible text.
• Tests remain valid even if you change class names or structure.

// @testing-library/vue: Query by role
import { render, screen } from '@testing-library/vue'
import Button from './Button.vue'

render(Button, { props: { label: 'Submit' } })
const button = screen.getByRole('button', { name: 'Submit' })

@vue/test-utils exposes implementation details.

• You query elements by CSS selectors or component references.
• Tests may break if you refactor the DOM structure.

// @vue/test-utils: Query by CSS selector
import { mount } from '@vue/test-utils'
import Button from './Button.vue'

const wrapper = mount(Button, { props: { label: 'Submit' } })
const button = wrapper.find('button.submit-btn')

🏗️ Rendering Components: render vs mount

@testing-library/vue uses render.

• It attaches the component to a container managed by the library.
• Cleanup happens automatically after each test.

// @testing-library/vue: Render function
import { render } from '@testing-library/vue'

const { container } = render(MyComponent)
// container holds the DOM node

@vue/test-utils uses mount or shallowMount.

• It returns a wrapper object that holds the component instance.
• You must manually handle cleanup in some setups.

// @vue/test-utils: Mount function
import { mount } from '@vue/test-utils'

const wrapper = mount(MyComponent)
// wrapper contains the component instance and DOM

🔍 Querying Elements: Accessibility vs Selectors

@testing-library/vue prefers accessibility queries.

• Uses getByRole, getByText, getByLabelText.
• Ensures your app is accessible to screen readers.

// @testing-library/vue: Accessibility query
import { screen } from '@testing-library/vue'

const input = screen.getByLabelText('Username')
const heading = screen.getByRole('heading', { level: 1 })

@vue/test-utils prefers CSS selectors.

• Uses find, get, findAll with strings or components.
• Gives precise control over specific DOM nodes.

// @vue/test-utils: CSS selector query
import { mount } from '@vue/test-utils'

const wrapper = mount(MyComponent)
const input = wrapper.find('input[name="username"]')
const child = wrapper.findComponent(ChildComponent)

🖱️ User Interactions: fireEvent vs trigger

@testing-library/vue uses fireEvent or userEvent.

• Simulates real browser events like clicks and typing.
• Encourages testing complete user flows.

// @testing-library/vue: Fire event
import { fireEvent } from '@testing-library/vue'

await fireEvent.click(button)
await fireEvent.update(input, 'new value')

@vue/test-utils uses trigger.

• Triggers Vue event listeners directly on the wrapper.
• Faster but less representative of real browser behavior.

// @vue/test-utils: Trigger event
import { mount } from '@vue/test-utils'

await wrapper.find('button').trigger('click')
await wrapper.find('input').setValue('new value')

🔓 Accessing Internals: Discouraged vs vm

@testing-library/vue hides the component instance.

• Direct access to vm is not provided by default.
• Prevents tests from relying on internal state.

// @testing-library/vue: No direct VM access
// You interact only with the DOM
const { container } = render(MyComponent)
// No wrapper.vm available

@vue/test-utils exposes the component instance.

• You can access wrapper.vm to check data or call methods.
• Useful for testing logic that does not affect the DOM.

// @vue/test-utils: Direct VM access
import { mount } from '@vue/test-utils'

const wrapper = mount(MyComponent)
expect(wrapper.vm.count).toBe(0)
wrapper.vm.increment()

🤝 Similarities: Shared Ground Between Libraries

While the differences are clear, both libraries also share many core ideas and tools. Here are key overlaps:

1. ⚛️ Both Support Vue 3 Composition API

• Both work with setup() functions and reactive refs.
• Support testing components written with <script setup>.

// Both: Testing Composition API
// Component uses setup()
// Tests mount/render the same way regardless of API style

2. 🛠️ Both Require Vue Test Environment

• Both need a valid Vue application context.
• Both handle component registration and props similarly.

// Both: Passing props
// @testing-library/vue
render(Component, { props: { id: 1 } })

// @vue/test-utils
mount(Component, { props: { id: 1 } })

3. ✅ Both Support Async Components

• Both handle await for async setup or data fetching.
• Allow waiting for DOM updates before assertions.

// Both: Waiting for updates
// @testing-library/vue
await screen.findByText('Loaded')

// @vue/test-utils
await wrapper.vm.$nextTick()

4. 🧩 Both Support Global Plugins

• Both allow installing Vuex, Pinia, or Vue Router for tests.
• Ensure components have access to global state.

// Both: Global plugins
// @testing-library/vue
render(Component, { global: { plugins: [router] } })

// @vue/test-utils
mount(Component, { global: { plugins: [router] } })

📊 Summary: Key Differences

💡 The Big Picture

@testing-library/vue is like a black-box tester 📦 — it cares only about inputs and outputs. Ideal for feature tests, accessibility compliance, and ensuring stability during refactors.

@vue/test-utils is like a white-box tester 🔍 — it lets you inspect the inner workings. Perfect for unit testing complex logic, reusable libraries, or when you need to mock deep child components.

Final Thought: Many teams use both. Use @testing-library/vue for high-level feature tests and @vue/test-utils for low-level unit tests where internal state matters. Choose based on what you need to prove.