You’re browsing the documentation for Vue Test Utils for Vue v2.x and earlier.

To read docs for Vue Test Utils for Vue 3, click here.

Wrapper

O Vue Test Utils (Utilitário de Teste da Vue) é uma API baseada em envolvedor.

Um Wrapper (envolvedor) é um objeto que contém um componente montado ou vnode (nó do vue) ou métodos para testar o componente ou vnode (nó do vue).

Propriedades

vm

Component (somente-leitura): Isto é a instância de Vue. Você pode acessar todos os métodos da instância e propriedades de um vm (modelo de vue) com o wrapper.vm. Isto só existe no envolvedor do componente de Vue ou no HTMLElement ligando o envolvedor do componente de Vue.

element

HTMLElement (somente-leitura): o nó raiz do DOM de um envolvedor

options

options.attachedToDocument

Boolean (read-only): true se o componente estiver ligado ao documento quando renderizado.

selector

Selector: o seletor que foi usado pelo find() ou pelo findAll() para criar este envolvedor

Métodos

O método attributes

Retorna o Wrapper (envolvedor) do objeto de atributo de um nó do DOM. Se a key for fornecida, o valor para o key será retornado.

  • Argumentos:

    • {string} key opcional
  • Retorna: {[attribute: string]: any} | string

  • Exemplo:

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

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

O método classes

Retorna o Wrapper de classes do nó do DOM.

Retorna um Array de nomes de classes ou um booleano se um nome de classe for fornecido.

  • Argumentos:

    • {string} className opcional
  • Retorna: Array<{string}> | boolean

  • Exemplo:

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

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

O método contains

Deprecation warning

O uso de contains está depreciado e será removido nos futuros lançamentos. Use o find para nós (nodes) do DOM (usando a sintaxe do querySelector), o findComponent para componentes, ou antes o wrapper.get.

Afirma que Wrapper contém um elemento ou componente que corresponde ao seletor.

  • Argumentos:

    • {string|Component} selector
  • Retorna: {boolean}

  • Exemplo:

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)

O método destroy

Destrói uma instância de componente de Vue.

  • Example:
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)

Se tanto a opção attachTo ou attachToDocument forem a causa do componente montar no documento, o componente de elementos do DOM também será removido do documento.

Para componentes funcionais, o destroy apenas remove os elementos do DOM renderizados do documento.

O método emitted

Retorna um objeto contento eventos personalizados emitidos pelo Wrapper vm.

  • Retorna: { [name: string]: Array<Array<any>> }

  • Exemplo:

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

test('emit demo', async () => {
  const wrapper = mount(Component)

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

  await wrapper.vm.$nextTick() // Espera até que $emits ter sido manipulado

  /*
  wrapper.emitted() retorna o seguinte objeto:
  {
    foo: [[], [123]]
  }
  */

  // afirma que o evento tem sido emitido
  expect(wrapper.emitted().foo).toBeTruthy()

  // afirma que o evento contabiliza
  expect(wrapper.emitted().foo.length).toBe(2)

  // afirma que evento carrega
  expect(wrapper.emitted().foo[1]).toEqual([123])
})

Você também pode escrever o que está acima como o seguinte:

// afirma que o evento tem sido emitido
expect(wrapper.emitted('foo')).toBeTruthy()

// afirma que o evento contabiliza
expect(wrapper.emitted('foo').length).toBe(2)

// afirma que evento carrega
expect(wrapper.emitted('foo')[1]).toEqual([123])

O método .emitted() retorna o mesmo objeto toda vez que ele for chamado, não um novo, e assim o objeto atualizará sempre que novos eventos forem disparados:

const emitted = wrapper.emitted()

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

// faça alguma coisa para fazer `wrapper` emitir o evento "foo"

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

O método emittedByOrder

Aviso de Depreciação

O emittedByOrder está depreciado e será removido nos futuros lançamentos.

Ao invés disso use o wrapper.emitted.

Retorna um objeto contento eventos personalizados emitidos pelo Wrapper (envolvedor) vm.

  • Retorna: Array<{ name: string, args: Array<any> }>

  • Exemplo:

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

