Wrapper

Vue Test Utils est une API basée sur un wrapper

Un wrapper est un objet qui contient un composant ou vnode monté et des méthodes pour tester le composant ou vnode

Découvrez l'objet Wrapper dans une leçon vidéo GRATUITE de Vue School

Propriétés

vm

Component(lecture seule): c'est l'instance Vue. Vous pouvez accéder à toutes les méthodes et propriétés de l'instance d'un vm avec un wrapper.vm. Ceci n'existe que pour le wrapper du composant Vue ou le wrapper du composant Vue liant les éléments HTMLE.

element

HTMLElement (lecture seule): le nœud DOM racine du wrapper

options

options.attachedToDocument

Boolean (lecture seule): true si le composant est joint au document lorsqu'il est rendu

selector

Selector: le sélecteur qui a été utilisé par find() ou findAll() pour créer cette enveloppe.

Méthodes

attributes

Renvoie l'objet attribut de nœud DOM Wrapper. Si la key est fournie, la valeur de la key sera renvoyée.

• Arguments:

  • {string} key facultatif

• Retours: {[attribute: string]: any} | string

• Example:

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

classes

Retourne les classes de nœuds DOM Wrapper.

Retourne un tableau de noms de classes ou un booléen si un nom de classe est fourni.

• Arguments:

  • {string} className facultatif

• Retours: Array<{string}> | boolean

• Exemple:

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)

contains

Avertissement de déprédation

L'utilisation de contains est déconseillée et sera supprimée dans les prochaines versions. Utilisez find pour les nœuds DOM (en utilisant la syntaxe querySelector), findComponent pour les composants, ou wrapper.get à la place.

Affirmer que le Wrapper contient un élément ou un composant correspondant selector.

• Arguments:

  • {string|Component} selector

• Retours: {boolean}

• Exemple:

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)

• Voir aussi : selectors

destroy

Détruit une instance du composant Vue.

• Exemple:

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)

si l'option attachTo ou attachToDocument a provoqué le montage du composant sur le document, les éléments du DOM du composant seront également supprimés du document.

Pour les composants fonctionnels, destroy ne supprime du document que les éléments DOM rendus.

emitted

Renvoie un objet contenant des événements personnalisés émis par le Wrapper vm.

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

• Exemple:

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() // Attendre que les $emits aient été traités

  /*
  wrapper.emitted() renvoie l'objet suivant :
  {
    foo: [[], [123]]
  }
  */

  // Affirmation de l'élément émis
  expect(wrapper.emitted().foo).toBeTruthy()

  // Affirmation du nombre d'élément
  expect(wrapper.emitted().foo.length).toBe(2)

  // Affirmation du paramètre additionnel
  expect(wrapper.emitted().foo[1]).toEqual([123])
})

Vous pouvez également écrire ce qui précède comme suit :

// Affirmation de l'élément émis
expect(wrapper.emitted('foo')).toBeTruthy()

// Affirmation du nombre d'élément
expect(wrapper.emitted('foo').length).toBe(2)

// Affirmation du paramètre additionnel
expect(wrapper.emitted('foo')[1]).toEqual([123])

La méthode .emitted() renvoie le même objet chaque fois qu'il est appelé, et non un nouveau, et donc l'objet se met à jour lorsque de nouveaux événements sont déclenchés :

const emitted = wrapper.emitted()

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

// Faire quelque chose pour que le "wrapper" émette l'événement "foo"

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

emittedByOrder

Avertissement de déprédation

Le terme emittedByOrder est obsolète et sera supprimé dans les prochaines versions.

Utilisez plutôt wrapper.emitted.

Retourne un tableau contenant des événements personnalisés émis par le Wrapper vm .

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

• Exemple:

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

const wrapper = mount(Component)

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

/*
wrapper.emittedByOrder() renvoie le tableau suivant :
[
  { name: 'foo', args: [] },
  { name: 'bar', args: [123] }
]
*/

// Faire valoir l'ordre d'émission d'événement
expect(wrapper.emittedByOrder().map(e => e.name)).toEqual(['foo', 'bar'])

exists

Affirmation de l'existence de wrapper.

Renvoie faux si on l'appelle sur un Wrapper vide.

• Retours: {boolean}

• Exemple:

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

Avertissement de déprédation

L'utilisation de find pour rechercher un composant est déconseillée et sera supprimée. Utilisez plutôt findComponent. La méthode find continuera à fonctionner pour trouver des éléments en utilisant n'importe quel [selector] valide (../selectors.md).

Retourne le "wrapper" du premier nœud DOM ou le sélecteur de composants Vue correspondant.

Utilisez n'importe quel sélecteur DOM valide (utilise la syntaxe querySelector).

