Skip to main content
skill CX Codex

vue-test-utils-skilld — Claude Code skill

The vue-test-utils-skilld skill guides Vue 3 tests with @vue/test-utils 2.5.1, including mounting, wrapper queries, async work, and v1 migration.

MIT 168 installs ★ 186 updated 2026-10-10

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add skilld-dev/vue-ecosystem-skills --skill vue-test-utils-skilld -a claude-code
Open on GitHub

What vue-test-utils-skilld does

The skill covers the current @vue/test-utils 2.5.1 API for Vue 3. It explains when to use mount or shallowMount, how to query component and DOM wrappers, when get() should replace find(), and where await or flushPromises() is needed.

It also covers mount options, stubs, injections, directives, Teleport, Suspense, composable tests, SSR rendering, and migration from Vue Test Utils v1. The guidance includes automatic unmount setup and the behavior of wrapper.vm.

Projects need Vue 3.x, @vue/compiler-dom 3.x, and a browser-like DOM environment such as jsdom or happy-dom. @vue/server-renderer 3.x is needed for renderToString; Vue 2 projects are outside this skill’s target.

What it helps with

  • write a Vue 3 component test
  • choose between mount and shallowMount
  • query a component through its wrapper
  • wait for DOM changes after async work
  • migrate tests from Vue Test Utils v1

Example prompts for the agent

  • Write a test for Counter.vue with @vue/test-utils, pass a starting prop, click the button, and check the rendered value.
  • Review this Vue test using findComponent and fix any assertion that runs before the DOM update.
  • Migrate this Vue Test Utils v1 test to the current @vue/test-utils API for Vue 3.

How to install vue-test-utils-skilld

1Skills CLI (Vercel)

npx skills add skilld-dev/vue-ecosystem-skills --skill vue-test-utils-skilld -a claude-code

2Manually: put the files in place

~/.claude/skills/vue-test-utils-skilld/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/vue-test-utils-skilld/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about vue-test-utils-skilld

How do I install vue-test-utils-skilld in Claude Code?

Run npx skills add skilld-dev/vue-ecosystem-skills --skill vue-test-utils-skilld -a claude-code, then check ~/.claude/skills/vue-test-utils-skilld/SKILL.md.

What does vue-test-utils-skilld do?

It guides the agent through @vue/test-utils 2.5.1 for Vue 3, covering mounts, wrapper queries, async updates, stubs, and migration from v1.

What does the skill require?

Use Vue 3.x, @vue/compiler-dom 3.x, and a browser-like DOM environment such as jsdom or happy-dom. Add @vue/server-renderer 3.x for renderToString.

Source text

SKILL.md · MIT
---
name: vue-test-utils-skilld
description: ALWAYS use when writing, debugging, or reviewing code that imports "@vue/test-utils" or mentions vue test-utils, VTU, mount, shallowMount, findComponent, wrapper queries, or migrating from Vue Test Utils v1. Provides the current API surface, mounting options, wrapper methods, and testing recipes for @vue/test-utils 2.5.1 on Vue 3.
license: MIT
---

# @vue/test-utils 2.5.1 (Vue 3)

Prepared source: `input/source`, version 2.5.1 (`package.json:3`).
Requires Vue 3.x and `@vue/compiler-dom` 3.x as peers; `@vue/server-renderer` 3.x is an optional peer needed only for `renderToString` (`package.json:73-81`).
Test-runner agnostic (Vitest, Jest, others). Needs a browser-like DOM environment (jsdom or happy-dom).

Install: `npm install @vue/test-utils --save-dev`

## Quick start

```ts
import { mount } from '@vue/test-utils'
import Counter from './Counter.vue'

test('increments', async () => {
  const wrapper = mount(Counter, { props: { start: 1 } })
  await wrapper.find('button').trigger('click')
  expect(wrapper.text()).toContain('2')
})
```

## Public API surface

Exports from `dist/src/index.d.ts:13`:

| Export | Kind | Use |
|---|---|---|
| `mount` | function | Mount a component, returns `VueWrapper` (`dist/src/mount.d.ts:17`) |
| `shallowMount` | function | Same as `mount` with all child components stubbed (`dist/src/mount.d.ts:22`) |
| `renderToString` | function | SSR-render a component to a string, `Promise<string>` (`dist/src/renderToString.d.ts:4`) |
| `flushPromises` | function | Await pending non-Vue promises (mocked API calls, timers) (`dist/src/utils/flushPromises.d.ts:1`) |
| `enableAutoUnmount(hook)` | function | Unmount all wrappers via a test hook (`dist/src/utils/autoUnmount.d.ts:4`) |
| `disableAutoUnmount` | function | Stop auto unmounting (`dist/src/utils/autoUnmount.d.ts:3`) |
| `VueWrapper` | class | Wrapper around a mounted component instance (`dist/src/vueWrapper.d.ts:5`) |
| `DOMWrapper` | class | Wrapper around a DOM element; `new DOMWrapper(document.body)` (`dist/src/domWrapper.d.ts:4`) |
| `RouterLinkStub` | component | Stub for `<router-link>` (`dist/src/components/RouterLinkStub.d.ts:1`) |
| `config` | object | Shared default mount options and wrapper plugins (`dist/src/config.d.ts:32`) |
| `createWrapperError` | function | Internal; produces the error wrapper returned by `find` misses |

