Actions Playwright

Ce chapitre présente les opérations Playwright liées à la navigation et au clic, ainsi que le mécanisme d'attente automatique derrière ces opérations.


Qu'est-ce qu'une Action

Une Action est une méthode dans Playwright utilisée poursimuler le comportement de l'utilisateurcomme cliquer sur des boutons, saisir du texte et sélectionner des listes déroulantes.

Avant chaque exécution d'une Action, Playwright attend automatiquement que l'élément cible atteigneun état actionnable。


Vérifications d'actionnabilité

Avant d'exécuter chaque action, Playwright effectue une série de vérifications sur l'élément cible :

ÉtapeVérification ConditionDescription
1. AttachéL'élément est attaché à l'arborescence DOML'élément existe dans la page
2. VisibleL'élément est visible (nondisplay:noneouvisibility:hidden)l'utilisateur peut voir l'élément
3. StableL'élément est stable (animations terminées)Éviter les actions erronées pendant les animations
4. Reçoit les événementsL'élément n'est pas masqué par d'autres élémentsS'assurer que le clic peut être reçu par l'élément
5. ActivéL'élément n'est pas désactivé (pasdisabled)l'utilisateur peut interagir avec lui

Si une vérification échoue, Playwright attend et réessaie jusqu'à ce que le délai d'attente soit atteint.

Ces 5 vérifications sont effectuées automatiquement par Playwright, vous n'avez donc pas besoin d'écrire de code d'attente supplémentaire. C'est aussi la raison fondamentale pour laquelle Playwright peut grandement réduire les tests instables.


Actions forcées { force: true }

Parfois, vous devez contourner les vérifications d'actionnabilité, par exemple en cliquant sur un bouton masqué par une superposition ou en testant l'état d'un élément invisible.

Exemple

// Clic forcé, ignorer toutes les vérifications d'actionnabilité
await page.getByRole('button', { name: 'Submit' }).click({ force: true });

force: trueest une opération au-delà de ce que les utilisateurs réels peuvent faire, et ne devrait pas être utilisée dans la grande majorité des cas. Si votre test nécessiteforce: true, vérifiez d'abord s'il existe un problème de conception d'interaction.


Actions de navigation

page.goto() Navigation de page

Exemple

// Navigation de base
await page.goto('https://www.example.com/');

// Attendre DOMContentLoaded (structure de la page chargée)
await page.goto('https://www.example.com/', { waitUntil: 'domcontentloaded' });

// Attendre que le réseau soit inactif (toutes les données asynchrones chargées)
await page.goto('https://www.example.com/', {
  waitUntil: 'networkidle',    // Réseau inactif
  timeout: 60000,              // Délai d'attente de 60 secondes
  referer: 'https://google.com', // Source du référent
});

page.goBack() / goForward() / reload()

Exemple

// Revenir à la page précédente
await page.goBack();

// Avancer à la page suivante
await page.goForward();

// Actualiser la page
await page.reload();

Actions de clic

locator.click() Clic simple

Exemple

// Clic simple de base
await page.getByRole('button', { name: 'Login' }).click();

// Clic avec options
await page.getByRole('button', { name: 'Login' }).click({
  button: 'left',     // Bouton de souris : 'left' | 'right' | 'middle'
  clickCount: 1,      // Nombre de clics
  delay: 100,         // Délai entre l'appui et le relâchement (millisecondes)
  timeout: 5000,      // Délai d'attente
  modifiers: [],      // Touches de modification : ['Alt', 'Control', 'Meta', 'Shift']
});

locator.dblclick() Double-clic

Exemple

// Double-clic sur l'élément
await page.getByText('Double-click to edit').dblclick();

Clic droit

Exemple

// Clic droit (ouvrir le menu contextuel)
await page.getByText('Menu contextuel').click({ button: 'right' });

Clic avec touche de modification

Exemple

// Ctrl + clic (sélection multiple)
await page.getByRole('option').click({ modifiers: ['Control'] });

