Playwright-Aktionen

Dieses Kapitel stellt Playwright-Operationen im Zusammenhang mit Navigation und Klicken sowie den automatischen Wartemechanismus hinter diesen Operationen vor.

Was ist eine Aktion

Eine Aktion ist eine Methode in Playwright, die verwendet wird, umNutzerverhalten zu simulieren, wie das Klicken auf Schaltflächen, die Texteingabe und die Auswahl von Dropdowns.

Bevor jede Aktion ausgeführt wird, wartet Playwright automatisch darauf, dass das Zielelement denaktionierbaren Zustand erreicht.。

Aktionsfähigkeitsprüfungen

Bevor Playwright jede Aktion ausführt, führt es eine Reihe von Prüfungen am Zielelement durch:

SchrittPrüfbedingungBeschreibung
1. AngehängtElement ist an den DOM-Baum angehängtElement ist auf der Seite vorhanden
2. SichtbarElement ist sichtbar (nichtdisplay:noneodervisibility:hidden）der Benutzer kann das Element sehen
3. StabilElement ist stabil (Animationen abgeschlossen)Fehlerhafte Aktionen während Animationen vermeiden
4. Empfängt EventsElement wird nicht von anderen Elementen verdecktStellen Sie sicher, dass der Klick vom Element empfangen werden kann
5. AktiviertElement ist nicht deaktiviert (nichtdisabled）Benutzer kann damit interagieren

Wenn eine Prüfung fehlschlägt, wartet Playwright und versucht es erneut, bis das Timeout erreicht ist.

Diese 5 Prüfungen werden automatisch von Playwright durchgeführt, sodass Sie keinen zusätzlichen Wartecode schreiben müssen. Dies ist auch der grundlegende Grund, weshalb Playwright flaky Tests stark reduzieren kann.

Erzwungene Aktionen { force: true }

Manchmal müssen Sie die Actionability-Prüfungen umgehen, zum Beispiel einen durch ein Overlay verdeckten Button anklicken oder den Zustand eines unsichtbaren Elements testen.

Beispiel

// Erzwungener Klick, alle Actionability-Prüfungen überspringen
await page.getByRole('button', { name: 'Submit' }).click({ force: true });

force: trueist eine Operation, die über das hinausgeht, was echte Benutzer tun können, und sollte in der überwiegenden Mehrheit der Fälle nicht verwendet werden. Wenn Ihr Test erfordertforce: true, prüfen Sie zuerst, ob ein Problem mit dem Interaktionsdesign vorliegt.

Navigationsaktionen

page.goto() Seitennavigation

Beispiel

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

// Auf DOMContentLoaded warten (Seitenstruktur geladen)
await page.goto('https://www.example.com/', { waitUntil: 'domcontentloaded' });

// Auf Netzwerk-Leerlauf warten (alle asynchronen Daten geladen)
await page.goto('https://www.example.com/', {
  waitUntil: 'networkidle',    // Netzwerk-Leerlauf
  timeout: 60000,              // Timeout 60 Sekunden
  referer: 'https://google.com', // Referer-Quelle
});

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

Beispiel

// Eine Seite zurück
await page.goBack();

// Eine Seite vorwärts
await page.goForward();

// Seite aktualisieren
await page.reload();

Klickaktionen

locator.click() Einzelklick

Beispiel

// Einfacher Einzelklick
await page.getByRole('button', { name: 'Login' }).click();

// Mit Optionen klicken
await page.getByRole('button', { name: 'Login' }).click({
  button: 'left',     // Maustaste: 'left' | 'right' | 'middle'
  clickCount: 1,      // Anzahl der Klicks
  delay: 100,         // Verzögerung zwischen Drücken und Loslassen (Millisekunden)
  timeout: 5000,      // Zeitüberschreitung
  modifiers: [],      // Modifikatortasten: ['Alt', 'Control', 'Meta', 'Shift']
});

locator.dblclick() Doppelklick

Beispiel

// Element doppelklicken
await page.getByText('Double-click to edit').dblclick();

Rechtsklick

Beispiel

// Rechtsklick (Kontextmenü öffnen)
await page.getByText('Right-click menu').click({ button: 'right' });

Klick mit Modifikatortaste

Beispiel

// Ctrl + Klicken (Mehrfachauswahl)
await page.getByRole('option').click({ modifiers: ['Control'] });

// Shift + Klicken (Bereichsauswahl / in neuem Fenster öffnen)
await page.getByRole('link').click({ modifiers: ['Shift'] });

Koordinatenklick

Beispiel

// Klick auf eine bestimmte Position innerhalb des Elements (relativ zu seiner oberen linken Ecke)
await page.locator('canvas').click({
  position: { x: 100, y: 50 },
});

locator.hover() Hovern

Beispiel

// Maus-Hover (Hover-Effekt oder Dropdown-Menü auslösen)
await page.getByRole('link', { name: 'Tutorial' }).hover();

// Nach dem Hover auf das Popup-Untermenü klicken
await page.getByRole('link', { name: 'Playwright Tutorial' }).click();

Anwendungsszenarien: Klicken vs. Hover

AktionAnwendungsfall
click()Button-Klicks, Link-Navigation, Checkbox-Umschaltung
dblclick()Bearbeitungsmodus aufrufen, Doppelklick zum Auswählen von Text
click({ button: 'right' })Öffnen des nativen Kontextmenüs des Browsers
hover()Hover-Menüs auslösen, Tooltip-Hinweise
click({ position })Canvas-Operationen, benutzerdefinierte Grafikinteraktionen

Aktionen für Texteingabe

locator.fill() Leeren und Ausfüllen

fill()Es leert zuerst das Eingabefeld und trägt dann den neuen Wert ein. Es ist die am häufigsten verwendete und empfohlene Methode für Eingabevorgänge.

Beispiel

// Das Eingabefeld leeren und einen neuen Wert eingeben
await page.getByLabel('Username').fill('example_user');
await page.getByLabel('Password').fill('secure_password');
await page.getByPlaceholder('Search EXAMPLE tutorials').fill('Playwright');

locator.type() Zeichenweise Eingabe

type()Es gibt Zeichen eins nach dem anderen ein, simuliert echte Tastenanschläge, und Sie können ein Intervall zwischen jedem Tastendruck festlegen.

Beispiel

// Zeichen für Zeichen eingeben (100ms Verzögerung zwischen Zeichen)
await page.getByLabel('Search').type('Playwright', { delay: 100 });

Unterschied zwischen fill und type

MethodeVerhaltenAnwendungsfall
fill()Leeren und Ausfüllen in einem SchrittDie meisten Szenarien (empfohlen)
type()Zeichenweise Eingabe, wodurch jedes Tastendruck-Ereignis ausgelöst wirdWenn Eingabevorschläge ausgelöst werden müssen, Echtzeitsuche

In den meisten Fällen verwenden Siefill()Das war's. Nur wenn das Eingabefeld eine Echtzeitsuche (keydown/keyup-Ereignisse) hat, ist die Verwendung erforderlichtype()。

locator.clear() Leeren

Beispiel

// Inhalt des Eingabefelds löschen
await page.getByLabel('Username').clear();

Auswahlaktionen

locator.check() / uncheck() Kontrollkästchen

Beispiel

// Kontrollkästchen aktivieren
await page.getByLabel('I agree to the service agreement').check();

// Deaktivieren
await page.getByLabel('Receive email notifications').uncheck();

// Den aktivierten Zustand setzen
await page.getByLabel('Remember me').setChecked(true);   // Überprüfen, ob es aktiviert ist
await page.getByLabel('Remember me').setChecked(false);  // Überprüfen, ob es deaktiviert ist

locator.selectOption() Dropdown-Auswahl

Beispiel

// Nach dem value-Attribut auswählen
await page.getByLabel('City').selectOption('beijing');

// Nach sichtbarem Text auswählen
await page.getByLabel('City').selectOption({ label: 'Shanghai' });

// Mehrfachauswahl-Dropdown
await page.getByLabel('Interessen-Tags').selectOption([
  { label: 'Programmierung' },
  { value: 'Design' },
]);

// Nach Index auswählen (Element 0, Element 2)
await page.getByLabel('Stadt').selectOption({ index: 0 });

Tastaturaktionen

page.keyboard.press() Taste drücken

Beispiel

// Enter drücken und loslassen
await page.keyboard.press('Enter');

// Alle auswählen (Control + A)
await page.keyboard.press('Control+A');

// Kopieren und Einfügen
await page.keyboard.press('Control+C');
await page.keyboard.press('Control+V');

// Rückgängig
await page.keyboard.press('Control+Z');

page.keyboard.down() / up() Drücken / Loslassen

Beispiel

// Shift gedrückt halten, ohne loszulassen
await page.keyboard.down('Shift');

// In dieser Zeit andere Tasten drücken (entspricht dem Halten von Shift während des Drückens anderer Tasten)
await page.keyboard.press('ArrowRight');  // Shift + Pfeil nach rechts (Text auswählen)
await page.keyboard.press('ArrowRight');

// Shift loslassen
await page.keyboard.up('Shift');

Namen spezieller Tasten

TastennameEntsprechende Taste
EnterEnter
EscapeEsc zum Beenden
TabTab zum Wechseln des Fokus
BackspaceBackspace zum Löschen
DeleteEntf-Taste
ArrowUp/Down/Left/RightPfeiltasten
PageUp/PageDownBild-Tasten
Home/EndPos1 / Ende
Control/Alt/Shift/MetaModifizierertasten

page.keyboard.type() Text über die Tastatur eingeben

Beispiel

// Text in das fokussierte Element eingeben
await page.keyboard.type('BEISPIEL Tutorial', { delay: 50 });

page.keyboard.insertText() Direkt einfügen

Beispiel

// Text direkt an der fokussierten Position einfügen (simuliert keine Tastaturereignisse, am schnellsten)
await page.keyboard.insertText('Schnell eingefügter Text');

Mausaktionen

Klicken und Bewegen nach Koordinaten

Beispiel

// An Viewport-Koordinaten (100, 200) klicken
await page.mouse.click(100, 200);

// Doppelklick an Koordinaten
await page.mouse.dblclick(100, 200);

// Maus an Koordinaten bewegen
await page.mouse.move(100, 200);

// Drücken / Loslassen
await page.mouse.down();
await page.mouse.up();

Mausrad

Beispiel

// 500px nach unten scrollen
await page.mouse.wheel(0, 500);

// 200px nach links scrollen
await page.mouse.wheel(200, 0);

locator.dragTo() Ziehen

Beispiel

// Element A zu Element B ziehen
const source = page.getByText('Drag me');
const target = page.getByTestId('drop-zone');
await source.dragTo(target);

// Mit Optionen ziehen
await source.dragTo(target, {
  sourcePosition: { x: 0, y: 0 },   // Startpunkt des Ziehens (relativ zum Quellelement)
  targetPosition: { x: 10, y: 10 }, // Zielpunkt des Ziehens (relativ zum Zielelement)
});

Wahl zwischen page.mouse und locator.click

MethodeAnwendungsszenario
locator.click()Auf Seitenelemente klicken (die meisten Szenarien)
page.mouse.click()Auf bestimmte Koordinaten klicken (Szenarien ohne DOM wie Canvas, Diagramme)

Datei-Upload

locator.setInputFiles() Einzelne/mehrere Dateien

Beispiel

// Eine einzelne Datei hochladen
await page
  .getByLabel('Choose file')
  .setInputFiles('path/to/document.pdf');

// Mehrere Dateien hochladen
await page
  .getByLabel('Choose file')
  .setInputFiles([
    'path/to/file1.png',
    'path/to/file2.png',
  ]);

// Ausgewählte Dateien entfernen
await page.getByLabel('Datei auswählen').setInputFiles([]);

Dateipfade sind relativ zum aktuellen Arbeitsverzeichnis (Projektstammverzeichnis).

Dateidownload

Beispiel

// Warten auf das Download-Ereignis starten (muss vor dem Vorgang aufgerufen werden, der den Download auslöst)
const downloadPromise = page.waitForEvent('download');

// Den Vorgang ausführen, der den Download auslöst
await page.getByRole('button', { name: 'Bericht herunterladen' }).click();

// Warten, bis der Download abgeschlossen ist
const download = await downloadPromise;

// Den vorgeschlagenen Dateinamen abrufen
console.log(download.suggestedFilename());

// In den angegebenen Pfad speichern
await download.saveAs('downloads/report.pdf');
Weitere Erweiterungen