• Arguments:

  • {string} selector

• Retours: {Wrapper}

• Exemple:

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

• Note:

  • Vous pouvez enchaîner les appels find ensemble :

const button = wrapper.find({ ref: 'testButton' })
expect(button.find('.icon').exists()).toBe(true)

Voir aussi : get.

findAll

Avertissement de déprédation

L'utilisation de findAll pour rechercher des composants est obsolète et sera supprimée. Utilisez plutôt findAllComponents. La méthode findAll continuera à fonctionner pour trouver des éléments en utilisant n'importe quel [sélecteur] valide (../selectors.md).

Retourne un WrapperArray.

Utilisez n'importe quel selector valide.

• Arguments:

  • {string|Component} selector

• Retours: {WrapperArray}

• Exemple:

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) // Utilisation dépréciée
expect(bar.is(Bar)).toBe(true)

findComponent

Retourne le wrapper du premier composant Vue correspondant.

• Arguments:

  • {Component|ref|name} selector

• Retours: {Wrapper}

• Exemple:

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) // => trouve Bar par instance de composant
expect(bar.exists()).toBe(true)
const barByName = wrapper.findComponent({ name: 'bar' }) // => trouve Bar par `name`
expect(barByName.exists()).toBe(true)
const barRef = wrapper.findComponent({ ref: 'bar' }) // => trouve Bar par `ref`
expect(barRef.exists()).toBe(true)

findAllComponents

Retourne un WrapperArray de tous les composants Vue correspondants.

• Arguments:

  • {Component|ref|name} selector

• Retours: {WrapperArray}

• Exemple:

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

Renvoie le HTML du nœud DOM Wrapper sous forme de chaîne.

• Retours: {string}

• Exemple:

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

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

get

Avertissement de déprédation

L'utilisation de get pour rechercher un Composant est dépréciée et sera supprimée. Utilisez plutôt getComponent

Fonctionne exactement comme find, mais lance une erreur si aucun élément correspondant au sélecteur donné n'est trouvé. Vous devez utiliser find lorsque vous recherchez un élément qui peut ne pas exister. Vous devez utiliser cette méthode lorsque vous obtenez un élément qui devrait exister et elle fournira un beau message d'erreur si ce n'est pas le cas.

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

const wrapper = mount(Foo)

// Similaire à `wrapper.find`.
// `get` lancera une erreur si un élément n'est pas trouvé. `find` ne fera rien.
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>'
  )

is

Avertissement de déprédation

L'utilisation de is pour affirmer que le nœud DOM est déprécié et sera supprimé.

Considérez un appariement personnalisé tel que ceux fournis dans jest-dom. ou pour l'assertion de type d'élément DOM, utilisez native Element.tagName à la place.

Pour conserver ces tests, un remplacement valable pour :

• is('DOM_SELECTOR') est une affirmation de wrapper.element.tagName.
• is('ATTR_NAME') est une affirmation véridique d wrapper.attributes('ATTR_NAME').
• is('CLASS_NAME') est une affirmation véridique d wrapper.classes('CLASS_NAME').

L'affirmation contre la définition du composant n'est pas dépréciée

En cas d'utilisation avec findComponent, accédez à l'élément DOM avec findComponent(Comp).element

Affirmer Wrapper le noeud DOM ou vm correspond. selector.

• Arguments:

  • {string|Component} selector

• Retours: {boolean}

• Exemple:

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

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

isEmpty

Avertissement de déprédation

isEmpty est déprécié et sera supprimé dans les prochaines versions.

Considérez un appariement personnalisé tel que ceux fournis dans jest-dom.

En cas d'utilisation avec findComponent, accédez à l'élément DOM avec findComponent(Comp).element

Affirmer que Wrapper ne contient pas de nœud enfant.

• Retours: {boolean}

• Exemple:

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

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

isVisible

Affirmer que Wrapper est visible.

Retourne false si un élément parent a le style display: none ou visibility: hidden, est situé à l'intérieur de la balise <details> fermée ou possède un attribut caché.

Ceci peut être utilisé pour affirmer qu'un élément est caché par v-show.

• Retours: {boolean}

• Exemple:

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

Avertissement de déprédation

isVueInstance est dépréciée et sera supprimée dans les prochaines versions.

Les tests reposant sur l'affirmation isVueInstance n'ont que peu ou pas de valeur. Nous suggérons de les remplacer par des assertions ciblées.

Pour conserver ces tests, un remplacement valable de isVueInstance() est une assertion véridique de wrapper.find(...).vm.

L'assertion Wrapper est l'instance de Vue.

• Retours: {boolean}

• Exemple:

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

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

name

Avertissement de déprédation