const wrapper = mount(Component)

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

/*
wrapper.emittedByOrder() retorna o seguinte `Array`:
[
  { name: 'foo', args: [] },
  { name: 'bar', args: [123] }
]
*/

// afirma que o evento emite a ordem
expect(wrapper.emittedByOrder().map(e => e.name)).toEqual(['foo', 'bar'])

O método exists

Afirma que o Wrapper (envolvedor) existe.

Retorna false se chamando em um Wrapper o qual não existe.

  • Retorna: {boolean}

  • Exemplo:

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)

O método find

Aviso de Depreciação

O uso do find para procurar por um componente está depreciado e será removido. Ao invés disso use o findComponent. O método find continuará a funcionar para achar elementos usando qualquer seletor válido.

Retorna o Wrapper (envolvedor) do primeiro nó do DOM ou componente do Vue que corresponde ao seletor.

Use qualquer seletor de DOM válido (usa a sintaxe de querySelector).

  • Argumentos:

    • {string} selector
  • Retorna: {Wrapper}

  • Exemplo:

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.exists()).toBe(true)

const byId = wrapper.find('#bar')
expect(byId.element.id).toBe('bar')
  • Nota:

    • Você pode encadear juntas chamadas de find:
const button = wrapper.find({ ref: 'testButton' })
expect(button.find('.icon').exists()).toBe(true)

Consulte também: o get.

O método findAll

Aviso de Depreciação

O uso de findAll para pesquisar por componentes está depreciado e será removido. Ao invés disso use findAllComponents. O método findAll continuará a funcionar para achar elementos usando qualquer seletor válido.

Retorna um WrapperArray.

Usa qualquer seletor válido.

  • Argumentos:

    • {string|Component} selector
  • Retorna: {WrapperArray}

  • Exemplo:

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) // Uso depreciado
expect(bar.is(Bar)).toBe(true)

O método findComponent

Retorna o Wrapper (envolvedor) do primeiro componente de Vue correspondente.

  • Argumentos:

    • {Component|ref|string} selector
  • Retorna: {Wrapper}

  • Exemplo:

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) // => Encontra Bar pela instância do componente
expect(bar.exists()).toBe(true)
const barByName = wrapper.findComponent({ name: 'bar' }) // => encontra Bar pelo `name`
expect(barByName.exists()).toBe(true)
const barRef = wrapper.findComponent({ ref: 'bar' }) // => encontra Bar pelo `ref`
expect(barRef.exists()).toBe(true)

Uso com seletores de CSS

Usar findComponent com um seletor de CSS pode resultar em confusão de comportamento

Considere este exemplo:

const ChildComponent = {
  name: 'Child',
  template: '<div class="child"></div>'
}

const RootComponent = {
  name: 'Root',
  components: { ChildComponent },
  template: '<child-component class="root" />'
}

const wrapper = mount(RootComponent)

const rootByCss = wrapper.findComponent('.root') // => encontra o Root
expect(rootByCss.vm.$options.name).toBe('Root')
const childByCss = wrapper.findComponent('.child')
expect(childByCss.vm.$options.name).toBe('Root') // => continua sendo o Root

A razão para tal comportamento é que o RootComponent e o ChildComponent estão partilhando o mesmo nó do DOM e somente o primeiro componente correspondente é íncluido para cada nó do DOM único.

O método findAllComponents

Retorna um WrapperArray de todos componentes de Vue correspondentes.

  • Argumentos:

    • O selector usa qualquer seletor válido
  • Retorna: {WrapperArray}

  • Exemplo:

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(bars).toHaveLength(1)

Uso com seletores de CSS

Ao usar o findAllComponents com o seletor de CSS está sujeito as mesmas limitações do findComponent

O método html

Returns HTML of Wrapper DOM node as a string. Retorna o HTML do nó do DOM do Wrapper como uma sequência de caracteres (string).

  • Retorna: {string}

  • Exemplo:

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

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

O método get

Aviso de Depreciação

O uso do método get para pesquisar por um componente está depreciado e será removido. Use o getComponent para isso.

