Écrits en cliquant, livrés avec la doc.

Un scénario est une séquence de requêtes nommée et rejouable — 100 % déclarative. Il n’y a de crochet de scripting nulle part, et c’est précisément ce qui rend les scénarios sérialisables, partageables et exportables. Ce guide est le workflow d’écriture, de bout en bout ; pour ce que sont les scénarios et pourquoi, commencez par la page de fonctionnalité.

Capturer, pas rédiger

Envoyez une requête dans la console d’essai, puis « Ajouter à un scénario » ; la même action existe sur toute entrée de l’historique. Un scénario grandit pas à pas à partir de requêtes qui ont réellement tourné — à aucun moment il n’y a de JSON à écrire à la main.

Chaîner en cliquant la réponse

Dans la vue du scénario, la dernière réponse est cliquable : cliquez une clé pour en faire une variable ({{petId}} ← /id) ou une assertion. Quand une étape ultérieure a besoin d’une variable qu’aucune étape ne produit, la suggestion d’extraction vient de la variable manquante elle-même. Les assertions naissent de la réponse observée ou du schéma déclaré, de la même façon — en cliquant.

Avant tout envoi, le panneau des prérequis répond à « pourquoi ça va échouer » : variables manquantes, credentials absents, étapes dont rien ne produit encore les entrées.

Ce qu’une étape peut porter

Tout ce qu’une étape déclare est de la donnée, jamais du code — c’est précisément ce qui garde les scénarios sérialisables :

Les extractions — par pointeur ({{petId}} ← /id) ou par une query JSONPath (RFC 9535), où le premier nœud sélectionné gagne. Une extraction marquée sensitive est masquée comme n’importe quel identifiant. Une extraction marquée persist est écrite dans l’environnement actif à la fin d’une exécution réussie — l’exception assumée qui fonctionne même sous environmentsLocked, parce que la config gouverne la structure de l’environnement, pas les valeurs qu’une exécution produit.
Les assertions — quatre opérateurs : exists, equals (souple), regex (non ancrée), et matches — un JSONPath RFC 9535 qui passe dès qu’il sélectionne au moins un nœud.
timeout — par étape, en millisecondes ; le runner annule l’envoi au-delà.
continueOnFailure — une étape en échec arrête normalement « Tout lancer » ; avec ce drapeau, la séquence continue et le rapport nomme les étapes tombées.
Les entrées — scenario.inputs déclare des valeurs par défaut nommées ; l’environnement surcharge une entrée du même nom, et une valeur produite pendant l’exécution surcharge les deux.

Deux modes d’exécution

« Tout exécuter » déroule la séquence et rend un rapport par étape — statut, durée, valeurs extraites, lien vers l’historique. « Pas à pas » charge chaque étape dans la vraie console d’essai et laisse le lecteur envoyer : un scénario écrit devient un tutoriel interactif. Dans les deux modes, une variable manquante bloque l’étape ; le {{littéral}} n’est jamais envoyé.

Le livrer avec la doc

Exportez le scénario en fichier JSON, committez-le, déclarez-le :

{ "scenarios": [{ "id": "onboarding", "title": "Onboarding", "url": "/scenarios/onboarding.json" }] }

Les scénarios déclarés sont en lecture seule pour le lecteur (« Dupliquer » en fait une copie locale éditable) et se chargent à l’ouverture, paresseusement — sauf un scénario pinned, dont le fichier est récupéré au chargement de la page d’accueil. pinned: true met ce scénario en avant sur la page d’accueil, description et étapes visibles — typiquement le flow d’auth que vous voulez sous la main dès l’arrivée. En multi-spec, déclarez les scénarios uniquement sur les entrées specs[] : un scénario référence les opérations d’une spec précise.

Une entrée scenarios[] accepte soit le format d’export de l’app, soit un document de workflow Arazzo (1.0 ou 1.1), par url ou en document inline — le fichier que votre CI exécute déjà se déclare donc tel quel, et chacun de ses workflows devient un scénario :

