Aller au contenu principal

Expect

Lorsque vous écrivez des tests, vous avez souvent besoin de vérifier que les valeurs remplissent certaines conditions. expect vous donne accès à un certain nombre de "matchers" qui vous permettent de valider différentes choses sur l'objet browser, un objet element ou mock.

Options par défaut​

Ces options par défaut ci-dessous sont liées aux options waitforTimeout et waitforInterval définies dans la configuration.

Ne définissez les options ci-dessous que si vous souhaitez attendre des délais spécifiques pour vos assertions.

{
wait: 2000, // ms d'attente pour que l'expectative réussisse
interval: 100, // intervalle entre les tentatives
}

Si vous souhaitez choisir des délais et des intervalles différents, définissez ces options comme ceci :

// wdio.conf.js
import { setOptions } from 'expect-webdriverio'

export const config = {
// ...
before () {
setOptions({ wait: 5000 })
},
// ...
}

Options de Matcher​

Chaque matcher peut prendre plusieurs options qui vous permettent de modifier l'assertion :

Options de commande​
NomTypeDétails
waitnumbertemps en ms d'attente pour que l'expectative réussisse. Par défaut : 3000
intervalnumberintervalle entre les tentatives. Par défaut : 100
beforeAssertionfunctionfonction à appeler avant que l'assertion ne soit faite
afterAssertionfunctionfonction à appeler après que l'assertion soit faite contenant les résultats de l'assertion
messagestringmessage utilisateur à ajouter avant l'erreur d'assertion
Options de chaîne​

Cette option peut être appliquée en plus des options de commande lorsque des chaînes sont en cours d'assertion.

NomTypeDétails
ignoreCasebooleanappliquer toLowerCase aux valeurs réelles et attendues
trimbooleanappliquer trim à la valeur réelle
replaceReplacer | Replacer[]remplacer des parties de la valeur réelle qui correspondent à la chaîne/RegExp. Le remplaçant peut être une chaîne ou une fonction.
containingbooleans'attend à ce que la valeur réelle contienne la valeur attendue, sinon égalité stricte.
asStringbooleanpeut être utile pour forcer la conversion de la valeur de propriété en chaîne
atStartbooleans'attend à ce que la valeur réelle commence par la valeur attendue
atEndbooleans'attend à ce que la valeur réelle se termine par la valeur attendue
atIndexnumbers'attend à ce que la valeur réelle ait la valeur attendue à l'index donné
Options numériques​

Cette option peut être appliquée en plus des options de commande lorsque des nombres sont en cours d'assertion.

NomTypeDétails
eqnumberégal
ltenumberinférieur ou égal
gtenumbersupérieur ou égal

Gestion des entités HTML​

Une entité HTML est un morceau de texte ("chaîne") qui commence par une esperluette (&) et se termine par un point-virgule (;). Les entités sont fréquemment utilisées pour afficher des caractères réservés (qui seraient autrement interprétés comme du code HTML), et des caractères invisibles (comme les espaces insécables, par exemple  ).

Pour trouver ou interagir avec un tel élément, utilisez l'équivalent unicode de l'entité. par exemple :

<div data="Some&nbsp;Value">Some&nbsp;Text</div>
const myElem = await $('div[data="Some\u00a0Value"]')
await expect(myElem).toHaveAttribute('data', 'div[Some\u00a0Value')
await expect(myElem).toHaveText('Some\u00a0Text')

Vous pouvez trouver toutes les références unicode dans la spécification HTML.

Remarque : unicode n'est pas sensible à la casse, donc \u00a0 et \u00A0 fonctionnent tous les deux. Pour trouver un élément dans l'inspecteur du navigateur, supprimez u de l'unicode, par exemple : div[data="Some\00a0Value"]

Matchers de navigateur​

toHaveUrl​

Vérifie si le navigateur est sur une page spécifique.

Utilisation​
await browser.url('https://webdriver.io/')
await expect(browser).toHaveUrl('https://webdriver.io')
Utilisation​
await browser.url('https://webdriver.io/')
await expect(browser).toHaveUrl(expect.stringContaining('webdriver'))

toHaveTitle​

Vérifie si le site web a un titre spécifique.

Utilisation​
await browser.url('https://webdriver.io/')
await expect(browser).toHaveTitle('WebdriverIO · Next-gen browser and mobile automation test framework for Node.js')
await expect(browser).toHaveTitle(expect.stringContaining('WebdriverIO'))

toHaveClipboardText​

Vérifie si le navigateur a un texte spécifique stocké dans son presse-papiers.

