Puppeteer Formular einreichen: Node.js-Leitfaden für 2026

Formulare sind das Tor zu den wertvollsten Teilen des modernen Webs: Kontoerstellung, Suchergebnisse, Dashboards, kostenpflichtige Downloads. Sie bündeln zudem alle Schwachstellen der Browser-Automatisierung an einem Ort. Ein einzelnes Puppeteer-Skript zum Absenden von Formularen muss unter Umständen mit React- oder Vue-Eingabefeldern zurechtkommen, die eine programmatische value Zuweisung ignorieren, Validierungen, die bei jedem Tastendruck ausgelöst werden, reine ARIA-Labels ohne id, versteckte Honeypot-Felder, Elemente außerhalb des Bildschirms, die man nicht anklicken kann, und Iframe-Sandboxes für Rich Text. Wenn Sie davon ausgehen, dass ein Formular nur statisches HTML ist, wird Ihr Skript stillschweigend fehlschlagen. Die folgenden Muster gehen davon aus, dass dies nicht der Fall ist.

Erstellen Sie einen neuen Ordner und führen Sie npm init -y. Setze "type": "module" in package.json so modern import Syntax funktioniert, dann installiere das vollständige Paket mit npm install puppeteer. Das enthält eine passende Chromium-Binärdatei, sodass du keinen separaten Browser benötigst. Verwende puppeteer-core stattdessen, wenn Sie eine bestehende Chrome-Installation nutzen möchten. Bevor Sie auch nur einen einzigen Selektor schreiben, führen Sie einen Smoke-Test durch, um sicherzustellen, dass alles richtig konfiguriert ist:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: 'new' });
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

Wenn ein echter Seitentitel ausgegeben wird, ist alles in Ordnung. Führe das Programm headless: false während du debuggst, wechsle dann zu 'new' , sobald das Skript stabil läuft.

Puppeteer bietet dir drei Möglichkeiten, Text in ein Feld einzugeben, und die Wahl hat konkrete Auswirkungen sowohl auf die Geschwindigkeit als auch auf die Bot-Erkennung. Beachte, dass es laut der aktuellen Puppeteer-Dokumentation zum Zeitpunkt des Verfassens dieses Artikels keine Top-Level- page.fill() auf der Page Klasse, wie Playwright eine bereitstellt; die entsprechende Aktion ist in der Puppeteer-Locator-API über page.locator(selector).fill(value).

Wenn du den Raw-Weg $eval Weg gehen, versenden new Event('input', { bubbles: true }) danach, damit React oder Vue die Änderung tatsächlich bemerkt.

Ein Puppeteer-Skript zum Absenden von Formularen funktioniert nur, wenn seine Selektoren eine Neuinstallation überstehen. Ordne deine Optionen nach Priorität:

1. #id wenn ein id vorhanden ist und stabil erscheint.
2. [name="..."] für jedes <input name> , das einen POST an ein Backend sendet, da der Name Teil des Vertrags ist.
3. [data-testid="..."] oder andere data-* Hooks, die explizit für die Automatisierung hinzugefügt wurden.
4. aria-label und label[for] Ketten für barrierefreie Benutzeroberflächen.
5. CSS-Attributselektoren wie input[type="email"] nur, wenn das Formular genau ein solches Feld enthält.
6. XPath als letztes Mittel, wenn Sie Textabgleiche benötigen, wie z. B. //button[contains(., "Sign in")].

Vermeiden Sie automatisch generierte Klassennamen wie .css-1q8r9j. Die Wahl von CSS anstelle von XPath zahlt sich in der Regel in Sachen Klarheit und Geschwindigkeit aus, aber XPath ist von unschätzbarem Wert, wenn Sie sich an sichtbarem Text orientieren müssen.

Die Suchleiste von Yelp verwendet zwei Texteingaben: #find_desc für das, was du suchst, und #dropperText_Mast für den Ort. Locator fill ist hier ausreichend; das Formular benötigt keine Ereignisse pro Taste.

await page.goto('https://www.yelp.com');
await page.locator('#find_desc').fill('coffee');
await page.locator('#dropperText_Mast').fill('Berlin, Germany');

await Promise.all([
  page.waitForNavigation({ waitUntil: 'networkidle2' }),
  page.click('button[type="submit"]'),
]);

await page.waitForSelector('h3 a.businessName__09f24__HG_pC', { timeout: 10000 });

Das Promise.all Muster löst den Klick- und den Navigations-Listener atomar aus, sodass du das Navigationsereignis nie verpasst, da es bereits vor der Registrierung des Wait-Befehls abgearbeitet wurde.