Funciona de forma similar ao find mas com a diferença de que lançará um erro se não encontrar nada que corresponda ao seletor dado. Você deve usar o find quando estiver procurando por um elemento que talvez não exista. Você deve usar o método get quando estiver buscando um elemento que deve existir e ele fornecerá um mensagem de erro agradável se não for o caso.

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

const wrapper = mount(Foo)

// similar ao `wrapper.find`.
// `get` lançará um erro se um elemento não for encontrado. O `find` não fará nada.
expect(wrapper.get('.does-exist'))

expect(() => wrapper.get('.does-not-exist'))
  .to.throw()
  .with.property(
    'message',
    'Unable to find .does-not-exist within: <div>the actual DOM here...</div>'
  )

O método is

Aviso de Depreciação

O uso do método is para afirmar que o envolvedor corresponde ao seletor de DOM está depreciado e será removido.

Para tal caso de uso considere um correspondente personalizado tal como aqueles fornecidos no jest-dom. ou ao invés disso use Element.tagName nativo para afirmação do tipo elemento de DOM.

Para manter estes testes, uma substituição válida para:

  • is('DOM_SELECTOR') é uma afirmação de wrapper.element.tagName.
  • is('ATTR_NAME') é uma afirmação de veracidade de wrapper.attributes('ATTR_NAME').
  • is('CLASS_NAME') é uma afirmação de veracidade de wrapper.classes('CLASS_NAME').

Afirmação contra definição do componente não está depreciada

Quando estiver usando com o findComponent, acesse o elemento do DOM com findComponent(Comp).element

Afirma que o nó do DOM do Wrapper (envolvedor) ou vm (modelo de vue) corresponde ao seletor.

  • Argumentos:

    • {string|Component} selector
  • Retorna: {boolean}

  • Exemplo:

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

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

O método isEmpty

Aviso de Depreciação

O método isEmpty está depreciado e será removido nos futuros lançamentos.

Considere um correspondente personalizado tais como aqueles fornecidos pelo jest-dom.

Quando estiver usando o findComponent, acesse o elemento do DOM com o findComponent(Comp).elment

Afiram que o Wrapper (envolvedor) não contém nó filho.

  • Retorna: {boolean}

  • Exemplo:

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

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

O método isVisible

Afirma que o Wrapper está visível.

Retorna false se um elemento ancestral que tem o estilo display: none, visibility: hidden, opacity: 0 está localizado dentro de uma tag <details> colapsada ou tem um atributo hidden.

Isto pode ser usado para afirmar que um componente está escondido por v-show.

  • Retorna: {boolean}

  • Exemplo:

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)

O método isVueInstance

Aviso de Depreciação

O método isVueInstance está depreciado e será removido nos futuros lançamentos.

Testes que dependem da afirmação do método isVueInstance fornecem pouco ou nenhum valor. Nós sugerimos substituir eles por afirmações resolutas.

Para manter esses testes, uma substituição válida para o método isVueInstance() é uma afirmação de veracidade (truthy) do wrapper.find(...).vm.

Afirma que o Wrapper é uma instância de Vue.

  • Retorna: {boolean}

  • Exemplo:

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

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

O método name

Aviso de Depreciação

O método name está depreciado e será removido nos futuros lançamentos. Consulte o vue-test-utils.vuejs.org/upgrading-to-v1/#name.

Retorna o nome do componente se o Wrapper (envolvedor) conter uma instância de Vue, ou nome da tag do nó do DOM do Wrapper se o Wrapper não conter uma instância de Vue.

  • Retorna: {string}

  • Exemplo:

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

O método props

Retorna o objeto de propriedades do Wrapper (envolvedor) do vm (modelo do vue). Se a key for fornecida, o valor para a key será retornado.

Nota que o Wrapper deve conter uma instância de Vue.

  • Argumentos:

    • {string} key opcional
  • Retorna: {[prop: string]: any} | any

  • Exemplo:

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

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

O método setChecked

Define o valor confirmado por um elemento input do tipo checkbox ou radio e atualiza o dado ligado ao v-model.

  • Argumentos:

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

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()
})
  • Nota:

