Tests

Tests

OpenClaw dispose de trois suites Vitest (unit/integration, e2e, live) et d’un petit ensemble de runners Docker.

Ce document est un guide « comment nous testons » :

• Ce que couvre chaque suite (et ce qu’elle ne couvre pas délibérément)
• Quelles commandes exécuter pour les workflows courants (local, pre-push, débogage)
• Comment les tests live découvrent les identifiants et sélectionnent les modèles/providers
• Comment ajouter des régressions pour les problèmes réels de modèle/provider

Démarrage rapide

La plupart des jours :

• Porte complète (attendue avant le push) : pnpm build && pnpm check && pnpm test

Lorsque vous touchez aux tests ou souhaitez une confiance supplémentaire :

• Porte de couverture : pnpm test:coverage
• Suite E2E : pnpm test:e2e

Lors du débogage de vrais providers/modèles (nécessite de vrais identifiants) :

• Suite Live (modèles + sondes d’outil/image de passerelle) : pnpm test:live

Astuce : lorsque vous n’avez besoin que d’un seul cas d’échec, privilégiez le rétrécissement des tests live via les variables d’environnement de liste autorisée décrites ci-dessous.

Suites de tests (ce qui s’exécute où)

Considérez les suites comme un « réalisme croissant » (et une instabilité/coût croissants) :

Unité / intégration (par défaut)

• Commande : pnpm test
• Config : vitest.config.ts
• Fichiers : src/**/*.test.ts
• Portée :
  • Tests unitaires purs
  • Tests d’intégration en processus (auth passerelle, routage, outils, analyse, config)
  • Régressions déterministes pour les bugs connus
• Attentes :
  • S’exécute dans la CI
  • Aucune vraie clé requise
  • Doit être rapide et stable

E2E (smoke passerelle)

• Commande : pnpm test:e2e
• Config : vitest.e2e.config.ts
• Fichiers : src/**/*.e2e.test.ts
• Portée :
  • Comportement de bout en bout de la passerelle multi-instance
  • Surfaces WebSocket/HTTP, appariement de nœuds et réseau plus lourd
• Attentes :
  • S’exécute dans la CI (lorsqu’elle est activée dans le pipeline)
  • Aucune vraie clé requise
  • Plus de pièces mobiles que les tests unitaires (peut être plus lent)

Live (vrais providers + vrais modèles)

• Commande : pnpm test:live
• Config : vitest.live.config.ts
• Fichiers : src/**/*.live.test.ts
• Par défaut : activé par pnpm test:live (définit OPENCLAW_LIVE_TEST=1)
• Portée :
  • « Ce provider/model fonctionne-t-il réellement aujourd’hui avec de vraies identifiants ? »
  • Détecter les changements de format du provider, les bizarreries de l’appel d’outils, les problèmes d’authentification et le comportement des limites de taux
• Attentes :
  • Pas stable en CI par conception (réseaux réels, politiques réelles des providers, quotas, pannes)
  • Coûte de l’argent / utilise les limites de taux
  • Privilégiez l’exécution de sous-ensembles réduits plutôt que de « tout »
  • Les exécutions Live sourceront ~/.profile pour récupérer les clés API manquantes
  • Rotation de la clé Anthropic : définissez OPENCLAW_LIVE_ANTHROPIC_KEYS="sk-...,sk-..." (ou OPENCLAW_LIVE_ANTHROPIC_KEY=sk-...) ou plusieurs vars ANTHROPIC_API_KEY* ; les tests réessaieront en cas de limites de taux

Quelle suite dois-je exécuter ?

Utilisez ce tableau de décision :

• Modification de la logique/tests : exécutez pnpm test (et pnpm test:coverage si vous avez beaucoup modifié)
• Toucher au réseau Gateway / protocole WS / appairage : ajoutez pnpm test:e2e
• Débogage de « mon bot est en panne » / échecs spécifiques au provider / appel d’outils : exécutez un pnpm test:live réduit

Live : smoke du model (clés de profil)

