Écrire un scénario

Un fichier JSON, une liste d'actions, dix-huit verbes. Comment en écrire un à partir d'une page que vous avez lue, et les deux habitudes qui le gardent en état de marche.

Un scénario est un fichier JSON : où aller, et quoi y faire. C’est l’unité de travail du cœur de navigation.

{
  "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"}
  ]
}

Deux champs sont obligatoires : url et actions. Le fichier est vérifié contre scenarios/schema.json avant le démarrage du navigateur : une clé mal orthographiée arrête l’exécution tout de suite, pas à mi-parcours.

Commencer par lire la page

On ne peut pas écrire d’actions pour une page qu’on n’a pas lue. Lisez-la d’abord :

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

a11y_tree vous donne la structure ; le scénario de relevé vous donne les sélecteurs. Écrivez le scénario à partir de cette sortie, pas de l’idée que vous vous faites de la page. Le scénario de relevé →

Les dix-huit verbes

Famille	Actions
Agir	`cliquer`, `remplir`, `defiler`
Dans un cadre	`cliquer_iframe`, `remplir_iframe`
Se déplacer	`naviguer`
Attendre	`attendre`, `attendre_absence`, `attendre_selecteur_present`, `attendre_navigation`, `attendre_url`, `attendre_reseau_calme`, `pause`
Observer	`evaluer`, `extraire_texte`
Second facteur	`attendre_mfa_ntfy`
Composer	`declencher_scenario`, `nettoyer_overlay`

Une action qui vise un élément prend un sélecteur CSS ; il n’existe pas de superposition numérotée à utiliser à la place. Pourquoi →

Les clés obligatoires et facultatives de chaque verbe, et les codes de sortie, figurent dans la fiche de référence.

Première habitude : attendre un signal, jamais une durée

Une pause est un pari sur la durée d’une opération, et on peut le perdre dans les deux sens.

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

Avec une pause de dix secondes, une opération qui en prend quinze est lue pendant qu’elle tourne encore : succès annoncé, rien de vérifié. Une opération qui en prend deux fait perdre huit secondes à chaque exécution. Attendre un changement dans la page fait durer le scénario exactement autant que le travail.

Deuxième habitude : vérifier la page avant d’agir

Placez une vérification en tête. Si la page n’est pas celle que vous attendez, le scénario s’arrête avant de rien saisir :

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

C’est cette vérification qui sépare une redirection passée inaperçue d’un mot de passe tapé dans le formulaire de quelqu’un d’autre. auth_indicator désigne un sélecteur qui n’existe qu’une fois connecté ; la réponse indique alors s’il a été trouvé (auth_status) :

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

Les options que le fichier peut porter

Certains réglages appartiennent à la cible, pas à celui qui lance le scénario. Mettez-les dans le fichier :

Propriété	Pour
`wait_until`	une cible dont le réseau ne se calme jamais
`http_credentials`	l’authentification HTTP Basic
`auth_indicator`	vérifier que la session est connectée
`intention`	une phrase consignée dans le journal des opérations

Celui qui réutilise votre scénario n’a alors pas besoin de connaître les particularités de la cible.

Ne jamais écrire un identifiant

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

Le scénario nomme une clé ; le répertoire chiffré détient la valeur. C’est ce qui permet de committer un scénario. Dinoer refuse d’exécuter un scénario qui contient un secret écrit en clair, dans un remplir sur un champ d’apparence sensible ou dans un script evaluer.

Le répertoire chiffré des identifiants →

En bref

Lisez d’abord la page avec --a11y ; écrivez le scénario à partir de cette sortie.
url et actions sont obligatoires ; tout le reste est facultatif.
Un élément se vise toujours par un sélecteur CSS.
Attendez des signaux, pas des durées.
Vérifiez la page avant d’agir dessus.
Un identifiant est toujours une secret_cle, jamais une valeur, nulle part dans le fichier.