Rédiger un scénario

Un fichier JSON, une liste d'actions, vingt et un verbes. Comment en écrire un qui marche encore le mois prochain, et les deux habitudes qui en décident.

Un scénario est un fichier JSON : où aller, et quoi y faire. C’est l’unité de travail de Diwall — vous en écrirez, vous en réutiliserez, vous les versionnerez.

{
  "nom": "check-dashboard",
  "url": "https://target.local/login",
  "actions": [
    {"type": "remplir_som", "id": 2, "valeur": "depuis_secrets", "secret_cle": "username"},
    {"type": "remplir_som", "id": 3, "valeur": "depuis_secrets", "secret_cle": "password"},
    {"type": "cliquer_som", "id": 5},
    {"type": "attendre_selecteur_present", "selecteur": ".user-menu"}
  ]
}

Deux champs sont obligatoires : url et actions. Tout le reste est facultatif, et le fichier est validé avant le démarrage du navigateur — une faute de frappe dans un nom de clé arrête l’exécution tout de suite, et non à mi-parcours.

Commencer par regarder

On n’écrit pas d’actions pour une page qu’on n’a pas lue. Capturez-la d’abord :

diwall-shot --url https://target.local/login --som --a11y --guide-version 1.3

elements_som vous donne les numéros, a11y_tree les sélecteurs et la structure. Écrivez le scénario à partir de cette sortie, pas du souvenir de ce à quoi la page ressemble probablement.

Les vingt et un verbes

Famille	Actions
Agir	`cliquer`, `cliquer_som`, `cliquer_visuel`, `remplir`, `remplir_som`, `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	`capturer`, `evaluer`
Composer	`declencher_scenario`, `nettoyer_overlay`, `attendre_mfa_ntfy`

Les variantes _som prennent un numéro issu de la capture ; les autres, un sélecteur CSS. Préférez les numéros quand la page est stable, et les sélecteurs quand vous disposez d’un repère unique.

Les paramètres de chaque verbe, obligatoires et facultatifs, sont dans le guide rapide.

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

Une pause est un pari sur la durée de quelque chose. Vous le perdrez, dans les deux sens.

{"type": "cliquer_som", "id": 7},
{"type": "attendre_absence", "selecteur": ".spinner"},
{"type": "attendre_selecteur_present", "selecteur": ".result"}

Réglez une pause à dix secondes : une opération qui en prend quinze vous donne la capture d’un travail encore en cours — succès annoncé, rien de vérifié. Une qui en prend deux gaspille huit secondes à chaque exécution.

Attendre un signal du DOM fait durer le scénario exactement le temps du travail. Gardez pause pour un délai voulu, pas pour une supposition.

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

Placez un contrôle en tête. Si la page n’est pas celle que vous attendez, le scénario s’arrête avant de taper quoi que ce soit où que ce soit :

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

Cela ne coûte rien, et c’est ce qui sépare une redirection passée inaperçue d’un mot de passe tapé dans le formulaire d’un inconnu. Le scénario d’authentification livré avec Diwall commence exactement ainsi.

auth_indicator fait la même chose au niveau du fichier — un sélecteur qui n’existe qu’une fois authentifié, vérifié automatiquement :

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

Les options que le fichier peut porter lui-même

Certaines options tiennent à la cible, pas à la personne qui lance le scénario. Mettez-les dans le fichier pour qu’il se suffise à lui-même :

Propriété	Pour
`wait_until`	une cible qui n’atteint jamais le silence réseau
`shadow_dom`	des composants dans des shadow roots ouverts
`som_brut`	renoncer à la résolution hybride de Set-of-Mark et revenir à la réindexation seule (rarement utile — la résolution hybride par défaut signale déjà la dérive)
`http_credentials`	l’authentification HTTP Basic
`intention`	une phrase inscrite dans le journal des opérations

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

N’écrivez jamais un identifiant

{"type": "remplir_som", "id": 3,
 "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 versionner un scénario sans risque, et le contrôle de publication refuse toute publication dans laquelle il trouve un mot de passe en clair dans un scénario.

Le répertoire chiffré des identifiants →

En bref

Capturez d’abord la page ; écrivez le scénario à partir de la sortie.
url et actions sont obligatoires — tout le reste est facultatif.
Attendez des signaux, pas des durées.
Vérifiez la page avant d’agir dessus.
Mettez les options propres à la cible dans le fichier, pour qu’il voyage seul.
Un identifiant est toujours une secret_cle, jamais une valeur.