Escribir un escenario

Un archivo JSON, una lista de acciones, dieciocho verbos. Cómo escribir uno a partir de una página que ha leído, y los dos hábitos que lo mantienen en funcionamiento.

Un escenario es un archivo JSON: adónde ir y qué hacer allí. Es la unidad de trabajo del núcleo de navegación.

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

Dos campos son obligatorios: url y actions. El archivo se comprueba contra scenarios/schema.json antes de arrancar el navegador: una clave mal escrita detiene la ejecución de inmediato, no a mitad de camino.

Empezar por leer la página

No se pueden escribir acciones para una página que no se ha leído. Léala primero:

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

a11y_tree le da la estructura; el escenario de reconocimiento le da los selectores. Escriba el escenario a partir de esa salida, no de cómo cree que es la página. El escenario de reconocimiento →

Los dieciocho verbos

Familia	Acciones
Actuar	`cliquer`, `remplir`, `defiler`
Dentro de un marco	`cliquer_iframe`, `remplir_iframe`
Moverse	`naviguer`
Esperar	`attendre`, `attendre_absence`, `attendre_selecteur_present`, `attendre_navigation`, `attendre_url`, `attendre_reseau_calme`, `pause`
Observar	`evaluer`, `extraire_texte`
Segundo factor	`attendre_mfa_ntfy`
Componer	`declencher_scenario`, `nettoyer_overlay`

Una acción que apunta a un elemento recibe un selector CSS; no existe una superposición numerada que usar en su lugar. Por qué →

Las claves obligatorias y opcionales de cada verbo, y los códigos de salida, están en la hoja de referencia rápida.

Primer hábito: esperar una señal, nunca una duración

Una pause es una apuesta sobre lo que tarda algo, y se puede perder en los dos sentidos.

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

Con una pausa de diez segundos, una operación que tarda quince se lee cuando aún está en curso: éxito anunciado, nada comprobado. Una que tarda dos hace perder ocho segundos en cada ejecución. Esperar un cambio en la página hace que el escenario dure exactamente lo que dura el trabajo.

Segundo hábito: comprobar la página antes de actuar

Ponga una comprobación al principio. Si la página no es la esperada, el escenario se detiene antes de escribir nada:

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

Esta comprobación es lo que se interpone entre una redirección que pasó desapercibida y una contraseña escrita en el formulario de otra persona. auth_indicator nombra un selector que solo existe con la sesión iniciada; la respuesta indica entonces si se encontró (auth_status):

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

Opciones que puede llevar el archivo

Algunos ajustes pertenecen al objetivo, no a quien ejecuta el escenario. Póngalos en el archivo:

Propiedad	Para
`wait_until`	un objetivo cuya red nunca se calma
`http_credentials`	la autenticación HTTP Basic
`auth_indicator`	comprobar que la sesión está iniciada
`intention`	una frase que se anota en el registro de operaciones

Así, quien reutilice su escenario no necesita conocer las peculiaridades del objetivo.

Nunca escriba una credencial

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

El escenario nombra una clave; el directorio cifrado guarda el valor. Eso es lo que permite hacer commit de un escenario. Dinoer se niega a ejecutar un escenario que contenga un secreto escrito en claro, ya sea en un remplir sobre un campo de aspecto sensible o dentro de un script evaluer.

El directorio cifrado de credenciales →

En resumen

Lea primero la página con --a11y; escriba el escenario a partir de esa salida.
url y actions son obligatorios; todo lo demás es opcional.
Un elemento se señala siempre con un selector CSS.
Espere señales, no duraciones.
Compruebe la página antes de actuar sobre ella.
Una credencial es siempre una secret_cle, nunca un valor, en ninguna parte del archivo.