Wrapper

vue-test-utils はラッパベースの API です。

Wrapper は、マウントされたコンポーネントと仮想 DOM 、またはコンポーネントと仮想 DOM をテストするメソッドを含むオブジェクトです。

プロパティ

vm

Component (読み込み専用):これは vue のインスタンスです。wrapper.vm を使って vm のプロパティとインスタンスメソッドにアクセスできます。これは、Vue コンポーネントのラッパもしくは Vue コンポーネントをバインディングしている HTMLElement のラッパにのみ存在します。

element

HTMLElement (読み込み専用): ラッパのルート DOM

options

options.attachedToDocument

Boolean (読み込み専用): マウンティングオプションで attachToDocumenttrue だった場合は True です。

メソッド

attributes()

Wrapper にラップされている要素の属性をオブジェクトで返します。

  • 戻り値: {[attribute: string]: any}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
expect(wrapper.attributes().id).toBe('foo')

classes()

Wrapper にラップされている要素の class 名を配列で返します。

  • 戻り値: Array<{string}>

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
expect(wrapper.classes()).toContain('bar')

contains(selector)

Wrapper に要素、もしくはセレクタで指定したコンポーネントを含んでいるか検証します。

  • 引数:

    • {string|Component} selector
  • 戻り値: {boolean}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'
import Bar from './Bar.vue'

const wrapper = mount(Foo)
expect(wrapper.contains('p')).toBe(true)
expect(wrapper.contains(Bar)).toBe(true)

destroy()

Vue コンポーネントインスタンスを破棄します。

  • 例:
import { mount } from '@vue/test-utils'
import sinon from 'sinon'

const spy = sinon.stub()
mount({
  render: null,
  destroyed() {
    spy()
  }
}).destroy()
expect(spy.calledOnce).toBe(true)

emitted()

Wrapper vm によって生成されたカスタムイベントを含むオブジェクトを返します。

  • 戻り値: { [name: string]: Array<Array<any>> }

  • 例:

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

const wrapper = mount(Component)

wrapper.vm.$emit('foo')
wrapper.vm.$emit('foo', 123)

/*
wrapper.emitted() は次のオブジェクトを返します:
{
  foo: [[], [123]]
}
*/

// イベントが発行されたか検証します
expect(wrapper.emitted().foo).toBeTruthy()

// イベントの数を検証します
expect(wrapper.emitted().foo.length).toBe(2)

// イベントのペイロードを検証します
expect(wrapper.emitted().foo[1]).toBe([123])

別の構文があります。

// イベントが発行されたか検証します
expect(wrapper.emitted('foo')).toBeTruthy()

// イベントの数を検証します
expect(wrapper.emitted('foo').length).toBe(2)

// イベントのペイロードを検証します
expect(wrapper.emitted('foo')[1]).toEqual([123])

.emitted() メソッドは呼ばれる度、新しいオブジェクトではなく同じオブジェクトを返します。イベントが発生すると、そのオブジェクトは更新します。

const emitted = wrapper.emitted()

expect(emitted.foo.length).toBe(1)

// `wrapper` が foo イベントを emit する何らかの処理したとします。

expect(emitted.foo.length).toBe(2)

emittedByOrder()

Deprecation warning

emittedByOrder は非推奨となり、将来のリリースで削除される予定です。

代わりに wrapper.emitted を使用してください。

Wrapper vm によって生成されたカスタムイベントを含む配列を返します。

  • 戻り値: Array<{ name: string, args: Array<any> }>

  • 例:

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

const wrapper = mount(Component)

wrapper.vm.$emit('foo')
wrapper.vm.$emit('bar', 123)

/*
wrapper.emittedByOrder() は次の配列を返します
[
  { name: 'foo', args: [] },
  { name: 'bar', args: [123] }
]
*/

// イベントの発行順序を検証します
expect(wrapper.emittedByOrder().map(e => e.name)).toEqual(['foo', 'bar'])

exists()

WrapperWrapperArray が存在するか検証します。

