Escribir un escenario

Un archivo JSON, una lista de acciones, veintiún verbos. Cómo escribir uno que siga funcionando el mes que viene, y los dos hábitos que lo deciden.

Un escenario es un archivo JSON: adónde ir y qué hacer allí. Es la unidad de trabajo de Diwall — escribirá algunos, reutilizará otros y los pondrá bajo control de versiones.

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

Dos campos son obligatorios: url y actions. Todo lo demás es opcional, y el archivo se valida antes de que arranque el navegador — una errata en el nombre de una clave detiene la ejecución de inmediato, y no a mitad de camino.

Empezar por mirar

No se pueden escribir acciones para una página que no se ha leído. Captúrela primero:

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

elements_som le da los números, a11y_tree los selectores y la estructura. Escriba el escenario a partir de esa salida, no del recuerdo de cómo es probablemente la página.

Los veintiún verbos

Familia	Acciones
Actuar	`cliquer`, `cliquer_som`, `cliquer_visuel`, `remplir`, `remplir_som`, `defiler`
Dentro de un marco	`cliquer_iframe`, `remplir_iframe`
Desplazarse	`naviguer`
Esperar	`attendre`, `attendre_absence`, `attendre_selecteur_present`, `attendre_navigation`, `attendre_url`, `attendre_reseau_calme`, `pause`
Observar	`capturer`, `evaluer`
Componer	`declencher_scenario`, `nettoyer_overlay`, `attendre_mfa_ntfy`

Las variantes _som toman un número de la captura; las demás, un selector CSS. Prefiera los números cuando la página es estable, y los selectores cuando dispone de algo único con lo que identificar el elemento.

Los parámetros de cada verbo, obligatorios y opcionales, están en la guía rápida.

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

Una pause es una apuesta sobre lo que tarda algo. La perderá, en los dos sentidos.

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

Fije una pausa de diez segundos: una operación que tarda quince le da la captura de un trabajo todavía en curso — éxito anunciado, nada comprobado. Una que tarda dos malgasta ocho segundos en cada ejecución.

Esperar una señal del DOM hace que el escenario dure exactamente lo que dura el trabajo. Reserve pause para un retraso deliberado, no para una suposición.

Segundo hábito: comprobar antes de actuar

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

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

No cuesta nada, y es lo que separa una redirección que pasó inadvertida de una contraseña escrita en el formulario de un desconocido. El escenario de autenticación incluido con Diwall empieza exactamente así.

auth_indicator hace lo mismo a nivel de archivo — un selector que solo existe una vez autenticado, comprobado automáticamente:

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

Opciones que el propio archivo puede llevar

Algunas opciones dependen del destino, no de la persona que ejecuta el escenario. Póngalas en el archivo para que sea autosuficiente:

Propiedad	Para
`wait_until`	un destino que nunca llega al silencio de red
`shadow_dom`	componentes dentro de shadow roots abiertos
`som_brut`	renunciar a la resolución híbrida de Set-of-Mark y volver a la reindexación sola (rara vez necesario — la resolución híbrida por defecto ya señala la deriva)
`http_credentials`	autenticación HTTP Basic
`intention`	una frase anotada en el registro de operaciones

Quien reutilice su escenario no necesitará conocer las particularidades del destino.

Nunca escriba una credencial

{"type": "remplir_som", "id": 3,
 "valeur": "depuis_secrets", "secret_cle": "password"}

El escenario nombra una clave; el directorio cifrado guarda el valor. Es lo que permite versionar un escenario sin riesgo, y el control de publicación rechaza toda publicación en la que encuentre una contraseña en claro dentro de un escenario.

El directorio cifrado de credenciales →

En resumen

Capture primero la página; escriba el escenario a partir de la salida.
url y actions son obligatorios — todo lo demás es opcional.
Espere señales, no duraciones.
Compruebe la página antes de actuar sobre ella.
Ponga en el archivo las opciones propias del destino, para que viaje solo.
Una credencial es siempre una secret_cle, nunca un valor.