Utilisation​
import { Key } from 'webdriverio'

await browser.keys([Key.Ctrl, 'a'])
await browser.keys([Key.Ctrl, 'c'])
await expect(browser).toHaveClipboardText('some clipboard text')
await expect(browser).toHaveClipboardText(expect.stringContaining('clipboard text'))

Matchers d'éléments​

toBeDisplayed​

Appelle isDisplayed sur l'élément donné.

Utilisation​
const elem = await $('#someElem')
await expect(elem).toBeDisplayed()

toExist​

Appelle isExisting sur l'élément donné.

Utilisation​
const elem = await $('#someElem')
await expect(elem).toExist()

toBePresent​

Identique à toExist.

Utilisation​
const elem = await $('#someElem')
await expect(elem).toBePresent()

toBeExisting​

Identique à toExist.

Utilisation​
const elem = await $('#someElem')
await expect(elem).toBeExisting()

toBeFocused​

Vérifie si l'élément a le focus. Cette assertion ne fonctionne que dans un contexte web.

Utilisation​
const elem = await $('#someElem')
await expect(elem).toBeFocused()

toHaveAttribute​

Vérifie si un élément a un certain attribut avec une valeur spécifique.

Utilisation​
const myInput = await $('input')
await expect(myInput).toHaveAttribute('class', 'form-control')
await expect(myInput).toHaveAttribute('class', expect.stringContaining('control'))

toHaveAttr​

Identique à toHaveAttribute.

Utilisation​
const myInput = await $('input')
await expect(myInput).toHaveAttr('class', 'form-control')
await expect(myInput).toHaveAttr('class', expect.stringContaining('control'))

toHaveElementClass​

Vérifie si un élément a un nom de classe unique. Peut également être appelé avec un tableau en paramètre lorsque l'élément peut avoir plusieurs noms de classe.

Utilisation​
const myInput = await $('input')
await expect(myInput).toHaveElementClass('form-control', { message: 'Not a form control!' })
await expect(myInput).toHaveElementClass(['form-control' , 'w-full'], { message: 'not full width' })
await expect(myInput).toHaveElementClass(expect.stringContaining('form'), { message: 'Not a form control!' })

toHaveElementProperty​

Vérifie si un élément a une certaine propriété.

Utilisation​
const elem = await $('#elem')
await expect(elem).toHaveElementProperty('height', 23)
await expect(elem).not.toHaveElementProperty('height', 0)

toHaveValue​

Vérifie si un élément d'entrée a une certaine valeur.

Utilisation​
const myInput = await $('input')
await expect(myInput).toHaveValue('admin-user', { ignoreCase: true })
await expect(myInput).toHaveValue(expect.stringContaining('user'), { ignoreCase: true })

toBeClickable​

Vérifie si un élément peut être cliqué en appelant isClickable sur l'élément.

Utilisation​
const elem = await $('#elem')
await expect(elem).toBeClickable()

toBeDisabled​

Vérifie si un élément est désactivé en appelant isEnabled sur l'élément.

Utilisation​
const elem = await $('#elem')
await expect(elem).toBeDisabled()
// équivalent à
await expect(elem).not.toBeEnabled()

toBeEnabled​

Vérifie si un élément est activé en appelant isEnabled sur l'élément.

Utilisation​
const elem = await $('#elem')
await expect(elem).toBeEnabled()
// équivalent à
await expect(elem).not.toBeDisabled()

toBeSelected​

Vérifie si un élément est activé en appelant isSelected sur l'élément.

Utilisation​
const elem = await $('#elem')
await expect(elem).toBeSelected()

toBeChecked​

Identique à toBeSelected.

Utilisation​
const elem = await $('#elem')
await expect(elem).toBeChecked()

toHaveComputedLabel​

Vérifie si l'élément a une étiquette WAI-ARIA calculée spécifique. Peut également être appelé avec un tableau en paramètre dans le cas où l'élément peut avoir différentes étiquettes.

Utilisation​
await browser.url('https://webdriver.io/')
const elem = await $('a[href="https://github.com/webdriverio/webdriverio"]')
await expect(elem).toHaveComputedLabel('GitHub repository')
await expect(elem).toHaveComputedLabel(expect.stringContaining('repository'))
Utilisation​
await browser.url('https://webdriver.io/')
const elem = await $('a[href="https://github.com/webdriverio/webdriverio"]')
await expect(elem).toHaveComputedLabel(['GitHub repository', 'Private repository'])
await expect(elem).toHaveComputedLabel([expect.stringContaining('GitHub'), expect.stringContaining('Private')])