Les tests Live sont divisés en deux couches afin que nous puissions isoler les échecs :

• « Direct model » nous indique si le provider/model peut répondre du tout avec la clé donnée.
• « Smoke Gateway » nous indique si le pipeline complet gateway+agent fonctionne pour ce model (sessions, historique, outils, stratégie de bac à sable, etc.).

Couche 1 : achèvement direct du model (pas de Gateway)

• Test : src/agents/models.profiles.live.test.ts
• Objectif :
  • Énumérer les models découverts
  • Utilisez getApiKeyForModel pour sélectionner les models pour lesquels vous avez des identifiants
  • Exécuter un petit achèvement par model (et des régressions ciblées si nécessaire)
• Comment activer :
  • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 si vous appelez Vitest directement)
• Définissez OPENCLAW_LIVE_MODELS=modern (ou all, alias pour modern) pour exécuter réellement cette suite ; sinon, elle est ignorée pour garder pnpm test:live concentré sur le test de fumée du gateway
• Comment sélectionner les models :
  • OPENCLAW_LIVE_MODELS=modern pour exécuter la liste d’autorisation moderne (Opus/Sonnet/Haiku 4.5, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.1, Grok 4)
  • OPENCLAW_LIVE_MODELS=all est un alias pour la liste d’autorisation moderne
  • ou OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,..." (liste d’autorisation par virgule)
• Comment sélectionner les providers :
  • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (liste d’autorisation par virgule)
• D’où viennent les clés :
  • Par défaut : magasin de profils et replis d’env
  • Définissez OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 pour appliquer uniquement le magasin de profils
• Pourquoi cela existe :
  • Sépare « l’API du provider est cassée / la clé est invalide » de « le pipeline de l’agent du gateway est cassé »
  • Contient de petites régressions isolées (exemple : flux de rejeu de raisonnement OpenAI Responses/Codex Responses + appels d’outils)

Couche 2 : Gateway + test de fumée de l’agent de développement (ce que fait réellement « @openclaw »)

• Test : src/gateway/gateway-models.profiles.live.test.ts
• Objectif :
  • Lancer un gateway en cours de processus
  • Créer/patcher une session agent:dev:* (remplacement du model par exécution)
  • Parcourir les models avec clés et vérifier :
    • réponse « significative » (pas d’outils)
    • un appel d’outil réel fonctionne (sonde de lecture)
    • sondes d’outils supplémentaires facultatives (sonde exec+lecture)
    • les chemins de régression OpenAI (appel d’outil uniquement → suivi) continuent de fonctionner
• Détails des sondes (afin que vous puissiez expliquer rapidement les échecs) :
  • sonde read : le test écrit un fichier nonce dans l’espace de travail et demande à l’agent de le read et de renvoyer le nonce.
  • sonde exec+read : le test demande à l’agent d’exec-écrire un nonce dans un fichier temporaire, puis de le read.
  • sonde d’image : le test joint un PNG généré (chat + code aléatoire) et s’attend à ce que le model renvoie cat <CODE>.
  • Référence de mise en œuvre : src/gateway/gateway-models.profiles.live.test.ts et src/gateway/live-image-probe.ts.
• Comment activer :
  • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 si vous invoquez Vitest directement)
• Comment sélectionner les modèles :
  • Par défaut : liste d’autorisation moderne (Opus/Sonnet/Haiku 4.5, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.1, Grok 4)
  • OPENCLAW_LIVE_GATEWAY_MODELS=all est un alias pour la liste d’autorisation moderne
  • Ou définissez OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (ou une liste séparée par des virgules) pour restreindre
