vue-test-utils-skilld

@vue/test-utils 2.5.1（Vue 3）

用意されたソース：input/source、バージョン 2.5.1（package.json:3）。 ピア依存関係として Vue 3.x と @vue/compiler-dom 3.x が必要です。renderToString を使用する場合に限り、オプションのピア依存関係である @vue/server-renderer 3.x も必要です（package.json:73-81）。 テストランナーに依存しません（Vitest、Jest など）。ブラウザーのような DOM 環境（jsdom または happy-dom）が必要です。

インストール：npm install @vue/test-utils --save-dev

クイックスタート

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')
})

公開 API

dist/src/index.d.ts:13 からエクスポート：

エクスポート	種類	用途
mount	関数	コンポーネントをマウントし、VueWrapper を返します（dist/src/mount.d.ts:17）
shallowMount	関数	すべての子コンポーネントをスタブ化する点を除き、mount と同じです（dist/src/mount.d.ts:22）
renderToString	関数	コンポーネントを SSR で文字列にレンダリングします。戻り値は Promise<string> です（dist/src/renderToString.d.ts:4）
flushPromises	関数	保留中の Vue が追跡しないプロミス（モックした API 呼び出し、タイマー）を待機します（dist/src/utils/flushPromises.d.ts:1）
enableAutoUnmount(hook)	関数	テストフックを通じてすべてのラッパーをアンマウントします（dist/src/utils/autoUnmount.d.ts:4）
disableAutoUnmount	関数	自動アンマウントを停止します（dist/src/utils/autoUnmount.d.ts:3）
VueWrapper	クラス	マウントされたコンポーネントインスタンスをラップします（dist/src/vueWrapper.d.ts:5）
DOMWrapper	クラス	DOM 要素をラップします。new DOMWrapper(document.body)（dist/src/domWrapper.d.ts:4）
RouterLinkStub	コンポーネント	<router-link> のスタブです（dist/src/components/RouterLinkStub.d.ts:1）
config	オブジェクト	マウントオプションとラッパープラグインの共有デフォルト設定です（dist/src/config.d.ts:32）
createWrapperError	関数	内部用です。find で見つからなかった場合に返されるエラーラッパーを生成します

基本ルール

• プロミスを返すメソッドはすべて await してください：trigger、setValue、setProps、setData、renderToString、flushPromises。await しないと、DOM が更新される前にアサーションが実行されます。
• 要素が存在する必要がある場合は get() / getComponent() を使用してください。要素が見つからないと例外が発生します。要素がなくても問題ない場合に限り find() / findComponent() を使用してください。要素が見つからない場合は、exists() が false になるエラーラッパーが返されます。
• find() が受け付けるのは CSS セレクターのみです。子コンポーネントを検索するには、findComponent(Component)、findComponent({ name: 'Foo' })、findComponent({ ref: 'foo' })、または CSS セレクターを使用してください。
• テスト間で状態が漏れないよう、テストのセットアップで enableAutoUnmount(afterEach) を一度登録してください。
• Vue が追跡しないプロミス（モックした HTTP クライアント、setTimeout）には flushPromises() を使用してください。
• wrapper.vm で確実に参照できるのは、コンポーネントが公開する内容のみです。オプション API の状態、defineExpose() のバインディング（2.5.0 以降、PR #2927）、または setup() の戻り値が対象です。

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

enableAutoUnmount(afterEach)

バージョンに関する注意：2.4.10 → 2.5.1

• 破壊的変更（2.5.0）：クラスコンポーネントのサポートが削除されました。defineComponent、オプションオブジェクト、または <script setup> SFC で定義された Vue コンポーネントをマウントしてください。https://github.com/vuejs/test-utils/releases/tag/v2.5.0
• 修正（2.5.0）：子コンポーネントがアンマウントされると、その emitted() の履歴がクリアされます。アンマウントする前にイベントをアサートしてください。https://github.com/vuejs/test-utils/pull/2898
• 修正（2.5.0）：defineExpose のバインディングが findComponent(...).vm から参照できるようになりました。https://github.com/vuejs/test-utils/pull/2927
• 修正（2.4.11）：setup() と data() を併用するコンポーネントで、setData() が正しく動作するようになりました。https://github.com/vuejs/test-utils/releases/tag/v2.4.11
• 修正（2.4.11）：trigger('keydown') が仕様に準拠した event.code を設定するようになりました。https://github.com/vuejs/test-utils/pull/2850
• 型（2.4.11）：GlobalMountOptions がエクスポートされるようになりました。https://github.com/vuejs/test-utils/pull/2851