Die Anmeldeseite von GitHub eignet sich gut als Übung, da die drei Felder alle unterschiedliche Selektorstile verwenden: id beim Benutzernamen, name beim Passwort und type auf der Absenden-Schaltfläche.

await page.goto('https://github.com/login');
await page.type('input[id="login_field"]', process.env.GH_USER);
await page.type('input[name="password"]', process.env.GH_PASS);

await Promise.all([
  page.waitForNavigation(),
  page.click('input[type="submit"]'),
]);

Ich verwende hier bewusst page.type hier. Anmeldeseiten neigen dazu, Sitzungen zu identifizieren, bei denen Anmeldedaten zu schnell eingegeben werden, und Tastenanschläge pro Zeichen hinterlassen eine menschlicher wirkende Spur. Codieren Sie Anmeldedaten niemals fest ein; beziehen Sie sie aus Umgebungsvariablen.

Sobald die Felder ausgefüllt sind, haben Sie drei sinnvolle Optionen:

1. Klicken Sie auf die Absenden-Schaltfläche mit page.click('button[type="submit"]'). Die Standardeinstellung. Schlägt fehl, wenn die Schaltfläche ausgeblendet, außerhalb des Bildschirms oder von einem Sticky-Banner verdeckt ist. Lösen Sie dies page.waitForSelector(sel, { visible: true }) erstes.
2. Drücken Sie die Eingabetaste await page.keyboard.press('Enter') nachdem Sie den Fokus auf ein Feld gesetzt haben. Funktioniert bei fast jedem Suchfeld und Anmeldeformular. Schlägt fehl, wenn die Seite die Eingabetaste für die Autovervollständigung abfängt oder wenn kein Feld im Fokus ist.
3. Aufruf form.requestSubmit() through page.$eval('form', f => f.requestSubmit())auf. Umgeht Klick-Handler vollständig und führt eine native Validierung durch, was nützlich ist, wenn die sichtbare Schaltfläche benutzerdefiniert gerendert und unzuverlässig ist. Schlägt fehl, wenn ein benutzerdefinierter JS-Handler die eigentliche Übermittlung unterbricht und nur auf Klicks reagiert.

Wählen Sie nach dem Verhalten, nicht nach der Gewohnheit.

Über einfache Textfelder hinaus kombinieren echte Formulare Kontrollkästchen, Optionsfelder, Dropdown-Menüs, Schieberegler, Datumsfelder, Dateien und Rich Text. Jedes davon hat einen Puppeteer-spezifischen Happy Path und einige Fallstricke. Die nächsten vier Unterabschnitte behandeln diese mit kopier- und einfügbaren Mustern.

Für native Kontrollkästchen und Optionsfelder ist page.click ist dein Freund; es schaltet den Status um und löst die richtigen Ereignisse aus. Behandle Radio-Gruppen anhand ihres Attributs, nicht nur anhand ihrer Position.

await page.click('input[type="checkbox"][name="newsletter"]');
await page.click('input[type="radio"][name="plan"][value="pro"]');

const isChecked = await page.$eval(
  'input[name="newsletter"]',
  el => el.checked,
)

Lies immer checked zurück; gestylte Wrapper können den Klick verschlucken, ohne den Status zu ändern.

Native <select> Elemente sind der einfache Fall. Verwenden Sie page.select, das die Option valueund nicht die sichtbare Beschriftung. Für Mehrfachauswahl übergeben Sie ein Array. Länderauswahlen können sehr umfangreich sein; ein gängiges Beispiel aus dem ScrapeOps-Tutorial verwendet eine Liste mit rund 248 Länderoptionen, und dieselbe Aufrufsignatur verarbeitet sie alle.

await page.select('select#country', 'DE');
await page.select('select#languages', 'en', 'de', 'fr');

Benutzerdefinierte JS-Dropdown-Menüs (z. B. <div role="listbox">) benötigen eine Klicksequenz: Klicken Sie auf den Auslöser, warten Sie auf das Optionsfeld und klicken Sie über XPath auf die passende Option anhand des sichtbaren Textes.

Native <input type="date"> akzeptiert YYYY-MM-DD und kommt gut zurecht mit page.type oder Locator fill. Benutzerdefinierte Kalender-Widgets erfordern eine Klicksequenz im Popup. Bei einem Bereichsregler muss der Wert über das DOM gesetzt und die Ereignisse ausgelöst werden, da die Seite sonst nie neu gerendert wird. Im folgenden Beispiel für einen Regler haben wir den Regler vor dem Screenshot auf 85 % gesetzt:

await page.$eval('input[type="range"]', el => {
  el.value = 85;
  el.dispatchEvent(new Event('input', { bubbles: true }));
  el.dispatchEvent(new Event('change', { bubbles: true }));
});

Rich-Text-Editoren gibt es in zwei Formen. Ein contenteditable div akzeptiert Locator fill direkt an. Iframe-basierte Editoren wie CKEditor oder TinyMCE sind in einer Sandbox ausgeführt; du musst zuerst den Kontext über ElementHandle.contentFrame() , bevor Sie darin etwas finden können.

const frameHandle = await page.$('iframe.cke_wysiwyg_frame');
const frame = await frameHandle.contentFrame();
await frame.locator('body').fill('Hello from Puppeteer.');

Wenn ein Selektor innerhalb der Hauptseite null zurückgibt, vermute einen iframe, bevor du einen Tippfehler vermutest.

Bei einem sichtbaren <input type="file">, rufe dessen nativen Handle mit page.$ und rufen Sie uploadFile mit absoluten Pfaden auf. Mehrere Dateien sind einfach zusätzliche Argumente. Wichtiger Hinweis: uploadFile prüft nicht, ob die Datei tatsächlich existiert. Ein Tippfehler im Pfad führt zu einem stillen Fehler, das Formular wird ohne Anhang übermittelt, und Sie verbringen zwei Stunden damit, Ihren Selektoren die Schuld zu geben. Validieren Sie Pfade im Code.

import { existsSync } from 'node:fs';
import { resolve } from 'node:path';

const file = resolve('./uploads/report.pdf');
if (!existsSync(file)) throw new Error(`Missing: ${file}`);

const input = await page.$('input[type="file"]');
await input.uploadFile(file);

Wenn die sichtbare Benutzeroberfläche eine benutzerdefinierte „Durchsuchen“-Schaltfläche ist, die die eigentliche Eingabe verbirgt, verwende page.waitForFileChooser. Registrieren Sie zuerst den Listener und lösen Sie dann den Klick aus, der den OS-Dialog öffnet:

const [chooser] = await Promise.all([
  page.waitForFileChooser(),
  page.click('button.upload-trigger'),
]);
await chooser.accept([file]);

setTimeout und page.waitForTimeout sind keine Wartestrategien; sie sind Fehlerquellen. Wählen Sie ein konkretes Erfolgssignal:

• waitForNavigation: klassischer Neuladung der gesamten Seite nach dem Absenden. Umschließen mit Promise.all , damit du den Klick und das Warten überholst.
• waitForResponse: SPA-POSTs an eine API. Warte, bis die passende URL oder der Status zurückkommt.
• waitForSelector: ein Erfolgsbanner, ein Weiterleitungszielelement oder eine neue Zeile in einer Liste.
• waitForNetworkIdle: Modernes „Catch-All“ von Puppeteer, wenn das Erfolgssignal unklar ist und sich die Seite erst stabilisiert.

Bei einer typischen Suchanfrage auf das Ergebniselement achten; bei einer Anmeldung auf das Dashboard-Navigationselement. Beides sind stärkere Signale als eine URL-Änderung.

Ein Absenden, das 200 zurückgibt, ist nicht dasselbe wie ein Absenden, das funktioniert hat. Lies die Seite danach.

• Untersuchen Sie einen bekannten Fehlercontainer, zum Beispiel .error-message, und behandeln Sie jeden Textinhalt als eindeutigen Fehler: Epic sadface: Username is required ist eine echte Validierungsmeldung, die Sie auf der Demo-Website von Sauce Labs sehen werden.
• Führen Sie eine native Validierung über el.checkValidity() über $eval , um Felder zu erkennen, die der Benutzer vor dem Klicken falsch ausgefüllt hat.
• Vergleichen Sie page.url() den Zustand vor und nach dem Absenden, wenn eine Weiterleitung erwartet wird.
• Erstellen Sie bei jedem Fehler einen Screenshot mit await page.screenshot({ path: 'fail.png', fullPage: true }) , damit du in CI einen Nachweis hast.

Einige Formulare lösen vor dem Absenden immer noch ein natives confirm() vor dem Absenden aus. Puppeteer stellt diese als dialog Ereignisse an, und Sie müssen den Listener vor dem Klick registrieren, der den Dialog auslöst, da der Dialog sonst die Seite blockiert.