• Comment sélectionner les fournisseurs (évitez « OpenRouter tout ») :
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (liste d’autorisation séparée par des virgules)
• Les sondages d’outil et d’image sont toujours activés dans ce test en direct :
  • Sondage read + sondage exec+read (stress de l’outil)
  • le sondage d’image s’exécute lorsque le modèle annonce la prise en charge des entrées d’image
  • Flux (niveau élevé) :
    • Le test génère un minuscule PNG avec « CAT » + code aléatoire (src/gateway/live-image-probe.ts)
    • L’envoie via agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
    • Le Gateway analyse les pièces jointes en images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
    • L’agent intégré transmet un message utilisateur multimodal au modèle
    • Assertion : la réponse contient cat + le code (tolérance OCR : erreurs mineures autorisées)

Astuce : pour voir ce que vous pouvez tester sur votre machine (et les ids provider/model exacts), lancez :

openclaw models list
openclaw models list --json

En direct : test de fumée du setup-token Anthropic

• Test : src/agents/anthropic.setup-token.live.test.ts
• Objectif : vérifier que le setup-token CLI de Claude Code (ou un profil setup-token collé) peut compléter une invite Anthropic.
• Activer :
  • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 si vous invoquez Vitest directement)
  • OPENCLAW_LIVE_SETUP_TOKEN=1
• Sources de jeton (en choisir une) :
  • Profil : OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
  • Jeton brut : OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...
• Remplacement du modèle (facultatif) :
  • OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-5

Exemple de configuration :

openclaw models auth paste-token --provider anthropic --profile-id anthropic:setup-token-test
OPENCLAW_LIVE_SETUP_TOKEN=1 OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test pnpm test:live src/agents/anthropic.setup-token.live.test.ts

En direct : test de fumée du backend CLI (Claude Code CLI ou autres CLI locaux)

• Test : src/gateway/gateway-cli-backend.live.test.ts
• Objectif : valider le pipeline Gateway + agent en utilisant un backend CLI local, sans toucher à votre configuration par défaut.
• Activer :
  • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 si vous appelez Vitest directement)
  • OPENCLAW_LIVE_CLI_BACKEND=1
• Valeurs par défaut :
  • Modèle : claude-cli/claude-sonnet-4-5
  • Commande : claude
  • Args : ["-p","--output-format","json","--dangerously-skip-permissions"]
• Remplacements (optionnels) :
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-5"
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2-codex"
  • OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"
  • OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","json","--permission-mode","bypassPermissions"]'
  • OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1 pour envoyer une vraie pièce jointe image (les chemins sont injectés dans le prompt).
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" pour passer les chemins des fichiers image en tant qu’arguments CLI au lieu de l’injection de prompt.
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (ou "list") pour contrôler comment les arguments d’image sont passés quand IMAGE_ARG est défini.
  • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 pour envoyer un second tour et valider le flux de reprise.
• OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0 pour garder la configuration MCP du CLI Claude Code activée (par défaut, désactive la configuration MCP avec un fichier temporaire vide).

Exemple :

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-5" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

Recettes live recommandées

Les listes d’autorisation étroites et explicites sont les plus rapides et les moins instables :

• Modèle unique, direct (pas de passerelle) :

  • OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts

• Modèle unique, smoke de passerelle :

  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

• Appel d’outils sur plusieurs fournisseurs :

  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-flash-preview,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

• Focus Google (clé API Gemini + Antigravity) :

  • Gemini (clé API) : OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • Antigravity (OAuth) : OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Notes :

• google/... utilise l’API Gemini (clé API).
• google-antigravity/... utilise le pont OAuth Antigravity (point de terminaison d’agent style Cloud Code Assist).
• google-gemini-cli/... utilise le CLI Gemini local sur votre machine (authentification séparée + particularités des outils).
• API Gemini vs CLI Gemini :
  • API : OpenClaw appelle l’API Gemini hébergée par Google via HTTP (clé API / auth profil) ; c’est ce que la plupart des utilisateurs entendent par « Gemini ».
  • CLI : OpenClaw fait appel à un binaire gemini local ; il possède sa propre authentification et peut se comporter différemment (streaming/support des outils/décalage de version).

Live : matrice de modèles (ce que nous couvrons)

Il n’y a pas de « liste de modèles CI » fixe (live est optionnel), mais ce sont les modèles recommandés à couvrir régulièrement sur une machine de développement avec des clés.