toHaveComputedRole​

Vérifie si l'élément a un rôle WAI-ARIA calculé spécifique. Peut également être appelé avec un tableau en paramètre dans le cas où l'élément peut avoir différentes étiquettes.

Utilisation​
await browser.url('https://webdriver.io/')
const elem = await $('[aria-label="Skip to main content"]')
await expect(elem).toHaveComputedRole('region')
await expect(elem).toHaveComputedRole(expect.stringContaining('ion'))
Utilisation​
await browser.url('https://webdriver.io/')
const elem = await $('[aria-label="Skip to main content"]')
await expect(elem).toHaveComputedRole(['region', 'section'])
await expect(elem).toHaveComputedRole([expect.stringContaining('reg'), expect.stringContaining('sec')])

toHaveHref​

Vérifie si l'élément de lien a une cible de lien spécifique.

Utilisation​
const link = await $('a')
await expect(link).toHaveHref('https://webdriver.io')
await expect(link).toHaveHref(expect.stringContaining('webdriver.io'))

Identique à toHaveHref.

Utilisation​
const link = await $('a')
await expect(link).toHaveLink('https://webdriver.io')
await expect(link).toHaveLink(expect.stringContaining('webdriver.io'))

toHaveId​

Vérifie si l'élément a un attribut id spécifique.

Utilisation​
const elem = await $('#elem')
await expect(elem).toHaveId('elem')

toHaveText​

Vérifie si l'élément a un texte spécifique. Peut également être appelé avec un tableau en paramètre dans le cas où l'élément peut avoir différents textes.

Utilisation​
await browser.url('https://webdriver.io/')
const elem = await $('.container')
await expect(elem).toHaveText('Next-gen browser and mobile automation test framework for Node.js')
await expect(elem).toHaveText(expect.stringContaining('test framework for Node.js'))
await expect(elem).toHaveText(['Next-gen browser and mobile automation test framework for Node.js', 'Get Started'])
await expect(elem).toHaveText([expect.stringContaining('test framework for Node.js'), expect.stringContaining('Started')])

Dans le cas où il y a une liste d'éléments dans la div ci-dessous :

<ul>
<li>Coffee</li>
<li>Tea</li>
<li>Milk</li>
</ul>

Vous pouvez les affirmer en utilisant un tableau :

const elem = await $$('ul > li')
await expect(elem).toHaveText(['Coffee', 'Tea', 'Milk'])

toHaveHTML​

Vérifie si l'élément a un texte spécifique. Peut également être appelé avec un tableau en paramètre dans le cas où l'élément peut avoir différents textes.

Utilisation​
await browser.url('https://webdriver.io/')
const elem = await $('.hero__subtitle')
await expect(elem).toHaveHTML('<p class="hero__subtitle">Next-gen browser and mobile automation test framework for Node.js</p>')
await expect(elem).toHaveHTML(expect.stringContaining('Next-gen browser and mobile automation test framework for Node.js'))
await expect(elem).toHaveHTML('Next-gen browser and mobile automation test framework for Node.js', { includeSelectorTag: false })
Utilisation​
await browser.url('https://webdriver.io/')
const elem = await $('.hero__subtitle')
await expect(elem).toHaveHTML(['Next-gen browser and mobile automation test framework for Node.js', 'Get Started'], { includeSelectorTag: false })
await expect(elem).toHaveHTML([expect.stringContaining('automation test framework for Node.js'), expect.stringContaining('Started')], { includeSelectorTag: false })

toBeDisplayedInViewport​

Vérifie si un élément est dans la fenêtre d'affichage en appelant isDisplayedInViewport sur l'élément.

Utilisation​
const elem = await $('#elem')
await expect(elem).toBeDisplayedInViewport()

toHaveChildren​

Vérifie le nombre d'enfants de l'élément récupéré en appelant la commande element.$('./*').

Utilisation​
const list = await $('ul')
await expect(list).toHaveChildren() // la liste a au moins un élément
// équivalent à
await expect(list).toHaveChildren({ gte: 1 })

await expect(list).toHaveChildren(3) // la liste a 3 éléments
// équivalent à
await expect(list).toHaveChildren({ eq: 3 })

toHaveWidth​

Vérifie si l'élément a une largeur spécifique.

Utilisation​
await browser.url('http://github.com')
const logo = await $('.octicon-mark-github')
await expect(logo).toHaveWidth(32)

toHaveHeight​

Vérifie si l'élément a une hauteur spécifique.

Utilisation​
await browser.url('http://github.com')
const logo = await $('.octicon-mark-github')
await expect(logo).toHaveHeight(32)

