# Écrits en cliquant, livrés avec la doc. > Écrire des scénarios ApiGlow sans toucher au JSON : capture depuis la console, chaînage en cliquant la réponse, livraison via la config, remise à votre CI. > > Source: https://apiglow.dev/fr/docs/scenarios/index.md Un scénario est une séquence de requêtes nommée et rejouable, entièrement déclarative. Il n'y a de crochet de scripting nulle part, et c'est 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é](/fr/features/workbench/). ## Capturer, pas rédiger Envoyez une requête dans la [console d'essai](/fr/features/workbench/), puis choisissez « 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é, donc il n'y a pas 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 antérieure 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. Avant tout envoi, le panneau des prérequis répond à « pourquoi ça va échouer » : variables manquantes, credentials absents, et é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 : - **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. C'est permis même sous `environmentsLocked`, parce que la config gouverne la structure de l'environnement plutôt que 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, et un lien vers l'historique par étape. « Pas à pas » charge chaque étape dans la vraie console d'essai et laisse le lecteur envoyer, ce qui transforme un scénario écrit en tutoriel interactif. Dans les deux modes, une variable manquante bloque l'étape, et le `{{littéral}}` n'est jamais envoyé. ## Le livrer avec la doc Exportez le scénario en fichier JSON, committez-le, et déclarez-le : ```json { "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. L'exception est 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](/fr/docs/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 : ```json { "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 aucune valeur sensible : les credentials restent des `{{var}}` d'environnement. 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 — plutôt que d'évincer un ancien. ## É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` sont couverts. Un workflow d'un document importé, JSON ou YAML, devient un scénario. Ce que le modèle ne sait pas exprimer est listé à l'import plutôt que perdu : 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 une par une. 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`) — et deux plateformes, **GitHub Actions** et **GitLab CI**. ```yaml {title=".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 …`) : il n'y a rien à committer et rien à tenir à jour. Avant la copie, le panneau nomme ce qui pourrait ne pas survivre au voyage. Respect annonce lire Arazzo 1.0.1, donc un document 1.1 reçoit un avertissement de version plus un par construction, pour les Selector Objects avec lesquels 1.1 extrait ses valeurs. L'Arazzo Runner n'annonce aucune révision, et le panneau le dit exactement. Un document écrit à la main reçoit sa propre note : 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. 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. ## 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.