page.on('dialog', async dialog => {
  console.log('dialog:', dialog.message());
  await dialog.accept();
});
await page.click('button#delete-account');

Verwende dialog.dismiss() , um abzubrechen, und dialog.message() um zu protokollieren, was die Seite tatsächlich abgefragt hat.

Anmelde- und Registrierungsformulare sind der Schwerpunkt der Anti-Bot-Logik. Drei reale Bedrohungen:

1. Honeypots. Versteckte <input type="hidden"> oder optisch versteckte Textfelder, die ein echter Benutzer nie berührt. Wenn Ihr Skript blind jedes Eingabefeld ausfüllt, lehnt der Server Sie ab. Lesen Sie den berechneten Stil des Feldes aus oder type und überspringe alles, was nicht sichtbar ist.
2. Fingerprinting. Vanilla Puppeteer gibt navigator.webdriver = true und andere Hinweise preis. Basierend auf Community-Tests zum Zeitpunkt der Erstellung dieses Artikels puppeteer-extra-plugin-stealth werden die meisten davon behoben, obwohl Anbieter von Erkennungslösungen ihre Methoden ständig weiterentwickeln.
3. CAPTCHA. Laut den aktuellen Dokumentationen der relevanten Projekte kannst du puppeteer-extra mit puppeteer-extra-plugin-recaptcha und einem kostenpflichtigen Token im 2captcha-Stil kombinieren, um reCAPTCHA und hCaptcha zu bewältigen, doch Abdeckung und Zuverlässigkeit ändern sich im Laufe der Zeit. Wenn Sie diesen Kampf immer wieder verlieren, ist unsere Scraper-API eine schnellere Entlastung, als wöchentlich Stealth-Flags anzupassen.

Wenn ein Puppeteer-Skript zum Absenden eines Formulars stillschweigend nichts tut, gehen Sie diese Liste der Reihe nach durch:

1. Führen Sie es mit headless: false und slowMo: 100 damit du sehen kannst, was der Browser tatsächlich tut.
2. Öffne devtools: true und beobachten Sie die Registerkarten „Netzwerk“ und „Konsole“ auf blockierte Anfragen oder ausgelöste Fehler.
3. Überprüfen Sie required und pattern Attribute sowie checkValidity() in jedem Feld; die native Validierung kann das Absenden blockieren, bevor ein Handler ausgelöst wird.
4. Überprüfen Sie auf Elemente außerhalb des Bildschirms oder deaktivierte Elemente; scrollen Sie mit el.scrollIntoView() , bevor Sie klicken.
5. Prüfen Sie auf einen iframe-Wrapper; falls vorhanden, wechseln Sie den Kontext mit contentFrame().
6. Aktivieren Sie die Abfrageüberwachung, um jeden ausgehenden POST zu protokollieren und zu bestätigen, ob die Absendeanfrage den Browser überhaupt verlassen hat.

Vor der Veröffentlichung:

• Verwenden Sie stabile Selektoren, bevorzugen Sie id, name, und data-testid.
• Umschließe jede Navigation mit Promise.all mit einer konkreten Wartezeit.
• Legen Sie Werte pro Aktion fest timeout Werte fest; verwende niemals unendlich als Standard.
• Umschließen Sie den Lauf in Wiederholungsversuche mit exponentiellem Backoff.
• Erstellen Sie bei jedem Fehler einen Screenshot und senden Sie ihn an Ihren Log-Speicher.
• Geben Sie strukturierte Protokolle aus, führen Sie headless: 'new'und rotieren Sie Proxys für jedes öffentlich zugängliche Ziel.

Wählen Sie die Eingabemethode entsprechend dem, worauf die Seite reagiert, wählen Sie den Absendepfad, der dem Verhalten des Formulars entspricht, warten Sie auf ein echtes Erfolgssignal und erstellen Sie bei jedem Fehler einen Screenshot. Vertiefen Sie sich von hier aus in verwandte Puppeteer-Tutorials zu Dateidownloads, den Grundlagen von Headless-Browsern und der Wahl zwischen XPath- und CSS-Selektoren.