Ensemble de test de fumée moderne (appel d’outils + image)

C’est l’exécution des « modèles courants » que nous nous attendons à voir fonctionner :

• OpenAI (non-Codex) : openai/gpt-5.2 (optionnel : openai/gpt-5.1)
• OpenAI Codex : openai-codex/gpt-5.2 (optionnel : openai-codex/gpt-5.2-codex)
• Anthropic : anthropic/claude-opus-4-5 (ou anthropic/claude-sonnet-4-5)
• Google (Gemini API) : google/gemini-3-pro-preview et google/gemini-3-flash-preview (éviter les anciens modèles Gemini 2.x)
• Google (Antigravity) : google-antigravity/claude-opus-4-5-thinking et google-antigravity/gemini-3-flash
• Z.AI (GLM) : zai/glm-4.7
• MiniMax : minimax/minimax-m2.1

Exécuter le test de fumée de la passerelle avec outils + image : OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Référence : appel d’outils (Read + Exec optionnel)

Choisissez au moins un par famille de provider :

• OpenAI : openai/gpt-5.2 (ou openai/gpt-5-mini)
• Anthropic : anthropic/claude-opus-4-5 (ou anthropic/claude-sonnet-4-5)
• Google : google/gemini-3-flash-preview (ou google/gemini-3-pro-preview)
• Z.AI (GLM) : zai/glm-4.7
• MiniMax : minimax/minimax-m2.1

Couverture supplémentaire optionnelle (la bienvenue) :

• xAI : xai/grok-4 (ou la plus récente disponible)
• Mistral : mistral/… (choisissez un modèle « outils » capable que vous avez activé)
• Cerebras : cerebras/… (si vous y avez accès)
• LM Studio : lmstudio/… (local ; l’appel d’outils dépend du mode API)

Vision : envoi d’image (pièce jointe → message multimodal)

Incluez au moins un modèle compatible avec les images dans OPENCLAW_LIVE_GATEWAY_MODELS (variantes de Claude/Gemini/OpenAI compatibles avec la vision, etc.) pour tester la sonde d’image.

Agrégateurs / passerelles alternatives

Si vous avez des clés activées, nous prenons également en charge les tests via :

• OpenRouter : openrouter/... (centaines de modèles ; utilisez openclaw models scan pour trouver des candidats compatibles avec les outils et les images)
• OpenCode Zen : opencode/... (auth via OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)

D’autres fournisseurs que vous pouvez inclure dans la matrice en direct (si vous avez des identifiants/config) :

• Intégrés : openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, xai, groq, cerebras, mistral, github-copilot
• Via models.providers (points de terminaison personnalisés) : minimax (cloud/API), ainsi que tout proxy compatible OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.)

Conseil : n’essayez pas de coder en dur « tous les modèles » dans la documentation. La liste faisant autorité est tout ce que discoverModels(...) renvoie sur votre machine + toutes les clés disponibles.

Identifiants (ne jamais valider)

Les tests en direct découvrent les identifiants de la même manière que le CLI. Conséquences pratiques :

• Si le CLI fonctionne, les tests en direct devraient trouver les mêmes clés.

• Si un test en direct indique « no creds », débuguez de la même manière que vous débugueriez openclaw models list / la sélection du modèle.

• Magasin de profils : ~/.openclaw/credentials/ (préféré ; ce que signifie « clés de profil » dans les tests)

• Config : ~/.openclaw/openclaw.json (ou OPENCLAW_CONFIG_PATH)

Si vous souhaitez compter sur les clés d’environnement (par ex. exportées dans votre ~/.profile), exécutez les tests locaux après source ~/.profile, ou utilisez les runners Docker ci-dessous (ils peuvent monter ~/.profile dans le conteneur).

Deepgram live (transcription audio)

• Test : src/media-understanding/providers/deepgram/audio.live.test.ts
• Activer : DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

Runners Docker (vérifications optionnelles « fonctionne sous Linux »)

