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
npx skills add skilld-dev/vue-ecosystem-skills --skill vue-test-utils-skilld -a claude-codeWhat 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
mountandshallowMount - 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.vuewith@vue/test-utils, pass a starting prop, click the button, and check the rendered value. - Review this Vue test using
findComponentand fix any assertion that runs before the DOM update. - Migrate this Vue Test Utils v1 test to the current
@vue/test-utilsAPI 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-code2Manually: put the files in place
~/.claude/skills/vue-test-utils-skilld/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/vue-test-utils-skilld/
1Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill vue-test-utils-skilld -a codex2Manually: put the files in place
.agents/skills/vue-test-utils-skilld/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill vue-test-utils-skilld -a cursor2Manually: put the files in place
.cursor/skills/vue-test-utils-skilld/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install skilld-dev/vue-ecosystem-skills skills/vue-test-utils-skilld2Manually: put the files in place
.github/skills/vue-test-utils-skilld/SKILL.md1Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill vue-test-utils-skilld -a gemini-cli2Platform CLI
gemini skills install https://github.com/skilld-dev/vue-ecosystem-skills --path skills/vue-test-utils-skilldManually: put the files in place
.devin/skills/vue-test-utils-skilld/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill vue-test-utils-skilld -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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