@openclaw/matrix groupé avec un homeserver Tuwunel jetable dans Docker, avec des comptes temporaires de pilote, de SUT et d’observateur, ainsi que des salons préremplis. C’est la couverture en direct avec transport réel pour Matrix.
Cet outillage est réservé aux mainteneurs. Les versions empaquetées d’OpenClaw omettent intentionnellement qa-lab, donc openclaw qa n’est disponible qu’à partir d’un checkout source. Les checkouts source chargent directement le runner groupé - aucune étape d’installation de plugin n’est nécessaire.
Pour un contexte plus large sur le framework QA, consultez la vue d’ensemble QA.
Démarrage rapide
pnpm openclaw qa matrix exécute --profile all et ne s’arrête pas au premier échec. Utilisez --profile fast --fail-fast pour une porte de validation de release ; partitionnez le catalogue avec --profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli lors de l’exécution de l’inventaire complet en parallèle.
Ce que fait la voie
- Provisionne un homeserver Tuwunel jetable dans Docker (image par défaut
ghcr.io/matrix-construct/tuwunel:v1.5.1, nom de serveurmatrix-qa.test, port28008) derrière un enregistreur borné et expurgateur des requêtes/réponses. - Enregistre trois utilisateurs temporaires -
driver(envoie le trafic entrant),sut(le compte Matrix OpenClaw testé),observer(capture de trafic tiers). - Préremplit les salons requis par les scénarios sélectionnés (principal, fils de discussion, médias, redémarrage, secondaire, liste d’autorisation, E2EE, DM de vérification, etc.).
- Exécute la sonde de protocole
matrix-qa-v1, neutre vis-à-vis du substrat, contre la frontière Tuwunel enregistrée. Les tests unitaires prouvent le contrat de la sonde avec le fixture du protocole Matrix ; l’hôte canonique de l’adaptateur de transport QA réel dans #99707 possède le câblage réel de la cible Crabline. - Démarre un Gateway OpenClaw enfant avec le vrai plugin Matrix limité au compte SUT ;
qa-channeln’est pas chargé dans l’enfant. - Exécute les scénarios en séquence, observe les événements via les clients Matrix driver/observer et déduit les attentes de routage/état à partir du trafic enregistré.
- Arrête le homeserver, écrit le rapport et les artefacts de preuve, puis quitte.
CLI
Indicateurs courants
| Indicateur | Valeur par défaut | Description |
|---|---|---|
--profile <profile> | all | Profil de scénario. Voir Profils. |
--fail-fast | désactivé | S’arrêter après le premier contrôle ou scénario en échec. |
--scenario <id> | - | Exécuter uniquement ce scénario. Répétable. Voir Scénarios. |
--output-dir <path> | <repo>/.artifacts/qa-e2e/matrix-<timestamp> | Emplacement où sont écrits les rapports, le résumé, l’inventaire de routage/état, les événements observés et le journal de sortie. Les chemins relatifs sont résolus par rapport à --repo-root. |
--repo-root <path> | process.cwd() | Racine du dépôt lors de l’appel depuis un répertoire de travail neutre. |
--sut-account <id> | sut | Identifiant du compte Matrix dans la configuration du Gateway QA. |
Indicateurs de fournisseur
La voie utilise un vrai transport Matrix, mais le fournisseur de modèle est configurable :| Indicateur | Valeur par défaut | Description |
|---|---|---|
--provider-mode <mode> | live-frontier | mock-openai pour un routage mock déterministe ou live-frontier pour les fournisseurs frontier en direct. L’ancien alias live-openai fonctionne encore. |
--model <ref> | valeur par défaut du fournisseur | Référence principale provider/model. |
--alt-model <ref> | valeur par défaut du fournisseur | Référence alternative provider/model lorsque les scénarios changent de modèle en cours d’exécution. |
--fast | désactivé | Activer le mode rapide du fournisseur lorsque pris en charge. |
--credential-source ni --credential-role. La voie provisionne localement des utilisateurs jetables ; il n’existe pas de pool d’identifiants partagé à louer.
Profils
Le profil sélectionné décide quels scénarios s’exécutent.| Profil | À utiliser pour |
|---|---|
all (par défaut) | Catalogue complet. Lent mais exhaustif. |
fast | Sous-ensemble de porte de validation de release qui exerce le contrat de transport en direct : canary, filtrage des mentions, blocage par liste d’autorisation, forme de réponse, reprise après redémarrage, suivi de fil, isolation de fil, observation des réactions et livraison des métadonnées d’approbation exec. |
transport | Scénarios de niveau transport pour les fils de discussion, DM, salons, autojoin, mentions/listes d’autorisation, approbations et réactions. |
media | Couverture des pièces jointes image, audio, vidéo, PDF et EPUB. |
e2ee-smoke | Couverture E2EE minimale - réponse chiffrée de base, suivi de fil, réussite du bootstrap. |
e2ee-deep | Scénarios exhaustifs E2EE de perte d’état, sauvegarde, clés et récupération. |
e2ee-cli | Scénarios CLI openclaw matrix encryption setup et verify * pilotés via le harnais QA. |
extensions/qa-matrix/src/runners/contract/scenario-catalog.ts.
Scénarios
La liste complète des identifiants de scénario est l’unionMatrixQaScenarioId dans extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15. Les catégories incluent :
- fils de discussion -
matrix-thread-*,matrix-subagent-thread-spawn - niveau supérieur / DM / salon -
matrix-top-level-reply-shape,matrix-room-*,matrix-dm-* - streaming et progression des outils -
matrix-room-partial-streaming-preview,matrix-room-quiet-streaming-preview,matrix-room-tool-progress-*,matrix-room-block-streaming - médias -
matrix-media-type-coverage,matrix-room-image-understanding-attachment,matrix-attachment-only-ignored,matrix-unsupported-media-safe - routage -
matrix-room-autojoin-invite,matrix-secondary-room-* - réactions -
matrix-reaction-* - approbations -
matrix-approval-*(métadonnées exec/plugin, fallback fragmenté, réactions de refus, fils et routagetarget: "both") - redémarrage et rejeu -
matrix-restart-*,matrix-stale-sync-replay-dedupe,matrix-room-membership-loss,matrix-homeserver-restart-resume,matrix-initial-catchup-then-incremental - filtrage des mentions, bot-à-bot et listes d’autorisation -
matrix-mention-*,matrix-allowbots-*,matrix-allowlist-*,matrix-multi-actor-ordering,matrix-inbound-edit-*,matrix-mxid-prefixed-command-block,matrix-observer-allowlist-override - E2EE -
matrix-e2ee-*(réponse de base, suivi de fil, bootstrap, cycle de vie de clé de récupération, variantes de perte d’état, comportement de sauvegarde serveur, hygiène des appareils, vérification SAS / QR / DM, redémarrage, expurgation des artefacts) - CLI E2EE -
matrix-e2ee-cli-*(configuration du chiffrement, configuration idempotente, échec du bootstrap, cycle de vie de clé de récupération, multi-compte, aller-retour de réponse Gateway, auto-vérification)
--scenario <id> (répétable) pour exécuter un ensemble choisi manuellement ; combinez avec --profile all pour ignorer le filtrage par profil.
Variables d’environnement
| Variable | Par défaut | Effet |
|---|---|---|
OPENCLAW_QA_MATRIX_TIMEOUT_MS | 1800000 (30 min) | Limite supérieure stricte pour toute l’exécution. |
OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS | 45000 | Limite pour la réponse canary initiale. La CI de publication l’augmente sur les runners partagés afin qu’un premier tour Gateway lent n’échoue pas avant le début de la couverture des scénarios. |
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS | 8000 | Fenêtre silencieuse pour les assertions négatives d’absence de réponse. Plafonnée à ≤ le délai d’expiration de l’exécution. |
OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS | 90000 | Limite pour le démontage Docker. Les surfaces d’échec incluent la commande de récupération docker compose ... down --remove-orphans. |
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE | ghcr.io/matrix-construct/tuwunel:v1.5.1 | Remplace l’image du serveur d’accueil lors de la validation avec une autre version de Tuwunel. |
OPENCLAW_QA_MATRIX_PROGRESS | activé | 0 masque les lignes de progression [matrix-qa] ... sur stderr. 1 les force. |
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT | expurgé | 1 conserve le corps du message et formatted_body dans matrix-qa-observed-events.json. Par défaut, ils sont expurgés pour garder les artefacts de CI sûrs. |
OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT | désactivé | 1 ignore le process.exit déterministe après l’écriture des artefacts. Par défaut, la sortie est forcée, car les handles crypto natifs de matrix-js-sdk peuvent garder la boucle d’événements active après la fin des artefacts. |
OPENCLAW_RUN_NODE_OUTPUT_LOG | non défini | Lorsqu’il est défini par un lanceur externe (par exemple scripts/run-node.mjs), la QA Matrix réutilise ce chemin de journal au lieu de démarrer son propre tee. |
Artefacts de sortie
Écrits dans--output-dir :
matrix-qa-report.md- rapport de protocole Markdown (ce qui a réussi, échoué, été ignoré, et pourquoi).matrix-qa-summary.json- résumé structuré adapté à l’analyse par la CI et aux tableaux de bord.matrix-qa-route-state-manifest.json- inventaire dynamiquematrix-qa-v1indexé par identifiant de scénario. Il enregistre les formes de route/corps expurgées, l’ordre des requêtes, les nouvelles tentatives observées, les erreurs, la continuité des sync-token, ainsi que les familles d’état d’appareil/clé/média/sauvegarde observées pendant cette exécution. C’est une preuve exécutable, pas une référence enregistrée dans le dépôt.matrix-qa-observed-events.json- événements Matrix observés depuis les clients pilote et observateur. Les corps sont expurgés sauf siOPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1; les métadonnées d’approbation sont résumées avec certains champs sûrs et un aperçu tronqué de la commande.matrix-qa-output.log- stdout/stderr combinés de l’exécution. SiOPENCLAW_RUN_NODE_OUTPUT_LOGest défini, le journal du lanceur externe est réutilisé à la place.
<repo>/.artifacts/qa-e2e/matrix-<timestamp> afin que les exécutions successives ne s’écrasent pas mutuellement.
Conseils de triage
- L’exécution se bloque près de la fin : les handles crypto natifs de
matrix-js-sdkpeuvent survivre au harness. Par défaut, unprocess.exitpropre est forcé après l’écriture des artefacts ; si vous avez désactivéOPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1, attendez-vous à ce que le processus reste actif. - Erreur de nettoyage : cherchez la commande de récupération affichée (une invocation
docker compose ... down --remove-orphans) et exécutez-la manuellement pour libérer le port du serveur d’accueil. - Fenêtres d’assertion négative instables en CI : réduisez
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS(8 s par défaut) lorsque la CI est rapide ; augmentez-le sur les runners partagés lents. - Besoin de corps expurgés pour un rapport de bug : relancez avec
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1et joignezmatrix-qa-observed-events.json. Traitez l’artefact obtenu comme sensible. - Version différente de Tuwunel : faites pointer
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGEvers la version testée. La lane vérifie uniquement l’image par défaut épinglée.
Contrat de transport en direct
Matrix est l’une des trois lanes de transport en direct (Matrix, Telegram, Discord) qui partagent une checklist de contrat unique définie dans Vue d’ensemble QA → Couverture du transport en direct.qa-channel reste la suite synthétique large et ne fait volontairement pas partie de cette matrice.
Liens connexes
- Vue d’ensemble QA - pile QA globale et contrat de transport en direct
- Canal QA - adaptateur de canal synthétique pour les scénarios adossés au dépôt
- Tests - exécuter les tests et ajouter une couverture QA
- Matrix - le Plugin de canal testé