Ceux-ci exécutent pnpm test:live à l’intérieur de l’image Docker du dépôt, en montant votre répertoire de config local et votre espace de travail (et en sourçant ~/.profile si monté) :

• Modèles directs : pnpm test:docker:live-models (script : scripts/test-live-models-docker.sh)
• Gateway + agent dev : pnpm test:docker:live-gateway (script : scripts/test-live-gateway-models-docker.sh)
• Assistant d’intégration (TTY, échafaudage complet) : pnpm test:docker:onboard (script : scripts/e2e/onboard-docker.sh)
• Réseau Gateway (deux conteneurs, auth WS + santé) : pnpm test:docker:gateway-network (script : scripts/e2e/gateway-network-docker.sh)
• Plugins (chargement d’extension personnalisé + smoke du registre) : pnpm test:docker:plugins (script : scripts/e2e/plugins-docker.sh)

Variables d’environnement utiles :

• OPENCLAW_CONFIG_DIR=... (défaut : ~/.openclaw) monté sur /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (défaut : ~/.openclaw/workspace) monté sur /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... (défaut : ~/.profile) monté sur /home/node/.profile et sourcé avant l’exécution des tests
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... pour restreindre l’exécution
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 pour s’assurer que les identifiants proviennent du magasin de profils (pas de l’env)

Sanité de la documentation

Exécutez les vérifications de documentation après les modifications : pnpm docs:list.

Régression hors ligne (sûr pour CI)

Il s’agit de régressions de « vrai pipeline » sans vrais fournisseurs :

• Appel d’outil Gateway (mock OpenAI, vraie boucle gateway + agent) : src/gateway/gateway.tool-calling.mock-openai.test.ts
• Assistant de configuration Gateway (WS wizard.start/wizard.next, écriture de la config + auth appliquée) : src/gateway/gateway.wizard.e2e.test.ts

Évaluations de fiabilité de l’agent (Skills)

Nous avons déjà quelques tests compatibles CI qui se comportent comme des « évaluations de fiabilité de l’agent » :

• Appel d’outil simulé via la véritable boucle Gateway + agent (src/gateway/gateway.tool-calling.mock-openai.test.ts).
• Flux de bout en bout de l’assistant qui valident le câblage de session et les effets de la configuration (src/gateway/gateway.wizard.e2e.test.ts).

Ce qui manque encore pour les Skills (voir Skills) :

• Prise de décision : lorsque les Skills sont répertoriés dans le prompt, l’agent choisit-il le bon Skill (ou évite-t-il ceux non pertinents) ?
• Conformité : l’agent lit-il SKILL.md avant utilisation et suit-il les étapes/arguments requis ?
• Contrats de workflow : scénarios multi-tours qui vérifient l’ordre des outils, la conservation de l’historique de session et les limites du bac à sable.

Les futures évaluations doivent d’abord rester déterministes :

• Un exécuteur de scénarios utilisant des fournisseurs simulés pour vérifier les appels d’outils + l’ordre, la lecture des fichiers Skills et le câblage de session.
• Une petite suite de scénarios axés sur les Skills (utilisation vs évitement, restriction, injection de prompt).
• Évaluations en direct optionnelles (opt-in, limitées par l’environnement) uniquement après la mise en place de la suite compatible CI.

Ajout de régressions (conseils)

Lorsque vous corrigez un problème de fournisseur/modèle découvert en direct :

• Ajoutez une régression compatible CI si possible (fournisseur simulé/bouchon, ou capturez la transformation exacte de la forme de la requête)
• Si c’est intrinsèquement uniquement en direct (limites de débit, stratégies d’auth), gardez le test en direct ciblé et optionnel via des variables d’environnement
• Privilégiez le ciblage de la plus petite couche qui détecte le bogue :
  • bogue de conversion/relecture de requête fournisseur → test direct des modèles
  • bogue de pipeline session/historique/outil de la Gateway → test de fumée en direct de la Gateway ou test simulé compatible CI de la Gateway