• Verwenden Sie page.locator(selector).fill(value) für Geschwindigkeit und page.type , wenn die Seite Tastenanschläge überwacht (Autocomplete, Anti-Bot, Live-Validierung).
• Senden Sie durch Klicken auf die Schaltfläche, Drücken der Eingabetaste oder Aufrufen von form.requestSubmit(); wählen Sie je nach Formularverhalten, nicht aus Gewohnheit.
• Kombinieren Sie die Absendungsaktion immer mit einer konkreten Wartezeit (waitForNavigation, waitForResponse, waitForSelectoroder waitForNetworkIdle) innerhalb von Promise.all.
• Bei Datei-Uploads validieren Sie den Pfad selbst; uploadFile tut dies nicht, und ein Tippfehler führt zu einem stillen Fehler.
• Wenn ein Formular das Absenden stillschweigend verweigert, führen Sie headful mit slowMo, überprüfen Sie required/pattern die Validierung, scanne nach Honeypots und suche nach Iframe-Wrappern.

Nicht in der Page Klasse. Nach der aktuellen Puppeteer-Dokumentation zum Zeitpunkt der Erstellung dieses Artikels fill Aktion in der Locator-API, daher rufst du await page.locator(selector).fill(value) anstelle von Playwrights await page.fill(selector, value). Locator fill unterstützt input, textarea, selectsowie checkbox , und wartet, bis das Element aktivierbar ist, bevor der Wert zugewiesen wird.

Verwenden Sie form.requestSubmit() through page.$eval('form#login', f => f.requestSubmit()). Dies löst die native HTML5-Validierung aus und löst das submit Ereignis aus, ohne dass ein anklickbares Element erforderlich ist. Als Fallback setzen Sie den Fokus auf ein beliebiges Feld innerhalb des Formulars mit page.focus() und rufen Sie await page.keyboard.press('Enter'), was von den meisten Such- und Anmeldeformularen akzeptiert wird.

Warten Sie auf den zugrunde liegenden API-Aufruf statt auf eine Navigation. Verwenden Sie await page.waitForResponse(res => res.url().includes('/api/submit') && res.status() === 200)oder page.waitForNetworkIdle({ idleTime: 500 }) , wenn die SPA mehrere parallele Anfragen auslöst. Kombinieren Sie beides mit waitForSelector mit dem „success“-Element, damit du auch sicherstellst, dass die Benutzeroberfläche das Ergebnis gerendert hat.

Übergeben Sie jeden absoluten Pfad als separates Argument an uploadFile: await input.uploadFile(file1, file2, file3). Das Ziel <input type="file"> muss das multiple Attribut haben, andernfalls behält der Browser nur den letzten Eintrag. Für benutzerdefinierte „Durchsuchen“-Schaltflächen rufen Sie chooser.accept([file1, file2]) auf den von waitForFileChooser.

Ja, aber Sie müssen zuerst den Kontext wechseln. Rufen Sie das iframe-Element mit page.$('iframe#payment'), und rufen Sie dann await handle.contentFrame() , um ein Frame Objekt abzurufen. Von dort aus ist jede Methode, die Sie auf page (type, click, locator, waitForSelector) ist im Frame verfügbar und wird im Geltungsbereich seines Dokuments ausgeführt.

Ein zuverlässiges Puppeteer-Skript zum Absenden von Formularen ist größtenteils eine Frage des Geschmacks. Wählen Sie die Eingabemethode, die dem entspricht, worauf die Seite wartet, den Absendepfad, der der tatsächlichen Auslösung des Formulars entspricht, und die Wartezeit, die dem Erfolgssignal entspricht, das Sie tatsächlich beobachten können. Die Mechanik ist nicht tiefgreifend; die Disziplin besteht darin, keine dieser drei Entscheidungen zu überspringen.

Die Muster in diesem Leitfaden decken die Fälle ab, auf die du bei 90 % der öffentlichen Websites triffst. Die letzten 10 % – Anmeldeseiten mit aggressivem Fingerprinting, CAPTCHA-geschützte Checkouts, Anti-Bot-WAFs, die ihr Verhalten wöchentlich ändern – sind eine ganz andere Liga. Das Einstellen von Stealth-Flags für deine eigene Browserflotte ist echte Ingenieursarbeit, und die Wartungskosten summieren sich.

Wenn Sie diese Zeit lieber für den Datenfluss als für die Anforderungsschicht aufwenden möchten, schauen Sie sich WebScrapingAPI an. Es übernimmt Proxy-Rotation, Browser-Fingerprinting und CAPTCHA-Lösung hinter einem einzigen Endpunkt, sodass Ihr Puppeteer-Skript seine Logik zum Ausfüllen von Formularen beibehalten und einfach die Teile abgeben kann, die schwieriger zu warten sind, als dass sie interessant wären. So oder so: Gewöhnen Sie sich jetzt das „Senden und Überprüfen“ an, und Ihr zukünftiges Ich wird es Ihnen danken.