// Shift + clic (sélection de plage / ouvrir dans une nouvelle fenêtre)
await page.getByRole('link').click({ modifiers: ['Shift'] });

Clic par coordonnées

Exemple

// Cliquer à une position précise dans l'élément (par rapport à son coin supérieur gauche)
await page.locator('canvas').click({
  position: { x: 100, y: 50 },
});

locator.hover() Survol

Exemple

// Survol de la souris (déclencher un effet de survol ou un menu déroulant)
await page.getByRole('link', { name: 'Tutorial' }).hover();

// Après avoir survolé, cliquez sur le sous-menu contextuel
await page.getByRole('link', { name: 'Playwright Tutorial' }).click();

Scénarios d'utilisation du clic vs du survol

OpérationScénario applicable
click()Clics sur les boutons, navigation par liens, basculement des cases à cocher
dblclick()Entrée en mode édition, double-clic pour sélectionner du texte
click({ button: 'right' })Ouverture du menu contextuel natif du navigateur
hover()Déclenchement de menus au survol, info-bulles
click({ position })Opérations sur Canvas, interactions graphiques personnalisées

Actions de saisie de texte

locator.fill() Effacer et remplir

fill()Il vide d'abord le champ de saisie, puis le remplit avec la nouvelle valeur. C'est la méthode la plus couramment utilisée et recommandée pour les opérations de saisie.

Exemple

// Effacer le champ de saisie et le remplir avec une nouvelle valeur
await page.getByLabel('Username').fill('example_user');
await page.getByLabel('Password').fill('secure_password');
await page.getByPlaceholder('Search EXAMPLE tutorials').fill('Playwright');

locator.type() Saisie caractère par caractère

type()Il saisit les caractères un par un, simulant de véritables frappes clavier, et vous pouvez définir un intervalle entre chaque appui sur une touche.

Exemple

// Saisir caractère par caractère (délai de 100ms entre les caractères)
await page.getByLabel('Search').type('Playwright', { delay: 100 });

Différence entre fill et type

MéthodeComportementScénario applicable
fill()Effacer et remplir en une seule foisLa plupart des scénarios (recommandé)
type()Saisie caractère par caractère, déclenchant chaque événement de frappeLorsqu'il est nécessaire de déclencher des suggestions de saisie, recherche en temps réel

Dans la plupart des cas, utilisezfill()C'est tout. Ce n'est que lorsque le champ de saisie dispose d'une recherche en temps réel (événements keydown/keyup) qu'il est nécessaire d'utilisertype()。

locator.clear() Effacer

Exemple

// Effacer le contenu du champ de saisie
await page.getByLabel('Username').clear();

Actions de sélection

locator.check() / uncheck() Case à cocher

Exemple

// Cocher la case
await page.getByLabel('I agree to the service agreement').check();

// Décocher
await page.getByLabel('Recevoir les notifications par e-mail').uncheck();

// Définir l'état coché
await page.getByLabel('Se souvenir de moi').setChecked(true);   // Vérifier qu'il est coché
await page.getByLabel('Se souvenir de moi').setChecked(false);  // Vérifier qu'il est décoché

locator.selectOption() Sélection dans une liste déroulante

Exemple

// Sélectionner par l'attribut value
await page.getByLabel('Ville').selectOption('beijing');

// Sélectionner par le texte visible
await page.getByLabel('Ville').selectOption({ label: 'Shanghai' });

// Liste déroulante à sélection multiple
await page.getByLabel('Tags d’intérêt').selectOption([
  { label: 'Programmation' },
  { value: 'design' },
]);

// Sélectionner par index (élément 0, élément 2)
await page.getByLabel('Ville').selectOption({ index: 0 });

Actions clavier

page.keyboard.press() Appuyer sur une touche

Exemple

// Appuyer et relâcher Entrée
await page.keyboard.press('Enter');

// Tout sélectionner (Control + A)
await page.keyboard.press('Control+A');

// Copier et coller
await page.keyboard.press('Control+C');
await page.keyboard.press('Control+V');