Quando você tenta definir o valor para o estado via v-model pelo radioInput.element.checked = true; radioInput.trigger('input'), o v-model não é acionado. O v-model é acionado pelo evento change.

checkboxInput.setChecked(checked) é um apelido do seguinte código.

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

O método setData

Define os dados do vm (modelo do vue) do Wrapper (envolvedor).

O setData funciona através da chamada recursiva do Vue.set.

Nota que o Wrapper deve conter uma instância de Vue.

  • Argumentos:

    • {Object} data
  • Exemplo:

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

O método setMethods

Aviso de Depreciação

O método setMethods está depreciado e será removido nos futuros lançamentos.

Não há um caminho claro para substituir setMethods, porque ele depende muito da sua utilização prévia. Ele guia facilmente para testes escamosos que dependem da implementação de detalhes, o que é desencorajado.

Nós sugerimos que repense aqueles testes.

Para forjar um método complexo extraia ele do componente e teste ele em quarentena. Para afirmar que um método for chamado, use o seu executor de teste para vigiar ele.

Define os métodos do vm do Wrapper (envolvedor) e força a atualização.

Nota que o Wrapper deve conter uma instância de Vue.

  • Argumentos:

    • {Object} methods
  • Exemplo:

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)

O método setProps

  • Argumentos:

    • {Object} props
  • Uso:

Define as propriedades do vm (modelo do vue) do Wrapper (envolvedor) e força a atualização.

WARNING

O método setProps deve ser chamado apenas para o componente de alto-nível, montado pelo método mount ou shallowMount

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

Você pode também passar um objeto propsData, o qual inicializará a instância de Vue com os valores passados.

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

O método setSelected

Selects an option element and updates v-model bound data. Seleciona um elemento de opção e atualiza o dado ligado ao v-model.

  • Exemplo:
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')
})
  • Nota:

Quando você tenta definir o valor para o estado via v-model pelo option.element.selected = true; parentSelect.trigger('input'), o v-model não é acionado. O v-model é acionado pelo evento change.

O option.setSelected() é um apelido do seguinte código.

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

O método setValue

Define o valor de um controle de texo do elemento input ou do elemento select e atualiza o dado ligado ao v-model.

  • Argumentos:

    • {any} value
  • Exemplo:

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

  // exige o <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'])
})
  • Nota:

    • O textInput.setValue(value) é um apelido do seguinte código.
    textInput.element.value = value
    textInput.trigger('input')
    
    • O select.setValue(value) é um apelido do seguinte código.
    select.element.value = value
    select.trigger('change')
    

O método text

Retorna o conteúdo do texto do Wrapper (envolvedor).

  • Retorna: {string}

  • Exemplo:

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

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

O método trigger

Aciona uma evento assincronamente no nó do DOM do Wrapper (envolvedor).

O método trigger recebe um objeto options opcional. As propriedades dentro do objeto options são adicionadas ao evento. O método trigger retorna uma promessa (Promise), a qual quando resolvida, garante que o componente seja atualizado. O méotodo trigger apenas funciona com eventos nativos do DOM. Para emitir um evento personalizado, use o wrapper.vm.$emit('myCustomEvent')

  • Argumentos:

    • {string} eventType obrigatório
    • {Object} options opcional
  • Exemplo:

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 // Para testes de manipuladores de @click.ctrl
  })

  expect(clickHandler.called).toBe(true)
})

TIP

Quando estiver usando o trigger('focus') com o jsdom v16.4.0, então o acima você de usar a opção attachTo quando estiver montando o componente. Isto porque uma resolução de bug no jsdom v16.4.0 mudou o el.focus() para não fazer nada em elementos que estão disconectados do DOM.

  • Configurando um alvo do evento:

Nos bastidores, o método trigger cria um objeto Event e despacha o evento no elemento do Wrapper (envolvedor).

Não é possível editar o valor do target de um objeto Event, assim você não pode definir o target dentro do objeto options.

Para adicionar um atributo ao target, você precisa definir o valor do elemento do Wrapper (envolvedor) antes da chamada do método trigger. Você pode fazer isso com a propriedade element.

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