Ein Szenario schreiben

Eine JSON-Datei, eine Liste von Aktionen, achtzehn Verben. Wie Sie eines anhand einer gelesenen Seite schreiben, und die zwei Gewohnheiten, die es funktionsfähig halten.

Ein Szenario ist eine JSON-Datei: wohin, und was dort zu tun ist. Es ist die Arbeitseinheit des Browserkerns.

{
  "nom": "check-dashboard",
  "url": "https://target.local/login",
  "actions": [
    {"type": "remplir", "selecteur": "input[name=\"username\"]", "valeur": "depuis_secrets", "secret_cle": "username"},
    {"type": "remplir", "selecteur": "input[name=\"password\"]", "valeur": "depuis_secrets", "secret_cle": "password"},
    {"type": "cliquer", "selecteur": "button[type=\"submit\"]"},
    {"type": "attendre_selecteur_present", "selecteur": ".user-menu"}
  ]
}

Zwei Felder sind Pflicht: url und actions. Die Datei wird vor dem Start des Browsers gegen scenarios/schema.json geprüft: Ein falsch geschriebener Schlüssel stoppt den Lauf sofort, nicht auf halbem Weg.

Zuerst die Seite lesen

Für eine Seite, die Sie nicht gelesen haben, können Sie keine Aktionen schreiben. Lesen Sie sie zuerst:

/opt/dinoer/venv/bin/python3 /opt/dinoer/shot.py \
  --url https://target.local/login --a11y --guide-version 1.6

a11y_tree liefert Ihnen die Struktur, das Erkundungsszenario die Selektoren. Schreiben Sie das Szenario anhand dieser Ausgabe, nicht anhand dessen, wie die Seite vermutlich aussieht. Das Erkundungsszenario →

Die achtzehn Verben

Familie	Aktionen
Handeln	`cliquer`, `remplir`, `defiler`
In einem Frame	`cliquer_iframe`, `remplir_iframe`
Sich bewegen	`naviguer`
Warten	`attendre`, `attendre_absence`, `attendre_selecteur_present`, `attendre_navigation`, `attendre_url`, `attendre_reseau_calme`, `pause`
Beobachten	`evaluer`, `extraire_texte`
Zweiter Faktor	`attendre_mfa_ntfy`
Zusammensetzen	`declencher_scenario`, `nettoyer_overlay`

Eine Aktion, die auf ein Element zielt, nimmt einen CSS-Selektor; eine nummerierte Überlagerung, die man stattdessen nutzen könnte, gibt es nicht. Warum →

Die Pflicht- und optionalen Schlüssel jedes Verbs sowie die Exit-Codes stehen im Spickzettel.

Erste Gewohnheit: auf ein Signal warten, nie auf eine Dauer

Eine pause ist eine Wette darauf, wie lange etwas dauert, und sie lässt sich in beide Richtungen verlieren.

{"type": "cliquer", "selecteur": "button[type=\"submit\"]"},
{"type": "attendre_absence", "selecteur": ".spinner"},
{"type": "attendre_selecteur_present", "selecteur": ".result"}

Mit einer Pause von zehn Sekunden wird ein Vorgang, der fünfzehn dauert, gelesen, während er noch läuft: Erfolg gemeldet, nichts geprüft. Einer, der zwei dauert, verschwendet bei jedem Lauf acht Sekunden. Wer auf eine Veränderung der Seite wartet, lässt das Szenario genau so lange dauern wie die Arbeit.

Zweite Gewohnheit: die Seite prüfen, bevor man handelt

Setzen Sie eine Prüfung an den Anfang. Ist die Seite nicht die erwartete, hält das Szenario an, bevor etwas eingetippt wird:

{"type": "evaluer", "script": "document.title", "contient": "Sign in"}

Diese Prüfung steht zwischen einer unbemerkten Weiterleitung und einem Passwort, das in das Formular eines anderen getippt wird. auth_indicator nennt einen Selektor, der nur nach der Anmeldung existiert; die Antwort meldet dann, ob er gefunden wurde (auth_status):

{"auth_indicator": ".user-menu", "url": "…", "actions": [...]}

Optionen, die die Datei selbst tragen kann

Manche Einstellungen gehören zum Ziel, nicht zu dem, der das Szenario startet. Schreiben Sie sie in die Datei:

Eigenschaft	Wofür
`wait_until`	ein Ziel, dessen Netzverkehr nie zur Ruhe kommt
`http_credentials`	HTTP-Basic-Authentifizierung
`auth_indicator`	prüfen, ob die Sitzung angemeldet ist
`intention`	ein Satz, der ins Betriebsjournal geschrieben wird

Wer Ihr Szenario wiederverwendet, muss die Eigenheiten des Ziels dann nicht kennen.

Nie Zugangsdaten hineinschreiben

{"type": "remplir", "selecteur": "input[name=\"password\"]",
 "valeur": "depuis_secrets", "secret_cle": "password"}

Das Szenario nennt einen Schlüssel; das verschlüsselte Verzeichnis hält den Wert. Deshalb können Sie ein Szenario committen. Dinoer führt kein Szenario aus, das ein Geheimnis im Klartext enthält, sei es in einem remplir auf einem sensibel wirkenden Feld oder in einem evaluer-Skript.

Das verschlüsselte Verzeichnis für Zugangsdaten →

Kurz gesagt

Lesen Sie die Seite zuerst mit --a11y; schreiben Sie das Szenario anhand dieser Ausgabe.
url und actions sind Pflicht, alles andere ist optional.
Ein Element wird immer über einen CSS-Selektor angesprochen.
Warten Sie auf Signale, nicht auf Zeitspannen.
Prüfen Sie die Seite, bevor Sie auf ihr handeln.
Zugangsdaten sind immer ein secret_cle, nie ein Wert, nirgends in der Datei.