Comment ajouter et utiliser une étape JavaScript

Qu'est-ce qu'une étape JavaScript ?

Une étape JavaScript vous permet d'exécuter votre propre code JavaScript à un point précis d'un test. Utilisez-la lorsqu'une étape en langage naturel ou une étape web ne peut pas exprimer ce dont vous avez besoin : lire une valeur calculée, combiner deux lectures du DOM, appeler une API pour vérifier l'état du backend, ou construire des données de test dynamiques.

Vous écrivez le corps d'une fonction Step(). Elle vous fournit un contexte prêt à l'emploi (vos variables, la page, un client API, la console, le réseau et les étapes précédentes), et vous retournez un résultat : l'étape réussit ou échoue.

Quand l'utiliser

Capturer une valeur : lire une valeur de la page (ou en calculer une) et la stocker dans une variable pour les étapes suivantes.
Valider l'état du backend : appeler une API interne ou externe en cours de test et la comparer à ce qu'affiche l'interface.
Faire des assertions sur le réseau : vérifier que la page a émis la bonne requête avec la bonne charge utile.
Construire des données dynamiques : générer des dates, des références ou des valeurs composées pour que les tests ne dépendent pas de données codées en dur.
Débloquer la page : fermer une bannière de cookies ou définir une valeur dans le localStorage dont dépend une étape suivante.

Quand privilégier une étape dédiée

Pour les actions courantes, les étapes dédiées sont plus simples. Réservez l'étape JavaScript aux cas où vous avez besoin d'une véritable logique.

Si vous voulez…	Privilégiez
Cliquer, saisir, sélectionner, survoler, attendre un élément	Une étape web ou une étape en langage naturel
Appeler une API et faire des assertions sur sa réponse comme étape à part entière	Une étape d'Appel API
Bifurquer ou arrêter l'exécution selon une condition simple	Une étape conditionnelle (IF)
Exécuter une logique personnalisée qu'aucune des options ci-dessus ne peut exprimer	Une étape JavaScript

Comment ajouter une étape JavaScript

Ouvrez votre cas de test.
Cliquez sur Ajouter une nouvelle étape.
Dans Type d'étape, sélectionnez Étape JavaScript.
Ajoutez une Description : un résumé court et lisible de ce que fait l'étape. Ce libellé est obligatoire et identifie l'étape dans la vue d'exécution.
Écrivez votre code dans l'éditeur.

La fonction `Step()`

L'éditeur s'ouvre avec un modèle. Vous écrivez le corps de la fonction ; la signature et l'accolade fermante restent en place.

function Step(response, variables, DOM, api_client, console, network, test_steps) {
  // Write your logic here.
  return response.Success();
}

Chaque étape retourne un seul résultat : response.Success() lorsqu'elle réussit, ou response.Fail('reason') sinon.

Les objets de contexte

Votre fonction Step() reçoit sept objets. Ils sont prêts à l'emploi, sans rien à importer ni à configurer.

