vue-test-utils-skilld

vuejs/test-utils @vue/test-utils

Version: 2.4.6 Deps: js-beautify@^1.14.9, vue-component-type-helpers@^2.0.0 Tags: latest: 2.4.6, 2.0.0-alpha.0: 2.0.0-alpha.0, 2.0.0-alpha.1: 2.0.0-alpha.1, 2.0.0-alpha.2: 2.0.0-alpha.2, 2.0.0-alpha.3: 2.0.0-alpha.3, 2.0.0-alpha.4: 2.0.0-alpha.4, next: 2.4.0-alpha.2, 2.0.0-alpha.8: 2.0.0-alpha.8, 2.0.0-beta.1: 2.0.0-beta.1, 2.0.0-beta.2: 2.0.0-beta.2, 2.0.0-beta.3: 2.0.0-beta.3, 2.0.0-beta.4: 2.0.0-beta.4, 2.0.0-beta.5: 2.0.0-beta.5, 2.0.0-beta.7: 2.0.0-beta.7, 2.0.0-beta.8: 2.0.0-beta.8, 2.0.0-beta.9: 2.0.0-beta.9, 2.0.0-beta.10: 2.0.0-beta.10, 2.0.0-beta.12: 2.0.0-beta.12, 2.0.0-beta.13: 2.0.0-beta.13, 2.0.0-rc.0: 2.0.0-rc.0, 2.0.0-rc.1: 2.0.0-rc.1, 2.0.0-rc.2: 2.0.0-rc.2, 2.0.0-rc.3: 2.0.0-rc.3, 2.0.0-rc.4: 2.0.0-rc.4, 2.0.0-rc.5: 2.0.0-rc.5, 2.0.0-rc.6: 2.0.0-rc.6, 2.0.0-rc.7: 2.0.0-rc.7, 2.0.0-rc.8: 2.0.0-rc.8, 2.0.0-rc.9: 2.0.0-rc.9, 2.0.0-rc.10: 2.0.0-rc.10, 2.0.0-rc.11: 2.0.0-rc.11, 2.0.0-rc.12: 2.0.0-rc.12, 2.0.0-rc.14: 2.0.0-rc.14, 2.0.0-rc.16: 2.0.0-rc.16, 2.0.0-rc.18: 2.0.0-rc.18, legacy: 1.3.6, 2.4.0-alpha.0: 2.4.0-alpha.0, v2.4.0-alpha.2: 2.4.0-alpha.2

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

• BREAKING: propsData — v2 renamed to props for consistency with component definitions source

• BREAKING: createLocalVue — removed in v2, use the global mounting option to install plugins, mixins, or directives source

• BREAKING: mocks and stubs — moved into the global mounting option in v2 as they apply to all components source

• BREAKING: destroy() — renamed to unmount() in v2 to match Vue 3 lifecycle naming source

• BREAKING: findAll().at() — removed in v2; findAll() now returns a standard array of wrappers source

• BREAKING: createWrapper() — removed in v2, use the new DOMWrapper() constructor for non-component elements source

• BREAKING: shallowMount — v2 no longer renders default slot content for stubbed components by default source

• BREAKING: find() — now only supports querySelector syntax; use findComponent() to locate Vue components source

• BREAKING: setSelected and setChecked — removed in v2, functionality merged into setValue() source

• BREAKING: attachToDocument — renamed to attachTo in v2 source

• BREAKING: emittedByOrder — removed in v2, use emitted() instead source

• NEW: renderToString() — added in v2.3.0 to support SSR testing source

• NEW: enableAutoUnmount() / disableAutoUnmount() — replaces enableAutoDestroy in v2 source

• DEPRECATED: scopedSlots — removed in v2 and merged into the slots mounting option source

Also changed: setValue() and trigger() return nextTick · slots scope exposed as params in string templates · is, isEmpty, isVueInstance, name, setMethods, and contains removed

Best Practices

• Always await methods that return nextTick (trigger, setValue, setProps, setData) to ensure DOM updates are processed before running assertions source

// Preferred
await wrapper.find('button').trigger('click')
expect(wrapper.text()).toContain('Count: 1')

// Avoid — assertion runs before DOM update
wrapper.find('button').trigger('click')
expect(wrapper.text()).toContain('Count: 1')

• Prefer get() and getComponent() over find() and findComponent() when you expect the element to exist — they throw immediately if not found, providing clearer test failures source

• Use flushPromises() to resolve non-Vue asynchronous operations such as mocked API calls (axios) or external promise-based logic that Vue doesn't track source

• Enable enableAutoUnmount(afterEach) in your test setup to automatically clean up wrappers after every test, preventing state pollution and memory leaks source

import { enableAutoUnmount } from '@vue/test-utils'
import { afterEach } from 'vitest'

enableAutoUnmount(afterEach)

• Wrap components with async setup() in a <Suspense> component within your test to correctly handle their asynchronous initialization source

• Enable config.global.renderStubDefaultSlot = true when using shallow mounting to ensure content within default slots is rendered for verification source

• Prefer mount() with specific global.stubs over shallow: true to keep tests more production-like while still isolating specific complex child components source

• Use global.provide to pass data to components using inject, ensuring the component tree's dependency injection works as it does in production source

• Test complex composables by mounting a minimal TestComponent that calls the composable, allowing you to verify internal state via wrapper.vm source

const TestComponent = defineComponent({
  setup() {
    return { ...useMyComposable() }
  }
})
const wrapper = mount(TestComponent)
expect(wrapper.vm.someValue).toBe(true)

• Stub custom directives using the vName naming convention (e.g., vTooltip: true) in the global.stubs mounting option source