## Core rules

- `await` every method that returns a promise: `trigger`, `setValue`, `setProps`, `setData`, `renderToString`, `flushPromises`. Without `await`, assertions run before the DOM updates.
- Use `get()` / `getComponent()` when the element must exist; they throw on miss. Use `find()` / `findComponent()` only when absence is a valid outcome; they return an error wrapper whose `exists()` is `false`.
- `find()` accepts CSS selectors only. To locate a child component use `findComponent(Component)`, `findComponent({ name: 'Foo' })`, `findComponent({ ref: 'foo' })`, or a CSS selector.
- Register `enableAutoUnmount(afterEach)` once in test setup to prevent state leaks between tests.
- Use `flushPromises()` for promises Vue does not track (mocked HTTP clients, `setTimeout`).
- `wrapper.vm` only reliably exposes what the component exposes: options-API state, `defineExpose()` bindings (since 2.5.0, PR #2927), or `setup()` return values.

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

enableAutoUnmount(afterEach)
```

## Version notes: 2.4.10 -> 2.5.1

- BREAKING (2.5.0): class component support removed. Mount Vue components defined with `defineComponent`, options objects, or `<script setup>` SFCs. https://github.com/vuejs/test-utils/releases/tag/v2.5.0
- Fix (2.5.0): `emitted()` history of child components is cleared when they unmount. Assert events before unmounting. https://github.com/vuejs/test-utils/pull/2898
- Fix (2.5.0): `defineExpose` bindings are visible on `findComponent(...).vm`. https://github.com/vuejs/test-utils/pull/2927
- Fix (2.4.11): `setData()` works correctly for components mixing `setup()` and `data()`. https://github.com/vuejs/test-utils/releases/tag/v2.4.11
- Fix (2.4.11): `trigger('keydown')` sets a spec-compliant `event.code`. https://github.com/vuejs/test-utils/pull/2850
- Type (2.4.11): `GlobalMountOptions` is exported. https://github.com/vuejs/test-utils/pull/2851

## Earlier v2 milestones still relevant

- `renderToString` added in 2.3.0 for SSR testing. https://github.com/vuejs/test-utils/releases/tag/v2.3.0
- `html({ raw: true })`, directive stubs (`vName: true`), and array `setValue` for multiselect added in 2.2.0. https://github.com/vuejs/test-utils/releases/tag/v2.2.0
- `enableAutoUnmount` / `disableAutoUnmount` replaced v1 `enableAutoDestroy`. https://github.com/vuejs/test-utils/releases/tag/v2.0.0-rc.16
- `propsData` still works but is deprecated; use `props` (`dist/src/types.d.ts:33-35`).
- `stubs` accepts a record (`{ Foo: true }`) or an array of names (`['Foo']`) (`dist/src/types.d.ts:80`).

## Migrating from v1 (Vue 2)

Full table: [migration reference](./references/migration-v2.md), official guide https://test-utils.vuejs.org/migration/

- `propsData` -> `props`; `createLocalVue` removed -> `global.plugins` / `global.mixins`
- `mocks`, `stubs`, `provide`, `directives` moved under `global`
- `destroy()` -> `unmount()`; `findAll().at(i)` -> `findAll()[i]` (returns an array)
- `createWrapper()` removed -> `new DOMWrapper(el)`
- `setChecked` / `setSelected` removed -> merged into `setValue`
- `find()` no longer finds components by name; use `findComponent`
- `shallowMount` no longer renders default slot content of stubs; restore with `config.global.renderStubDefaultSlot = true`
- Removed: `is`, `isEmpty`, `isVueInstance`, `name`, `setMethods`, `contains`, `scopedSlots` (merged into `slots`)

## Best practices

- Prefer `mount` with targeted `global.stubs` over `shallowMount`. Shallow tests assert structure, not behavior, and stubbed children hide real interactions. https://test-utils.vuejs.org/guide/advanced/stubs-shallow-mount
- If you do stub broadly, set `config.global.renderStubDefaultSlot = true` so default slot content of stubs still renders (`dist/src/types.d.ts:125-131`).
- Stub directives with the `vName` key: `global.stubs: { vTooltip: true }` or pass a replacement directive object.
- `<transition>` and `<transition-group>` are stubbed by default (`dist/src/types.d.ts:120-124`); custom transition stubs are supported.
- Pass inject values through `global.provide`, matching production injection. For typed injection keys, wrap the key: `provide: { [injectionKey as symbol]: value }`.
- Test composables by mounting a minimal host component and reading state from `wrapper.vm`.
- Wrap components with `async setup()` in a `<Suspense>` host before mounting.
- For `<Teleport>`, either stub it (`global.stubs: { teleport: true }`) or create the target element in `beforeEach` and query it with `document.querySelector`. https://test-utils.vuejs.org/guide/advanced/teleport
- Use `RouterLinkStub` when testing around `<router-link>` without installing a router: `global.stubs: { 'router-link': RouterLinkStub }`.

## References

- [Mounting options and config](./references/mounting-options.md): every `mount` / `shallowMount` / `renderToString` option, `global.*`, and the `config` object.
- [Wrapper API](./references/wrapper-api.md): every `VueWrapper` / `DOMWrapper` method with signatures.
- [Migration v1 -> v2](./references/migration-v2.md): full option and method mapping plus 2.5.x changes.
- [Testing recipes](./references/recipes.md): forms, `v-model`, emitted events, router, Vuex/Pinia, Suspense, Teleport, SSR.

© skilld-dev · MIT · skilld-dev/vue-ecosystem-skills

Similar skills

All skills for Testing and QA →
vue-testing-best-practices github.com/vuejs-ai vue-testing-best-practices is a Claude Code skill with Vue 3 testing patterns. It helps configure Vitest and write blackbox component tests without brittle assertions. CX Codex +1 15,300installs unit-test-vue-pinia official github unit-test-vue-pinia writes and reviews unit tests for Vue 3, TypeScript, Vitest and Pinia code. Useful when your tests reach into component internals instead of behavior. CX Codex +1 1,800installs Expert Vue.js Frontend Engineer official github Expert Vue.js Frontend Engineer — a GitHub Copilot subagent for building Vue 3 frontends with TypeScript. It handles components, Pinia stores, tests and rendering performance as part of your coding session. CX Codex +1 ★ 41,430repo stars vue-3-nuxt-3-development-cursorrules-prompt-file PatrickJS vue-3-nuxt-3-development-cursorrules-prompt-file directs Cursor to follow Vue 3 and Nuxt 3 practices. Requires planning via pseudocode first, uses the Composition API, and relies exclusively on TailwindCSS. CX Codex +1 ★ 41,178repo stars antdv-next Antdv Next team A skill for Claude Code finds Antdv Next Vue 3 component docs, including props, events and slots. It activates for requests about component APIs, playground examples or theme tokens. CX Codex +1 1,500installs vue-expert https://github.com/Jeffallan vue-expert guides Vue 3 work with the Composition API, Nuxt 3, Pinia, and Vite. Use it for components, PWAs, and Quasar or Capacitor apps. CX Codex +1 4,800installs

From the same set32

The whole set →
vueuse-core-skilld vueuse-core-skilld — a skill with the full @vueuse/core 15.0.0 API: new composables, v14 migration rules, deprecated functions and environment requirements. CX Codex +1 219installs vee-validate-skilld vee-validate-skilld — a skill for writing, reviewing, and debugging Vue 3 forms with vee-validate 4.15.x. Covers Composition API, validation schema patterns, typed-schema integration, version-specific changes since 4.9, and common pitfalls. CX Codex +1 188installs primevue-skilld primevue-skilld is a Claude Code skill that guides PrimeVue v5 setup, current component APIs, and theming in Vue 3 projects. CX Codex +1 187installs shadcn-vue-skilld shadcn-vue-skilld — a skill for Claude Code, Codex, Cursor and other agents covering shadcn-vue 2.8.2 CLI in Vue and Nuxt projects. Carries exact flags for every command and the full components.json schema. CX Codex +1 174installs vueuse-components-skilld vueuse-components-skilld is a Claude Code skill that guides Vue 3 template work with @vueuse/components, including debugging and translating composables into component or directive usage. CX Codex +1 168installs motion-v-skilld motion-v-skilld — a skill for motion-v (Motion for Vue) animations: motion component, gestures, variants, v-motion directive, Nuxt module. CX Codex +1 146installs reka-ui-skilld reka-ui-skilld is a Claude Code skill for building accessible interfaces with Reka UI 2.10.5 in Vue 3. It helps agents write clean component compositions and use props accurately. CX Codex +1 146installs vueuse-integrations-skilld vueuse-integrations-skilld equips AI agents with reference rules for 12 utility wrappers in @vueuse/integrations v15. Prevents broken imports and guides API migration. CX Codex +1 145installs

Project sponsors

Companies that keep this analytics open