以前の v2 マイルストーンのうち、引き続き関連するもの

• SSR テスト用に、2.3.0 で renderToString が追加されました。https://github.com/vuejs/test-utils/releases/tag/v2.3.0
• 2.2.0 で html({ raw: true })、ディレクティブのスタブ（vName: true）、複数選択用の配列 setValue が追加されました。https://github.com/vuejs/test-utils/releases/tag/v2.2.0
• enableAutoUnmount / disableAutoUnmount により、v1 の enableAutoDestroy が置き換えられました。https://github.com/vuejs/test-utils/releases/tag/v2.0.0-rc.16
• propsData は引き続き動作しますが、非推奨です。props を使用してください（dist/src/types.d.ts:33-35）。
• stubs はレコード（{ Foo: true }）または名前の配列（['Foo']）を受け付けます（dist/src/types.d.ts:80）。

v1（Vue 2）からの移行

全項目の表：移行リファレンス、公式ガイド https://test-utils.vuejs.org/migration/

• propsData -> props、createLocalVue は削除 -> global.plugins / global.mixins
• mocks、stubs、provide、directives は global の下に移動
• destroy() -> unmount()、findAll().at(i) -> findAll()[i]（配列を返します）
• createWrapper() は削除 -> new DOMWrapper(el)
• setChecked / setSelected は削除 -> setValue に統合
• find() ではコンポーネント名で検索できなくなりました。findComponent を使用してください
• shallowMount ではスタブのデフォルトスロットの内容がレンダリングされなくなりました。config.global.renderStubDefaultSlot = true で元に戻せます
• 削除済み：is、isEmpty、isVueInstance、name、setMethods、contains、scopedSlots（slots に統合）

ベストプラクティス

• shallowMount よりも、対象を絞った global.stubs とともに mount を使用してください。浅いテストでは動作ではなく構造を検証するため、スタブ化した子コンポーネントによって実際のインタラクションが隠れてしまいます。https://test-utils.vuejs.org/guide/advanced/stubs-shallow-mount
• 広範囲にスタブ化する場合は、config.global.renderStubDefaultSlot = true を設定して、スタブのデフォルトスロットの内容も引き続きレンダリングされるようにしてください（dist/src/types.d.ts:125-131）。
• vName キーでディレクティブをスタブ化します：global.stubs: { vTooltip: true } を指定するか、置き換え用のディレクティブオブジェクトを渡します。
• <transition> と <transition-group> はデフォルトでスタブ化されます（dist/src/types.d.ts:120-124）。カスタムのトランジションスタブもサポートされています。
• 本番環境と同じ注入方法になるよう、global.provide 経由で inject の値を渡します。型付きの注入キーの場合は、キーをラップします：provide: { [injectionKey as symbol]: value }。
• コンポーザブルをテストするには、最小限のホストコンポーネントをマウントし、wrapper.vm から状態を読み取ります。
• async setup() を使用するコンポーネントは、マウントする前に <Suspense> ホストでラップします。
• <Teleport> については、スタブ化する（global.stubs: { teleport: true }）か、beforeEach でターゲット要素を作成し、document.querySelector で検索します。https://test-utils.vuejs.org/guide/advanced/teleport
• ルーターをインストールせずに <router-link> を含むテストを行う場合は、RouterLinkStub を使用します：global.stubs: { 'router-link': RouterLinkStub }。

リファレンス

• マウントオプションと設定：すべての mount / shallowMount / renderToString オプション、global.*、および config オブジェクト。
• Wrapper API：すべての VueWrapper / DOMWrapper メソッドとシグネチャ。
• v1 -> v2 の移行：オプションとメソッドの完全な対応表、および 2.5.x の変更点。
• テストレシピ：フォーム、v-model、発行イベント、ルーター、Vuex/Pinia、Suspense、Teleport、SSR。