WrapperWrapperArray が空だった場合は false を返します。

  • 戻り値: {boolean}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
expect(wrapper.exists()).toBe(true)
expect(wrapper.find('does-not-exist').exists()).toBe(false)
expect(wrapper.findAll('div').exists()).toBe(true)
expect(wrapper.findAll('does-not-exist').exists()).toBe(false)

find(selector)

Deprecation warning

コンポーネントの検索に find を使用することは非推奨となり、削除される予定です。代わりに findComponent を使用してください。

最初の DOM ノードの Wrapper、またはセレクタで一致した Vue コンポーネントを返します。

有効なセレクタを使用してください。

  • 引数:

    • {string|Component} selector
  • 戻り値: {Wrapper}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'
import Bar from './Bar.vue'

const wrapper = mount(Foo)

const div = wrapper.find('div')
expect(div.is('div')).toBe(true)

const bar = wrapper.find(Bar)
expect(bar.is(Bar)).toBe(true)

const barByName = wrapper.find({ name: 'bar' })
expect(barByName.is(Bar)).toBe(true)

const fooRef = wrapper.find({ ref: 'foo' })
expect(fooRef.is(Foo)).toBe(true)

findAll(selector)

Deprecation warning

findAll を使用してコンポーネントを検索することは非推奨となり、削除される予定です。代わりに findAllComponents を使用してください。

WrapperArrayを返します。

有効なセレクタを使用してください。

  • 引数:

    • {string|Component} selector
  • 戻り値: {WrapperArray}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'
import Bar from './Bar.vue'

const wrapper = mount(Foo)
const div = wrapper.findAll('div').at(0)
expect(div.is('div')).toBe(true)
const bar = wrapper.findAll(Bar).at(0)
expect(bar.is(Bar)).toBe(true)

findComponent

最初に一致した Vue コンポーネントの Wrapper を返します。

  • 引数:

    • {Component|ref|name} selector
  • 戻り値: {Wrapper}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'
import Bar from './Bar.vue'

const wrapper = mount(Foo)

const bar = wrapper.findComponent(Bar) // => コンポーネントインスタンスによってバーを検索します
expect(bar.exists()).toBe(true)
const barByName = wrapper.findComponent({ name: 'bar' }) // => `name` でバーを検索します
expect(barByName.exists()).toBe(true)
const barRef = wrapper.findComponent({ ref: 'bar' }) // => `ref` でバーを検索します
expect(barRef.exists()).toBe(true)

findAllComponents

一致するすべての Vue コンポーネントの WrapperArray を返します。

  • 引数:

    • {Component|ref|name} selector
  • 戻り値: {WrapperArray}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'
import Bar from './Bar.vue'

const wrapper = mount(Foo)
const bar = wrapper.findAllComponents(Bar).at(0)
expect(bar.exists()).toBeTruthy()
const bars = wrapper.findAllComponents(Bar)
expect(bar).toHaveLength(1)

html()

Wrapper DOM ノードの HTML を文字列として返します。

  • 戻り値: {string}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
expect(wrapper.html()).toBe('<div><p>Foo</p></div>')

is(selector)

Deprecation warning

is を使用して、 DOM ノードまたは vm がセレクタに一致することをアサートするのは非推奨となり、削除される予定です。

jest-dom で提供されているようなカスタムマッチャの使用を検討してください。または、 DOM 要素などに対するアサーションには、代わりにネイティブの Element.tagName を使用してください。

テストを維持するためには、以下の置き換えが有効です。

  • is('DOM_SELECTOR')wrapper.element.tagName のアサーションです。
  • is('ATTR_NAME') は真に wrapper.attributes('ATTR_NAME') のアサーションです。
  • is('CLASS_NAME') は真に wrapper.classes('CLASS_NAME') のアサーションです。

findComponent で使用する場合は、 findComponent(Comp).element で DOM 要素にアクセスします。

Wrapper DOM ノード、または vmセレクタと一致しているか検証します。

  • 引数:

    • {string|Component} selector
  • 戻り値: {boolean}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