toHaveSize​

Vérifie si l'élément a une taille spécifique.

Utilisation​
await browser.url('http://github.com')
const logo = await $('.octicon-mark-github')
await expect(logo).toHaveSize({ width: 32, height: 32 })

toBeElementsArrayOfSize​

Vérifie le nombre d'éléments récupérés en utilisant la commande $$.

Remarque : Ce matcher mettra à jour le tableau passé avec les derniers éléments si l'assertion réussit. Cependant, si vous avez réaffecté la variable, vous devrez récupérer à nouveau les éléments.

Utilisation​
const listItems = await $$('ul>li')
await expect(listItems).toBeElementsArrayOfSize(5) // 5 éléments dans la liste

await expect(listItems).toBeElementsArrayOfSize({ lte: 10 })
// équivalent à
assert.ok(listItems.length <= 10)

Matchers de réseau​

toBeRequested​

Vérifie que le mock a été appelé

Utilisation​
const mock = browser.mock('**/api/todo*')
await expect(mock).toBeRequested()

toBeRequestedTimes​

Vérifie que le mock a été appelé le nombre de fois attendu

Utilisation​
const mock = browser.mock('**/api/todo*')
await expect(mock).toBeRequestedTimes(2) // await expect(mock).toBeRequestedTimes({ eq: 2 })

await expect(mock).toBeRequestedTimes({ gte: 5, lte: 10 }) // requête appelée au moins 5 fois mais moins de 11

toBeRequestedWith​

Vérifie que le mock a été appelé selon les options attendues.

La plupart des options prennent en charge les matchers partiels expect/jasmine comme expect.objectContaining

Utilisation​
const mock = browser.mock('**/api/todo*', { method: 'POST' })

await expect(mock).toBeRequestedWith({
url: 'http://localhost:8080/api/todo', // [optionnel] string | function | custom matcher
method: 'POST', // [optionnel] string | array
statusCode: 200, // [optionnel] number | array
requestHeaders: { Authorization: 'foo' }, // [optionnel] object | function | custom matcher
responseHeaders: { Authorization: 'bar' }, // [optionnel] object | function | custom matcher
postData: { title: 'foo', description: 'bar' }, // [optionnel] object | function | custom matcher
response: { success: true }, // [optionnel] object | function | custom matcher
})

await expect(mock).toBeRequestedWith({
url: expect.stringMatching(/.*\/api\/.*/i),
method: ['POST', 'PUT'], // soit POST ou PUT
statusCode: [401, 403], // soit 401 ou 403
requestHeaders: headers => headers.Authorization.startsWith('Bearer '),
postData: expect.objectContaining({ released: true, title: expect.stringContaining('foobar') }),
response: r => Array.isArray(r) && r.data.items.length === 20
})

Matcher de snapshot​

WebdriverIO prend en charge les tests de snapshot de base ainsi que les tests de snapshot DOM.

toMatchSnapshot​

Vérifie si un objet arbitraire correspond à une certaine valeur. Si vous passez un WebdriverIO.Element, il prendra automatiquement un snapshot de son état outerHTML.

Utilisation​
// snapshot d'objets arbitraires (pas besoin de "await" ici)
expect({ foo: 'bar' }).toMatchSnapshot()
// snapshot de `outerHTML` de WebdriverIO.Element (snapshot DOM, nécessite "await")
await expect($('elem')).toMatchSnapshot()
// snapshot du résultat de la commande d'élément
await expect($('elem').getCSSProperty('background-color')).toMatchSnapshot()

toMatchInlineSnapshot​

De même, vous pouvez utiliser toMatchInlineSnapshot() pour stocker le snapshot en ligne dans le fichier de test. Par exemple, étant donné :

await expect($('img')).toMatchInlineSnapshot()

Au lieu de créer un fichier de snapshot, WebdriverIO modifiera directement le fichier de test pour mettre à jour le snapshot en tant que chaîne :

await expect($('img')).toMatchInlineSnapshot(`"<img src="/public/apple-touch-icon-precomposed.png">"`)

Matchers de snapshot visuel​

Les matchers suivants sont implémentés dans le cadre du plugin @wdio/visual-service et ne sont disponibles que lorsque le service est configuré. Assurez-vous de suivre les instructions de configuration en conséquence.

toMatchElementSnapshot​

Vérifie si l'élément donné correspond au snapshot de référence.

Utilisation​
await expect($('.hero__title-logo')).toMatchElementSnapshot('wdioLogo', 0, {
// options
})