{ "scenarios": [{ "id": "payments", "url": "/workflows/payments.arazzo.yaml" }] }

Le partager

Un scénario voyage en fichier JSON ou en lien #/scenario-import?d=…. L’import montre toujours un aperçu d’abord et n’exécute jamais rien automatiquement. Un fichier de scénario ne contient jamais de valeur sensible — les credentials restent des {{var}} d’environnement, et restent chez eux.

Les scénarios locaux sont plafonnés à 200 par spec. Au-delà, la création est refusée avec un message actionnable — exportez ou supprimez d’abord — jamais une éviction silencieuse : un scénario est le travail du lecteur, pas un cache.

Échanger de l’Arazzo

Les scénarios parlent Arazzo, le format de workflows de l’OpenAPI Initiative : l’import accepte les documents 1.0 et 1.1, l’export écrit du 1.1.0 — étapes, outputs, successCriteria et expressions d’exécution du type $response.body#/id. Un workflow d’un document importé (JSON ou YAML) devient un scénario, et ce que le modèle ne sait pas exprimer est listé à l’import, jamais perdu en silence — les constructions que l’app ne sait pas exécuter (workflows imbriqués, actions retry/goto, étapes AsyncAPI) s’affichent avec un badge « support partiel » qui les nomme.

Le menu Export d’une page de scénario offre trois emports : le fichier de scénario, un lien de partage, et le document Arazzo.

Le remettre à votre CI

Chaque page de scénario porte un panneau « Automatiser ce scénario » : choisissez un runner et une plateforme CI, et il génère un job prêt à committer qui exécute le document Arazzo du scénario à intervalle régulier — dans votre CI, avec le runner d’un tiers. Deux runners aujourd’hui, Redocly Respect (npx @redocly/cli respect) et l’Arazzo Runner de Jentic (pip install arazzo-runner) ; deux plateformes, GitHub Actions et GitLab CI.

.github/workflows/create-a-payment.yml

name: Create a payment
on:
  workflow_dispatch:
  schedule:
    - cron: '0 6 * * *'
jobs:
  create-a-payment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Run the workflow
        run: |
          npx @redocly/cli@latest respect arazzo/create-a-payment.arazzo.json \
            --workflow create-payment \
            --input auth.token="$AUTH_TOKEN"
        env:
          AUTH_TOKEN: ${{ secrets.AUTH_TOKEN }}

Le job transporte des noms de variables branchés sur le coffre à secrets de votre CI, jamais des valeurs — le panneau liste les noms à définir, et l’extrait ne contient rien de ce que votre environnement stocke. Un scénario déclaré par url génère un job qui récupère le document servi (curl -fsSL …) : le fichier vous appartient, rien à committer, rien à tenir à jour.

Avant la copie, le panneau nomme ce qui pourrait ne pas survivre au voyage : Respect annonce lire Arazzo 1.0.1, un document 1.1 reçoit donc un avertissement de version plus un par construction (les Selector Objects avec lesquels 1.1 extrait ses valeurs) ; l’Arazzo Runner n’annonce aucune révision, et le panneau le dit exactement plutôt que de deviner. Un document écrit à la main reçoit sa propre note d’honnêteté — il peut décrire plus que ce que cette documentation exécute.

Le panneau fonctionne aussi sur vos scénarios locaux, pas seulement les déclarés. Et la frontière est énoncée dans le produit lui-même : « Cette documentation reste une page statique — elle ne planifie rien et n’exécute rien à votre place. » Le job GitHub se réveille chaque jour (0 6 * * * — ajustez le cron) ; côté GitLab, la planification vit dans CI/CD → Schedules. features: { "ci": false } retire le panneau — l’export Arazzo reste.

Ou tout débrancher

features: { "scenarios": false } retire la fonctionnalité en entier — section de nav, boutons de capture, carte d’accueil, routes, index de recherche. Les scénarios locaux déjà dans le navigateur du lecteur restent en base, intacts, pour le jour où elle est réactivée.