Aller au contenu principal

Sélecteurs

Le Protocole WebDriver fournit plusieurs stratégies de sélection pour interroger un élément. WebdriverIO les simplifie pour faciliter la sélection des éléments. Veuillez noter que même si la commande pour interroger les éléments s'appelle $ et $$, elles n'ont rien à voir avec jQuery ou le Moteur de Sélection Sizzle.

Bien qu'il existe de nombreux sélecteurs différents, seuls quelques-uns d'entre eux offrent un moyen fiable de trouver le bon élément. Par exemple, étant donné le bouton suivant :

<button
id="main"
class="btn btn-large"
name="submission"
role="button"
data-testid="submit"
>
Submit
</button>

Nous recommandons et ne recommandons pas les sélecteurs suivants :

SélecteurRecommandéNotes
$('button')🚨 JamaisLe pire - trop générique, sans contexte.
$('.btn.btn-large')🚨 JamaisMauvais. Couplé au style. Très susceptible de changer.
$('#main')⚠️ Avec parcimonieMieux. Mais toujours couplé au style ou aux écouteurs d'événements JS.
$(() => document.queryElement('button'))⚠️ Avec parcimonieRequête efficace, complexe à écrire.
$('button[name="submission"]')⚠️ Avec parcimonieCouplé à l'attribut name qui a une sémantique HTML.
$('button[data-testid="submit"]')✅ BonNécessite un attribut supplémentaire, non lié à l'a11y.
$('aria/Submit') ou $('button=Submit')✅ ToujoursLe meilleur. Ressemble à la façon dont l'utilisateur interagit avec la page. Il est recommandé d'utiliser les fichiers de traduction de votre frontend pour que vos tests ne échouent jamais lorsque les traductions sont mises à jour

Sélecteur CSS

Sauf indication contraire, WebdriverIO interrogera les éléments en utilisant le modèle de sélecteur CSS, par exemple :

selectors/example.js
loading...

Texte de lien

Pour obtenir un élément d'ancrage avec un texte spécifique, interrogez le texte en commençant par un signe égal (=).

Par exemple :

selectors/example.html
loading...

Vous pouvez interroger cet élément en appelant :

selectors/example.js
loading...

Texte de lien partiel

Pour trouver un élément d'ancrage dont le texte visible correspond partiellement à votre valeur de recherche, interrogez-le en utilisant *= devant la chaîne de requête (par exemple, *=driver).

Vous pouvez également interroger l'élément de l'exemple ci-dessus en appelant :

selectors/example.js
loading...

Remarque : Vous ne pouvez pas mélanger plusieurs stratégies de sélection dans un seul sélecteur. Utilisez plutôt plusieurs requêtes d'éléments chaînées pour atteindre le même objectif, par exemple :

const elem = await $('header h1*=Welcome') // ne fonctionne pas !!!
// utilisez plutôt
const elem = await $('header').$('*=driver')

Élément avec un texte spécifique

La même technique peut être appliquée aux éléments également. De plus, il est également possible de faire une correspondance insensible à la casse en utilisant .= ou .*= dans la requête.

Par exemple, voici une requête pour un titre de niveau 1 avec le texte "Welcome to my Page" :

selectors/example.html
loading...

Vous pouvez interroger cet élément en appelant :

selectors/example.js
loading...

Ou en utilisant une requête de texte partiel :

selectors/example.js
loading...

La même chose fonctionne pour les noms d'id et de class :

selectors/example.html
loading...

Vous pouvez interroger cet élément en appelant :

selectors/example.js
loading...

Remarque : Vous ne pouvez pas mélanger plusieurs stratégies de sélection dans un seul sélecteur. Utilisez plutôt plusieurs requêtes d'éléments chaînées pour atteindre le même objectif, par exemple :

const elem = await $('header h1*=Welcome') // ne fonctionne pas !!!
// utilisez plutôt
const elem = await $('header').$('h1*=Welcome')

Nom de balise

Pour interroger un élément avec un nom de balise spécifique, utilisez <tag> ou <tag />.

selectors/example.html
loading...

Vous pouvez interroger cet élément en appelant :

selectors/example.js
loading...

Attribut Name

Pour interroger des éléments avec un attribut name spécifique, vous pouvez soit utiliser un sélecteur CSS3 normal, soit la stratégie de nom fournie par le JSONWireProtocol en passant quelque chose comme [name="some-name"] comme paramètre de sélecteur :

selectors/example.html
loading...
selectors/example.js
loading...

Remarque : Cette stratégie de sélection est obsolète et ne fonctionne que dans les anciens navigateurs qui sont exécutés par le protocole JSONWireProtocol ou en utilisant Appium.

xPath

Il est également possible d'interroger des éléments via un xPath spécifique.

Un sélecteur xPath a un format comme //body/div[6]/div[1]/span[1].

selectors/xpath.html
loading...

Vous pouvez interroger le deuxième paragraphe en appelant :

selectors/example.js
loading...

Vous pouvez utiliser xPath pour également parcourir l'arbre DOM vers le haut et vers le bas :

selectors/example.js
loading...

Sélecteur de nom d'accessibilité

Interrogez les éléments par leur nom accessible. Le nom accessible est ce qui est annoncé par un lecteur d'écran lorsque cet élément reçoit le focus. La valeur du nom accessible peut être à la fois du contenu visuel ou des alternatives textuelles cachées.

info

Vous pouvez en savoir plus sur ce sélecteur dans notre article de blog de lancement

Récupérer par aria-label

selectors/aria.html
loading...
selectors/example.js
loading...

Récupérer par aria-labelledby

selectors/aria.html
loading...
selectors/example.js
loading...

Récupérer par contenu

selectors/aria.html
loading...
selectors/example.js
loading...

Récupérer par titre

selectors/aria.html
loading...
selectors/example.js
loading...

Récupérer par propriété alt

selectors/aria.html
loading...
selectors/example.js
loading...

ARIA - Attribut Role

Pour interroger des éléments basés sur les rôles ARIA, vous pouvez spécifier directement le rôle de l'élément comme [role=button] en tant que paramètre de sélecteur :

selectors/aria.html
loading...
selectors/example.js
loading...

Attribut ID

La stratégie de localisation "id" n'est pas prise en charge dans le protocole WebDriver, il faut utiliser les stratégies de sélecteur CSS ou xPath pour trouver des éléments en utilisant l'ID.

Cependant, certains pilotes (par exemple Appium You.i Engine Driver) pourraient encore prendre en charge ce sélecteur.

Les syntaxes de sélecteur actuellement prises en charge pour l'ID sont :

//localisateur css
const button = await $('#someid')
//localisateur xpath
const button = await $('//*[@id="someid"]')
//stratégie id
// Remarque : fonctionne uniquement dans Appium ou des frameworks similaires qui prennent en charge la stratégie de localisation "ID"
const button = await $('id=resource-id/iosname')

Fonction JS

Vous pouvez également utiliser des fonctions JavaScript pour récupérer des éléments en utilisant les API web natives. Bien sûr, vous ne pouvez le faire que dans un contexte web (par exemple, browser, ou contexte web sur mobile).

Étant donné la structure HTML suivante :

selectors/js.html
loading...

Vous pouvez interroger l'élément frère de #elem comme suit :

Welcome! How can I help?

WebdriverIO AI Copilot