Exécutions de test

Une exécution de test transforme un script en preuves. L’agent enveloppe un parcours dans astral.test, le découpe en étapes, énonce ce qui doit être vrai, et Astral enregistre ce qui s’est passé.

Les exécutions de test utilisent l’outil run_script, qui exécute du JavaScript écrit par l’agent dans un bac à sable qui appelle les autres outils. Le groupe script est désactivé par défaut ; le groupe tests est activé par défaut, mais ne prend effet que tant que script est activé. Voir le groupe script.

Un exemple

return await astral.test('Login demo', async () => {
  await astral.step('Open the store', () => astral.navigate({url: 'http://localhost:3000/'}));
  await astral.step('Sign in', async () => {
    await astral.type({locator: {role: 'textbox', name: 'Username'}, text: 'demo'});
    await astral.type({locator: {role: 'textbox', name: 'Password'}, text: 'demo', submit: true});
    await astral.expect.visible({role: 'button', name: 'Sign out'});
    await astral.expect.noErrors();
  });
  await astral.step('Pay', async () => {
    await astral.click({locator: {role: 'button', name: 'Pay'}});
    await astral.expect.request({urlContains: '/api/', method: 'POST', status: '2xx'});
  });
}, {continueOnFailure: true, record: 'actions'});

Donnez à run_script un timeoutMs de 60000 à 120000 pour un test : les preuves prennent du temps.

astral.test et astral.step

Options de astral.test(name, fn, options) : tabId, continueOnFailure (false par défaut) et record. Il ne lève pas d’exception quand une étape échoue : vérifiez le status dans le résultat, qui contient aussi les totaux, un summary en Markdown et les chemins du rapport.

astral.step(name, fn) regroupe des actions. À sa fin, et toujours en cas d’échec, Astral enregistre une capture d’écran, l’URL et le titre, les requêtes effectuées pendant l’étape (celles qui échouent, avec en-têtes et corps masqués), les erreurs et avertissements de la console, ainsi que les nouveaux groupes d’erreurs. Une étape échoue lorsque sa fonction lève une exception ou qu’une attente qu’elle contient échoue. Sans continueOnFailure, le test s’arrête à la première étape échouée.

run_script accepte aussi test: {name, continueOnFailure, ...} pour traiter tout le script comme un seul test.

Attentes

Appel	Réussit lorsque
`expect.visible(locator)`	L’élément est visible, en attendant jusqu’à `timeoutMs` (5000 par défaut).
`expect.hidden(locator)`	L’élément n’est pas visible.
`expect.text(locator, 'contains')` / `expect.text('text')`	L’élément contient le texte, ou le texte apparaît n’importe où sur la page.
`expect.url('/dashboard')` / `expect.url(/regex/)`	L’URL de l’onglet correspond.
`expect.request({urlContains, method, status})`	Une requête correspondante a été effectuée depuis le début de l’étape. `status` est un nombre, `'2xx'` ou `'error'`.
`expect.noErrors({kinds, waitMs, ignoreStatus, ignore})`	Aucun nouveau groupe d’erreurs n’est apparu depuis le début de l’étape. Ignorez des statuts comme 401 ou des messages par sous-chaîne.
`expect.layout({rules, ignore})`	La mise en page responsive de la page ne présente aucune erreur au viewport de l’exécution. Voir la vérification de la mise en page.

Un localisateur est {role, name, text, nth, exact}, une référence d’instantané comme "e12", ou un texte. Une attente échouée lève une erreur d’assertion indiquant ce qui était attendu et ce qui a été trouvé, et le rapport l’affiche. astral.screenshot({name, fullPage}) dans un test ajoute une capture d’écran nommée à l’étape en cours.

Modes d’enregistrement

Mode	Ce qui est capturé
`'off'`	Des captures d’écran uniquement des échecs.
`'steps'` (par défaut)	Une capture d’écran à la fin de chaque étape.
`'actions'`	Aussi une après chaque clic, saisie, sélection, appui de touche et navigation, prise pendant qu’un repère signale la cible : un cadre, une onde au point du clic et une légende comme click "Sign in".
`'video'`	Aussi des images de l’onglet à 4 par seconde (jusqu’à 5 minutes ou 200 Mo), enregistrées sous forme de `recording.png` animé, et `recording.mp4` là où Astral peut en encoder un (macOS), avec un lecteur d’images dans le rapport.

Les repères sont dessinés dans tous les modes sauf 'off', disparaissent après 2,5 secondes et à la fin de l’exécution, et ne capturent jamais les clics. Le texte saisi dans un champ de mot de passe, de code à usage unique ou de carte n’est jamais écrit : les légendes affichent •••••• et la valeur est masquée partout ailleurs dans le rapport. Voir Plateformes pour la prise en charge de la vidéo.

Ce que laisse une exécution

Chaque exécution écrit un dossier dans le répertoire de données d’Astral contenant :

report.html : un rapport lisible avec un résumé, une carte par étape avec ses captures d’écran, l’assertion échouée, les requêtes en échec, les erreurs de la console, les erreurs de page regroupées, une chronologie des actions et une section de performances.
report.json : les mêmes données, plus un résumé en Markdown conçu pour être collé dans une issue.
Les captures d’écran sous forme de fichiers PNG, et l’enregistrement si vous en avez demandé un.

Les 50 exécutions les plus récentes sont conservées (configurable dans Settings → Developer, où les exécutions de test peuvent aussi être désactivées). L’agent relit les exécutions avec test_runs_list et test_run_get.

Des preuves pour les tickets

Le résumé en Markdown est conçu pour être collé dans une issue, à côté des captures d’écran et du rapport. Si votre agent est connecté à votre outil de tickets, il peut y publier ces preuves à votre place. Astral lui-même ne s’intègre à aucun outil de tickets : il écrit les preuves et en laisse la publication à vous ou à votre agent.

Les noms de tests, les étapes, les noms de captures d’écran et tout ce qu’Astral écrit à propos d’une exécution sont en anglais, quelle que soit la langue que vous, le ticket ou la page utilisez. Seuls les localisateurs conservent le texte propre de la page.