expect(wrapper.is('div')).toBe(true)

isEmpty()

Wrapper が子ノードを含んでいないか検証します。

  • 戻り値: {boolean}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
expect(wrapper.isEmpty()).toBe(true)

isVisible()

Wrapper が表示されているかアサートします。

style が display: none か  visibility: hidden の親要素がある場合、 false を返します。

コンポーネントが v-show によって非表示になっているかアサートすることに使用することができます。

  • 戻り値: {boolean}

  • 例:

import { mount } from 'vue-test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
expect(wrapper.isVisible()).toBe(true)
expect(wrapper.find('.is-not-visible').isVisible()).toBe(false)

isVueInstance()

Deprecation warning

isVueInstance は非推奨となり、将来のリリースで削除される予定です。

isVueInstance アサーションに依存するテストは、ほとんどまたは全く価値を提供しません。それらを意図のあるアサーションに置き換えることをお勧めします。

テストを維持するために、isVueInstance() を置き換える場合は、 wrapper.find(...).vm のアサーションが有効です。

Wrapper が Vue インスタンスか検証します。

  • 戻り値: {boolean}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
expect(wrapper.isVueInstance()).toBe(true)

name()

Deprecation warning

name は非推奨となり、将来のリリースで削除される予定です。

Wrapper に Vue インスタンスが含まれている場合はコンポーネント名を返し、そうでない場合は Wrapper DOM ノードのタグ名を返します。

  • 戻り値: {string}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
expect(wrapper.name()).toBe('Foo')
const p = wrapper.find('p')
expect(p.name()).toBe('p')

props()

Wrappervm プロパティの props オブジェクトを返します。

Wrapper には Vue インスタンスを含む必要があることに注意してください

  • 戻り値: {[prop: string]: any}

  • 例:

import { mount } from '@vue/test-utils'
import { expect } from 'chai'
import Foo from './Foo.vue'

const wrapper = mount(Foo, {
  propsData: {
    bar: 'baz'
  }
})
expect(wrapper.props().bar).toBe('baz')

setChecked

Sets checked value for input element of type checkbox or radio and updates v-model bound data.

  • Arguments:

    • {Boolean} checked (default: true)
  • Example:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

test('setChecked demo', async () => {
  const wrapper = mount(Foo)
  const radioInput = wrapper.find('input[type="radio"]')

  await radioInput.setChecked()

  expect(radioInput.element.checked).toBeTruthy()
})
  • Note:

When you try to set the value to state via v-model by radioInput.element.checked = true; radioInput.trigger('input'), v-model is not triggered. v-model is triggered by change event.

checkboxInput.setChecked(checked) is an alias of the following code.

checkboxInput.element.checked = checked
checkboxInput.trigger('click')
checkboxInput.trigger('change')

setData(data)

Wrapper vm データを設定します。

setData は再帰的に Vue.set を実行することで動作します。

Wrapper には Vue インスタンスを含む必要があることに注意してください

  • 引数:

    • {Object} data
  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

test('setData demo', async () => {
  const wrapper = mount(Foo)

  await wrapper.setData({ foo: 'bar' })

  expect(wrapper.vm.foo).toBe('bar')
})

setMethods(methods)

Deprecation warning

setMethods は非推奨となり、将来のリリースで削除される予定です。

setMethods を置き換える明確な方法はありません。それは、置き換え前の使われ方に非常に依存しているためです。 setMethods は実装の詳細に依存する不安定なテストに簡単につながるため、お勧めしません

それらテストを見直すことをお勧めします。

複雑なメソッドをスタブするには、コンポーネントからメソッドを抽出し、単独でテストします。 メソッドが呼び出されたことをアサートするには、テストランナーを使用してそれを探ります。

Wrapper vm メソッドを設定し、更新を強制します。

Wrapper には Vue インスタンスを含む必要があることに注意してください

  • 引数:

    • {Object} methods
  • 例:

import { mount } from '@vue/test-utils'
import sinon from 'sinon'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
const clickMethodStub = sinon.stub()

wrapper.setMethods({ clickMethod: clickMethodStub })
wrapper.find('button').trigger('click')
expect(clickMethodStub.called).toBe(true)

setProps(props)

  • 引数:

    • {Object} props
  • 使用方法:

Wrapper vm プロパティを設定し更新を強制します。

Wrapper には Vue インスタンスを含む必要があることに注意してください

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

test('setProps demo', async () => {
  const wrapper = mount(Foo)

  await wrapper.setProps({ foo: 'bar' })

  expect(wrapper.vm.foo).toBe('bar')
})

渡された値で Vue インスタンス を初期化する propsData オブジェクトを渡すことができます。

// Foo.vue
export default {
  props: {
    foo: {
      type: String,
      required: true
    }
  }
}
import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo, {
  propsData: {
    foo: 'bar'
  }
})

expect(wrapper.vm.foo).toBe('bar')

setSelected

Selects an option element and updates v-model bound data.

  • Example:
import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

test('setSelected demo', async () => {
  const wrapper = mount(Foo)
  const options = wrapper.find('select').findAll('option')

  await options.at(1).setSelected()

  expect(wrapper.find('option:checked').element.value).toBe('bar')
})
  • Note:

When you try to set the value to state via v-model by option.element.selected = true; parentSelect.trigger('input'), v-model is not triggered. v-model is triggered by change event.

option.setSelected() is an alias of the following code.

option.element.selected = true
parentSelect.trigger('change')

setValue

Sets value of a text-control input or select element and updates v-model bound data.

  • Arguments:

    • {any} value
  • Example:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

test('setValue demo', async () => {
  const wrapper = mount(Foo)

  const textInput = wrapper.find('input[type="text"]')
  await textInput.setValue('some value')

  expect(wrapper.find('input[type="text"]').element.value).toBe('some value')

  const select = wrapper.find('select')
  await select.setValue('option value')

  expect(wrapper.find('select').element.value).toBe('option value')

  // requires <select multiple>
  const multiselect = wrapper.find('select')
  await multiselect.setValue(['value1', 'value3'])

  const selectedOptions = Array.from(multiselect.element.selectedOptions).map(
    o => o.value
  )
  expect(selectedOptions).toEqual(['value1', 'value3'])
})
  • Note:

    • textInput.setValue(value) is an alias of the following code.
    textInput.element.value = value
    textInput.trigger('input')
    
    • select.setValue(value) is an alias of the following code.
    select.element.value = value
    select.trigger('change')
    

text()

Wrapper のテキスト内容を返します。

  • 戻り値: {string}

  • 例:

import { mount } from '@vue/test-utils'
import Foo from './Foo.vue'

const wrapper = mount(Foo)
expect(wrapper.text()).toBe('bar')

trigger(eventType [, options ])

Wrapper DOM ノードのイベントを発火します。

Trigger は options オブジェクト形式で行います。options オブジェクトのプロパティがイベントに追加されます。

  • 引数:

    • {string} eventName 必須
    • {Object} options オプション
  • 例:

import { mount } from '@vue/test-utils'
import sinon from 'sinon'
import Foo from './Foo'

test('trigger demo', async () => {
  const clickHandler = sinon.stub()
  const wrapper = mount(Foo, {
    propsData: { clickHandler }
  })

  await wrapper.trigger('click')

  await wrapper.trigger('click', {
    button: 0
  })

  await wrapper.trigger('click', {
    ctrlKey: true
  })

  expect(clickHandler.called).toBe(true)
})
  • イベントターゲットの設定:

trigger は  Event オブジェクトを生成して、Wrapper.element にイベントを送ります。
Event オブジェクトの target 値を編集できません。つまり、 target を オプションオブジェクトにセットすることはできません。
target の属性を追加するには、 trigger を実行する前に Wrapper.element の属性にその値をセットする必要があります。

const input = wrapper.find('input')
input.element.value = 100
input.trigger('click')