Objet	Ce qu'il vous offre
`response`	Le constructeur de résultat. Retournez `response.Success()` ou `response.Fail('reason')` pour indiquer au moteur ce qui s'est passé.
`variables`	Lire et écrire les variables Thunders. `variables['MY_VAR']` renvoie la valeur actuelle ; lui affecter une valeur met à jour la variable pour le reste du test. Fonctionne avec les variables d'environnement, de projet et les données de lot CSV.
`DOM`	Le `document` de la page en direct. Utilisez les API DOM standards comme `DOM.querySelector(...)`, `.textContent`, `.getAttribute(...)`, etc.
`api_client`	Un client HTTP pour appeler des API depuis l'étape. Voir Appeler des API.
`console`	`console.log`, `console.info`, `console.warn`, `console.error`. Les messages apparaissent dans le résultat de l'étape dans la vue d'exécution. C'est votre principal outil de débogage.
`network`	Une vue en lecture seule des requêtes émises par la page. `network.requests` est une liste de `{ url, method, status, headers, body }`. Voir Lire les requêtes réseau.
`test_steps`	Une liste en lecture seule des étapes déjà exécutées. Chacune a `name` (le texte de l'étape), `outcome` (`passed`, `failed` ou `skipped`) et `duration` en ms, pour que votre étape puisse réagir à ce qui s'est passé avant.

Les méthodes response

Retournez exactement l'une d'entre elles.

Méthode	Comportement
`response.Success()`	L'étape réussit et l'exécution continue vers l'étape suivante.
`response.Success(value)`	Réussit et attache `value` au résultat de l'étape, pratique pour faire apparaître une réponse d'API ou un objet calculé dans la vue d'exécution.
`response.Fail('reason')`	L'étape échoue. La raison apparaît dans le récapitulatif d'exécution, et l'exécution s'arrête (comme pour les autres échecs d'étape).

Utiliser les variables

Il existe deux façons de travailler avec les variables, et elles se complètent :

Interpolation [VARIABLE] : Thunders remplace tout jeton [MY_VAR] de votre code par la valeur de la variable avant l'exécution du script, comme dans les autres étapes.
L'objet variables : variables['MY_VAR'] lit la valeur actuelle à l'exécution, et lui affecter une valeur (variables['MY_VAR'] = 'nouvelle valeur') met à jour la variable pour le reste du test.

Appeler des API avec `api_client`

api_client vous permet d'appeler une API depuis l'étape et de faire des assertions sur le résultat, par exemple pour confirmer que le backend est cohérent avec ce qu'affiche l'interface.

Méthode	Description
`api_client.get(url, opts)`	Envoie une requête GET.
`api_client.post(url, body, opts)`	Envoie une requête POST avec un `body` JSON.
`api_client.put(url, body, opts)`	Envoie une requête PUT avec un `body` JSON.
`api_client.patch(url, body, opts)`	Envoie une requête PATCH avec un `body` JSON.
`api_client.delete(url, opts)`	Envoie une requête DELETE.

Chaque appel est asynchrone : utilisez donc await. Passez des en-têtes personnalisés via opts, par ex. { headers: { 'X-Env': 'staging' } }. Chaque appel vous renvoie une réponse que vous pouvez lire :

{
  status,   // HTTP status code, e.g. 200
  ok,       // true when status is 2xx
  data,     // the parsed response body
  headers   // response headers
}

function Step(response, variables, DOM, api_client, console, network, test_steps) {
  const res = await api_client.get(`/api/carts/${variables['CART_ID']}`);
  if (!res.ok) {
    return response.Fail(`Cart lookup failed with status ${res.status}`);
  }
  return response.Success(res.data);
}

Lire les requêtes réseau

network.requests est une liste en lecture seule des requêtes émises par la page pendant l'exécution de l'étape, chacune avec { url, method, status, headers, body } (les corps JSON sont analysés pour vous). Utilisez-la pour confirmer qu'une requête a été envoyée, vérifier un code de statut ou lire une charge utile de réponse.

function Step(response, variables, DOM, api_client, console, network, test_steps) {
  const analytics = network.requests.find(r => r.url.includes('/analytics/event'));
  if (!analytics) {
    return response.Fail('No analytics event was fired');
  }
  if (analytics.body.event_name !== 'checkout_completed') {
    return response.Fail(`Wrong event name: ${analytics.body.event_name}`);
  }
  return response.Success();
}

Exemples

1. Capturer une valeur de la page dans une variable

function Step(response, variables, DOM, api_client, console, network, test_steps) {
  const orderId = DOM.querySelector('[data-order-id]').textContent;
  variables['ORDER_ID'] = orderId;
  return response.Success();
}

Après la soumission d'une commande, l'identifiant de commande apparaît sur la page de confirmation. Capturez-le pour que les étapes suivantes puissent naviguer vers /orders/[ORDER_ID] ou appeler une API avec.

2. Valider l'interface par rapport au backend

function Step(response, variables, DOM, api_client, console, network, test_steps) {
  const uiTotal = parseFloat(DOM.querySelector('.cart-total').textContent.replace('$', ''));
  const res = await api_client.get(`/api/carts/${variables['CART_ID']}`);
  if (res.data.total !== uiTotal) {
    return response.Fail(`Cart mismatch: UI ${uiTotal}, API ${res.data.total}`);
  }
  return response.Success();
}

Détecte les bugs d'intégrité des données que les tests purement visuels manquent : la page s'affiche correctement, mais le backend n'est pas d'accord.

3. Construire des données de test dynamiques

function Step(response, variables, DOM, api_client, console, network, test_steps) {
  const today = new Date();
  const year = today.getFullYear();
  const month = String(today.getMonth() + 1).padStart(2, '0');
  variables['BILLING_PERIOD'] = `${year}-${month}`;
  variables['INVOICE_REF'] = `INV-${variables['CUSTOMER_ID']}-${year}${month}`;
  return response.Success();
}

Évitez les dates codées en dur qui cassent le mois suivant, et construisez des valeurs composées à partir de variables existantes.

4. Débloquer la page

function Step(response, variables, DOM, api_client, console, network, test_steps) {
  // A cookie banner intercepts the login button on staging, so dismiss it.
  const banner = DOM.querySelector('.cookie-banner');
  if (banner) banner.remove();
  return response.Success();
}

5. Réagir à une étape précédente

function Step(response, variables, DOM, api_client, console, network, test_steps) {
  const login = test_steps.find(s => s.name.includes('Log in'));
  if (login && login.duration > 5000) {
    variables['USE_RECOVERY_FLOW'] = 'true';
    console.warn('Login was slow, switching to the recovery flow');
  }
  return response.Success();
}

Écrivez un indicateur dans une variable, puis bifurquez dessus avec une étape conditionnelle suivante.

Comment les résultats apparaissent dans une exécution de test

Dans la vue d'exécution, sélectionnez l'étape JavaScript pour ouvrir son onglet JavaScript. Il affiche :

Un bloc Résultat : la valeur retournée par votre étape (le cas échéant) et votre sortie console. En cas d'erreur dans le code, vous verrez aussi le message et le numéro de ligne ; cliquez dessus pour ouvrir l'éditeur à cette ligne.

Résultat	Ce que cela signifie
Success	L'étape a retourné `response.Success()`. Elle est marquée en vert et l'exécution continue.
Échec	L'étape a retourné `response.Fail('reason')`. La raison est affichée et l'exécution s'arrête.
Erreur	Quelque chose dans votre code a échoué (par exemple une faute de frappe ou un élément manquant). Le message d'erreur et le numéro de ligne sont affichés pour que vous puissiez corriger.