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 :
| Étape | Vérification Condition | Description |
|---|---|---|
| 1. Attaché | L'élément est attaché à l'arborescence DOM | L'élément existe dans la page |
| 2. Visible | L'élément est visible (nondisplay:noneouvisibility:hidden) | l'utilisateur peut voir l'élément |
| 3. Stable | L'élément est stable (animations terminées) | Éviter les actions erronées pendant les animations |
| 4. Reçoit les événements | L'élément n'est pas masqué par d'autres éléments | S'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
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
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
await page.goBack();
// Avancer à la page suivante
await page.goForward();
// Actualiser la page
await page.reload();
Actions de clic
locator.click() Clic simple
Exemple
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
await page.getByText('Double-click to edit').dblclick();
Clic droit
Exemple
await page.getByText('Menu contextuel').click({ button: 'right' });
Clic avec touche de modification
Exemple
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
await page.locator('canvas').click({
position: { x: 100, y: 50 },
});
locator.hover() Survol
Exemple
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ération | Scé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
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
await page.getByLabel('Search').type('Playwright', { delay: 100 });
Différence entre fill et type
| Méthode | Comportement | Scénario applicable |
|---|---|---|
fill() | Effacer et remplir en une seule fois | La plupart des scénarios (recommandé) |
type() | Saisie caractère par caractère, déclenchant chaque événement de frappe | Lorsqu'il est nécessaire de déclencher des suggestions de saisie, recherche en temps réel |
Dans la plupart des cas, utilisez
fill()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
await page.getByLabel('Username').clear();
Actions de sélection
locator.check() / uncheck() Case à cocher
Exemple
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
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
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
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 touche | Touche correspondante |
|---|---|
Enter | Entrée |
Escape | Échap pour quitter |
Tab | Tab pour changer le focus |
Backspace | Retour arrière pour supprimer |
Delete | Touche Suppr |
ArrowUp/Down/Left/Right | Touches fléchées |
PageUp/PageDown | Touches Page |
Home/End | Début / Fin |
Control/Alt/Shift/Meta | Touches de modification |
page.keyboard.type() Saisir du texte via le clavier
Exemple
await page.keyboard.type('EXAMPLE Tutorial', { delay: 50 });
page.keyboard.insertText() Insérer directement
Exemple
await page.keyboard.insertText('Quickly inserted text');
Actions de la souris
Clic aux coordonnées
Exemple
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
await page.mouse.wheel(0, 500);
// Faire défiler vers la gauche de 200px
await page.mouse.wheel(200, 0);
locator.dragTo() Glisser
Exemple
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éthode | Scé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
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
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');