Le résultat attendu est par défaut 0, donc vous pouvez écrire la même assertion comme :

await expect($('.hero__title-logo')).toMatchElementSnapshot('wdioLogo', {
// options
})

ou ne pas passer d'options du tout :

await expect($('.hero__title-logo')).toMatchElementSnapshot()

toMatchScreenSnapshot​

Vérifie si l'écran actuel correspond au snapshot de référence.

Utilisation​
await expect(browser).toMatchScreenSnapshot('partialPage', 0, {
// options
})

Le résultat attendu est par défaut 0, donc vous pouvez écrire la même assertion comme :

await expect(browser).toMatchScreenSnapshot('partialPage', {
// options
})

ou ne pas passer d'options du tout :

await expect(browser).toMatchScreenSnapshot('partialPage')

toMatchFullPageSnapshot​

Vérifie si la capture d'écran de la page entière correspond au snapshot de référence.

Utilisation​
await expect(browser).toMatchFullPageSnapshot('fullPage', 0, {
// options
})

Le résultat attendu est par défaut 0, donc vous pouvez écrire la même assertion comme :

await expect(browser).toMatchFullPageSnapshot('fullPage', {
// options
})

ou ne pas passer d'options du tout :

await expect(browser).toMatchFullPageSnapshot('fullPage')

toMatchTabbablePageSnapshot​

Vérifie si la capture d'écran de la page entière incluant les marques d'onglets correspond au snapshot de référence.

Utilisation​
await expect(browser).toMatchTabbablePageSnapshot('tabbable', 0, {
// options
})

Le résultat attendu est par défaut 0, donc vous pouvez écrire la même assertion comme :

await expect(browser).toMatchTabbablePageSnapshot('tabbable', {
// options
})

ou ne pas passer d'options du tout :

await expect(browser).toMatchTabbablePageSnapshot('tabbable')

Utilisation des expressions régulières​

Vous pouvez également utiliser directement des expressions régulières pour tous les matchers qui font une comparaison de texte.

Utilisation​
await browser.url('https://webdriver.io/')
const elem = await $('.container')
await expect(elem).toHaveText(/node\.js/i)
await expect(elem).toHaveText([/node\.js/i, 'Get Started'])
await expect(browser).toHaveTitle(/webdriverio/i)
await expect(browser).toHaveUrl(/webdriver\.io/)
await expect(elem).toHaveElementClass(/Container/i)

Matchers par défaut​

En plus des matchers expect-webdriverio, vous pouvez utiliser les assertions intégrées expect de Jest ou expect/expectAsync pour Jasmine.

Matchers asymétriques​

WebdriverIO prend en charge l'utilisation de matchers asymétriques partout où vous comparez des valeurs textuelles, par exemple :

await expect(browser).toHaveTitle(expect.stringContaining('some title'))

ou

await expect(browser).toHaveTitle(expect.not.stringContaining('some title'))

TypeScript​

Si vous utilisez le Testrunner WDIO, tout sera automatiquement configuré. Suivez simplement le guide de configuration de la documentation. Cependant, si vous exécutez WebdriverIO avec un autre testrunner ou dans un simple script Node.js, vous devrez ajouter expect-webdriverio à types dans le tsconfig.json.

  • "expect-webdriverio" pour tout le monde sauf les utilisateurs de Jasmine/Jest.
  • "expect-webdriverio/jasmine" pour Jasmine
  • "expect-webdriverio/jest" pour Jest

JavaScript (VSCode)​

Il est nécessaire de créer jsconfig.json à la racine du projet et de faire référence aux définitions de types pour que l'autocomplétion fonctionne en javascript vanilla.

{
"include": [
"**/*.js",
"**/*.json",
"node_modules/expect-webdriverio"
]
}

Ajouter vos propres matchers​

Similaire à la façon dont expect-webdriverio étend les matchers Jasmine/Jest, il est possible d'ajouter des matchers personnalisés.

Les matchers personnalisés doivent être ajoutés dans le hook before de wdio

// wdio.conf.js
{
async before () {
const { addCustomMatchers } = await import('./myMatchers')
addCustomMatchers()
}
}
// myMatchers.js - Exemple Jest
export function addCustomMatchers () {
if (global.expect.expect !== undefined) { // Solution temporaire. Voir https://github.com/webdriverio/expect-webdriverio/issues/835
global.expect = global.expect.expect;
}

expect.extend({
myMatcher (actual, expected) {
return { pass: actual === expected, message: () => 'some message' }
}
})
}

Welcome! How can I help?

WebdriverIO AI Copilot