name est dépréciée et sera supprimée dans les prochaines versions.

Retourne le nom du composant si Wrapper contient une instance de Vue, ou le nom du tag du nœud DOM Wrapper si Wrapper ne contient pas d'instance de Vue.

• Retours: {string}

• Exemple:

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

Retourne l'objet props Wrapper vm. Si key est fourni, la valeur pour key sera retournée.

Note : le Wrapper doit contenir une instance de Vue.

• Arguments:

  • {string} key facultatif

• Retours: {[prop: string]: any} | any

• Exemple:

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

setChecked

Définis la valeur cochée pour l'élément d'entrée de type case à cocher ou radio et met à jour les données liées au v-model.

• Arguments:

  • {Boolean} checked (default: true)

• Exemple:

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

const wrapper = mount(Foo)
const radioInput = wrapper.find('input[type="radio"]')
radioInput.setChecked()

• Note:

Lorsque vous essayez de mettre la valeur à l'état via v-model par radioInput.element.checked = true ; radioInput.trigger('input'), v-model n'est pas déclenché. Le v-model est déclenché par l'événement change.

checkboxInput.setChecked(checked) est un alias du code suivant.

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

setData

Définis les données Wrapper vm.

setData fonctionne en appelant récursivement Vue.set.

Note - le Wrapper doit contenir une instance de Vue.

• Arguments:

  • {Object} data

• Exemple:

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

const wrapper = mount(Foo)
wrapper.setData({ foo: 'bar' })
expect(wrapper.vm.foo).toBe('bar')

setMethods

Avertissement de déprédation

setMethods est dépréciée et sera supprimée dans les prochaines versions.

Il n'y a pas de voie claire pour remplacer les setMethods, car cela dépend vraiment de votre utilisation précédente. Cela conduit facilement à des tests bancals qui s'appuient sur des détails d'implémentation, ce qui est déconseillé

Nous suggérons de repenser ces tests.

Pour mettre au point une méthode complexe, il faut l'extraire du composant et le tester de manière isolée. Pour affirmer qu'une méthode est appelée, utilisez votre testeur pour l'espionner.

Définis les méthodes Wrapper vm et les met à jour.

Note le Wrapper doit contenir une instance de Vue.

• Arguments:

  • {Object} methods

• Exemple:

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

• Arguments:

  • {Object} props

• Usage:

Définir les props de Wrapper vm et forcer à mettre à jour

::: avertissement setProps ne peut être appelé que pour un composant de haut niveau, monté par 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')
})

Vous pouvez également passer un objet propsData, qui initialisera l'instance de Vue avec les valeurs passées.

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

Sélectionne un élément d'option et met à jour les données liées au v-model.

• Exemple:

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

const wrapper = mount(Foo)
const options = wrapper.find('select').findAll('option')

options.at(1).setSelected()

• Note:

Lorsque vous essayez de mettre la valeur à l'état via v-model par option.element.selected = true ; parentSelect.trigger('input'), v-model n'est pas déclenché. Le v-model est déclenché par l'événement change.

option.setSelected() est un alias du code suivant.

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

setValue

Définis la valeur d'une entrée de contrôle de texte ou d'un élément de sélection et met à jour les données liées au v-model.

• Arguments:

  • {any} value

• Exemple:

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

const wrapper = mount(Foo)

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

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

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

• Note:

• textInput.setValue(value) est un alias du code suivant.

  textInput.element.value = value
  textInput.trigger('input')
  

  • select.setValue(value) est un alias du code suivant.

  select.element.value = value
  select.trigger('change')
  

text

Renvoie le contenu textuel de Wrapper.

• Retours: {string}

• Exemple:

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

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

trigger

Déclenche un événement de manière asynchrone sur le nœud DOM de l'Wrapper.

Le trigger prend un objet options optionnel. Les propriétés de l'objet options sont ajoutées à l'événement. Le trigger renvoie une Promesse, qui une fois résolue, garantit la mise à jour du composant. Le trigger ne fonctionne qu'avec les événements DOM natifs. Pour émettre un événement personnalisé, utilisez wrapper.vm.$emit('myCustomEvent')

• Arguments:

  • {string} eventType requis
  • {Object} options facultatif

• Exemple:

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 // For testing @click.ctrl handlers
  })

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

• Définir l'objectif de l'événement :

Sous le capot, trigger cré un objet Event et envoie l'événement sur l'élément Wrapper.

Il n'est pas possible de modifier la valeur target d'un objet Event, donc vous pouvez pas définir la target dans l'objet options.

Pour ajouter un attribut à la target, vous devez définir la valeur de l'élément Wrapper avant d’appeler le trigger. Vous pouvez le faire avec la propriété element.

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