// Annuler
await page.keyboard.press('Control+Z');

page.keyboard.down() / up() Appuyer / Relâcher

Exemple

// Maintenir Shift sans relâcher
await page.keyboard.down('Shift');

// Appuyer sur d'autres touches pendant ce temps (équivalent à maintenir Shift tout en appuyant sur d'autres touches)
await page.keyboard.press('ArrowRight');  // Shift + Flèche droite (sélectionner du texte)
await page.keyboard.press('ArrowRight');

// Relâcher Shift
await page.keyboard.up('Shift');

Noms des touches spéciales

Nom de la toucheTouche correspondante
EnterEntrée
EscapeÉchap pour quitter
TabTab pour changer le focus
BackspaceRetour arrière pour supprimer
DeleteTouche Suppr
ArrowUp/Down/Left/RightTouches fléchées
PageUp/PageDownTouches Page
Home/EndDébut / Fin
Control/Alt/Shift/MetaTouches de modification

page.keyboard.type() Saisir du texte via le clavier

Exemple

// Saisir du texte dans l'élément ciblé
await page.keyboard.type('EXAMPLE Tutorial', { delay: 50 });

page.keyboard.insertText() Insérer directement

Exemple

// Insérer directement du texte à la position ciblée (ne simule pas les événements clavier, le plus rapide)
await page.keyboard.insertText('Quickly inserted text');

Actions de la souris

Clic aux coordonnées

Exemple

// Cliquer aux coordonnées de la fenêtre d'affichage (100, 200)
await page.mouse.click(100, 200);

// Double-cliquer aux coordonnées
await page.mouse.dbl(100, 200);

// Déplacer la souris vers les coordonnées
await page.mouse.move(100, 200);

// Appuyer / Relâcher
await page.mouse.down();
await page.mouse.up();

Molette de la souris

Exemple

// Faire défiler vers le bas de 500px
await page.mouse.wheel(0, 500);

// Faire défiler vers la gauche de 200px
await page.mouse.wheel(200, 0);

locator.dragTo() Glisser

Exemple

// Glisser l'élément A vers l'élément B
const source = page.getByText('Drag me');
const target = page.getByTestId('drop-zone');
await source.dragTo(target);

// Glisser avec options
await source.dragTo(target, {
  sourcePosition: { x: 0, y: 0 },   // Point de départ du glisser (relatif à l'élément source)
  targetPosition: { x: 10, y: 10 }, // Point cible du glisser (relatif à l'élément cible)
});

Choisir entre page.mouse et locator.click

MéthodeScénario d'application
locator.click()Cliquer sur des éléments de page (la plupart des scénarios)
page.mouse.click()Cliquer sur des coordonnées spécifiques (scénarios sans DOM comme Canvas, graphiques)

Téléversement de fichier

locator.setInputFiles() Fichier unique/Fichiers multiples

Exemple

// Téléverser un seul fichier
await page
  .getByLabel('Choisir un fichier')
  .setInputFiles('path/to/document.pdf');

// Téléverser plusieurs fichiers
await page
  .getByLabel('Choisir un fichier')
  .setInputFiles([
    'path/to/file1.png',
    'path/to/file2.png',
  ]);

// Effacer les fichiers sélectionnés
await page.getByLabel('Choose file').setInputFiles([]);

Les chemins de fichiers sont relatifs au répertoire de travail actuel (répertoire racine du projet).


Téléchargement de fichier

Exemple

// Commencer à attendre l'événement de téléchargement (doit être appelé avant l'opération qui déclenche le téléchargement)
const downloadPromise = page.waitForEvent('download');

// Effectuer l'opération qui déclenche le téléchargement
await page.getByRole('button', { name: 'Download report' }).click();

// Attendre que le téléchargement soit terminé
const download = await downloadPromise;

// Obtenir le nom de fichier suggéré
console.log(download.suggestedFilename());

// Enregistrer dans le chemin spécifié
await download.saveAs('downloads/report.pdf');
Autres extensions