@openclaw/matrix incluído contra um homeserver Tuwunel descartável no Docker, com contas temporárias de driver, SUT e observador, além de salas semeadas. Ela é a cobertura real, com transporte ao vivo, para Matrix.
Esta é uma ferramenta exclusiva para mantenedores. As versões empacotadas do OpenClaw omitem intencionalmente qa-lab, então openclaw qa só está disponível a partir de um checkout do código-fonte. Checkouts do código-fonte carregam o executor incluído diretamente - nenhuma etapa de instalação de Plugin é necessária.
Para um contexto mais amplo do framework de QA, consulte visão geral de QA.
Início rápido
pnpm openclaw qa matrix simples executa --profile all e não para na primeira falha. Use --profile fast --fail-fast para um gate de release; divida o catálogo com --profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli ao executar todo o inventário em paralelo.
O que a linha faz
- Provisiona um homeserver Tuwunel descartável no Docker (imagem padrão
ghcr.io/matrix-construct/tuwunel:v1.5.1, nome do servidormatrix-qa.test, porta28008) atrás de um gravador limitado de solicitações/respostas com redação. - Registra três usuários temporários -
driver(envia tráfego de entrada),sut(a conta Matrix do OpenClaw em teste),observer(captura de tráfego de terceiros). - Semeia as salas exigidas pelos cenários selecionados (principal, threads, mídia, reinicialização, secundária, lista de permissões, E2EE, DM de verificação etc.).
- Executa a sonda de protocolo
matrix-qa-v1, neutra em relação ao substrato, contra o limite Tuwunel gravado. Testes unitários comprovam o contrato da sonda com o fixture de protocolo Matrix; o host canônico do adaptador de transporte de QA em #99707 é responsável pela fiação real do alvo Crabline. - Inicia um Gateway filho do OpenClaw com o Plugin Matrix real restrito à conta SUT;
qa-channelnão é carregado no filho. - Executa cenários em sequência, observando eventos por meio dos clientes Matrix driver/observer e derivando expectativas de rota/estado a partir do tráfego gravado.
- Encerra o homeserver, grava artefatos de relatório e evidências, então sai.
CLI
Flags comuns
| Flag | Padrão | Descrição |
|---|---|---|
--profile <profile> | all | Perfil de cenário. Consulte Perfis. |
--fail-fast | desativado | Para após a primeira verificação ou cenário com falha. |
--scenario <id> | - | Executa apenas este cenário. Repetível. Consulte Cenários. |
--output-dir <path> | <repo>/.artifacts/qa-e2e/matrix-<timestamp> | Onde relatórios, resumo, inventário de rota/estado, eventos observados e o log de saída são gravados. Caminhos relativos são resolvidos em relação a --repo-root. |
--repo-root <path> | process.cwd() | Raiz do repositório ao invocar a partir de um diretório de trabalho neutro. |
--sut-account <id> | sut | ID da conta Matrix dentro da configuração do Gateway de QA. |
Flags de provedor
A linha usa um transporte Matrix real, mas o provedor de modelo é configurável:| Flag | Padrão | Descrição |
|---|---|---|
--provider-mode <mode> | live-frontier | mock-openai para despacho mock determinístico ou live-frontier para provedores frontier ao vivo. O alias legado live-openai ainda funciona. |
--model <ref> | padrão do provedor | Ref principal provider/model. |
--alt-model <ref> | padrão do provedor | Ref alternativa provider/model quando cenários alternam no meio da execução. |
--fast | desativado | Habilita o modo rápido do provedor quando houver suporte. |
--credential-source nem --credential-role. A linha provisiona usuários descartáveis localmente; não há pool de credenciais compartilhado para reservar.
Perfis
O perfil selecionado decide quais cenários serão executados.| Perfil | Use para |
|---|---|
all (padrão) | Catálogo completo. Lento, mas exaustivo. |
fast | Subconjunto de gate de release que exercita o contrato de transporte ao vivo: canário, gate de menção, bloqueio por lista de permissões, formato de resposta, retomada após reinicialização, continuação de thread, isolamento de thread, observação de reação e entrega de metadados de aprovação de exec. |
transport | Cenários em nível de transporte para threads, DM, sala, autoentrada, menção/lista de permissões, aprovação e reações. |
media | Cobertura de anexos de imagem, áudio, vídeo, PDF e EPUB. |
e2ee-smoke | Cobertura mínima de E2EE - resposta criptografada básica, continuação de thread, sucesso de bootstrap. |
e2ee-deep | Cenários exaustivos de perda de estado, backup, chave e recuperação de E2EE. |
e2ee-cli | Cenários da CLI openclaw matrix encryption setup e verify * executados pelo harness de QA. |
extensions/qa-matrix/src/runners/contract/scenario-catalog.ts.
Cenários
A lista completa de IDs de cenário é a uniãoMatrixQaScenarioId em extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15. As categorias incluem:
- threads -
matrix-thread-*,matrix-subagent-thread-spawn - nível superior / DM / sala -
matrix-top-level-reply-shape,matrix-room-*,matrix-dm-* - streaming e progresso de ferramenta -
matrix-room-partial-streaming-preview,matrix-room-quiet-streaming-preview,matrix-room-tool-progress-*,matrix-room-block-streaming - mídia -
matrix-media-type-coverage,matrix-room-image-understanding-attachment,matrix-attachment-only-ignored,matrix-unsupported-media-safe - roteamento -
matrix-room-autojoin-invite,matrix-secondary-room-* - reações -
matrix-reaction-* - aprovações -
matrix-approval-*(metadados de exec/Plugin, fallback em partes, reações de negação, threads e roteamentotarget: "both") - reinicialização e repetição -
matrix-restart-*,matrix-stale-sync-replay-dedupe,matrix-room-membership-loss,matrix-homeserver-restart-resume,matrix-initial-catchup-then-incremental - gate de menção, bot-para-bot e listas de permissões -
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-*(resposta básica, continuação de thread, bootstrap, ciclo de vida de chave de recuperação, variantes de perda de estado, comportamento de backup do servidor, higiene de dispositivo, verificação SAS / QR / DM, reinicialização, redação de artefatos) - CLI de E2EE -
matrix-e2ee-cli-*(configuração de criptografia, configuração idempotente, falha de bootstrap, ciclo de vida da chave de recuperação, múltiplas contas, ida e volta de resposta do Gateway, autoverificação)
--scenario <id> (repetível) para executar um conjunto escolhido manualmente; combine com --profile all para ignorar o gate de perfil.
Variáveis de ambiente
| Variável | Padrão | Efeito |
|---|---|---|
OPENCLAW_QA_MATRIX_TIMEOUT_MS | 1800000 (30 min) | Limite superior rígido para toda a execução. |
OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS | 45000 | Limite para a resposta canário inicial. A CI de lançamento aumenta isso em executores compartilhados para que um primeiro turno lento do Gateway não falhe antes do início da cobertura de cenários. |
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS | 8000 | Janela silenciosa para asserções negativas de ausência de resposta. Limitada a ≤ o tempo limite da execução. |
OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS | 90000 | Limite para o desmonte do Docker. As superfícies de falha incluem o comando de recuperação docker compose ... down --remove-orphans. |
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE | ghcr.io/matrix-construct/tuwunel:v1.5.1 | Sobrescreve a imagem do servidor doméstico ao validar contra uma versão diferente do Tuwunel. |
OPENCLAW_QA_MATRIX_PROGRESS | ativado | 0 silencia as linhas de progresso [matrix-qa] ... em stderr. 1 as força a ficar ativadas. |
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT | redigido | 1 mantém o corpo da mensagem e formatted_body em matrix-qa-observed-events.json. O padrão redige para manter os artefatos de CI seguros. |
OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT | desativado | 1 pula o process.exit determinístico após a gravação do artefato. O padrão força a saída porque os manipuladores de criptografia nativa do matrix-js-sdk podem manter o loop de eventos ativo após a conclusão do artefato. |
OPENCLAW_RUN_NODE_OUTPUT_LOG | não definido | Quando definido por um iniciador externo (por exemplo, scripts/run-node.mjs), o QA do Matrix reutiliza esse caminho de log em vez de iniciar seu próprio tee. |
Artefatos de saída
Gravados em--output-dir:
matrix-qa-report.md- Relatório de protocolo em Markdown (o que passou, falhou, foi ignorado e por quê).matrix-qa-summary.json- Resumo estruturado adequado para análise por CI e dashboards.matrix-qa-route-state-manifest.json- Inventário dinâmicomatrix-qa-v1indexado por id de cenário. Ele registra formas redigidas de rota/corpo, ordenação de solicitações, novas tentativas observadas, erros, continuidade de token de sincronização e famílias de estado de dispositivo/chave/mídia/backup observadas durante essa execução. Isso é evidência executável, não uma linha de base versionada.matrix-qa-observed-events.json- Eventos Matrix observados dos clientes de driver e observador. Corpos são redigidos, a menos queOPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1; metadados de aprovação são resumidos com campos seguros selecionados e prévia de comando truncada.matrix-qa-output.log- stdout/stderr combinados da execução. SeOPENCLAW_RUN_NODE_OUTPUT_LOGestiver definido, o log do iniciador externo será reutilizado.
<repo>/.artifacts/qa-e2e/matrix-<timestamp>, para que execuções sucessivas não sobrescrevam umas às outras.
Dicas de triagem
- A execução trava perto do fim: os manipuladores de criptografia nativa do
matrix-js-sdkpodem sobreviver ao harness. O padrão força umprocess.exitlimpo após a gravação do artefato; se você removeu a definição deOPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1, espere que o processo continue ativo por algum tempo. - Erro de limpeza: procure o comando de recuperação impresso (uma invocação
docker compose ... down --remove-orphans) e execute-o manualmente para liberar a porta do servidor doméstico. - Janelas de asserção negativa instáveis na CI: reduza
OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS(padrão 8 s) quando a CI estiver rápida; aumente-o em executores compartilhados lentos. - Precisa de corpos redigidos para um relatório de bug: execute novamente com
OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1e anexematrix-qa-observed-events.json. Trate o artefato resultante como sensível. - Versão diferente do Tuwunel: aponte
OPENCLAW_QA_MATRIX_TUWUNEL_IMAGEpara a versão em teste. A lane verifica apenas a imagem padrão fixada.
Contrato de transporte ao vivo
Matrix é uma das três lanes de transporte ao vivo (Matrix, Telegram, Discord) que compartilham uma única lista de verificação de contrato definida em Visão geral de QA → Cobertura de transporte ao vivo.qa-channel continua sendo a suíte sintética ampla e intencionalmente não faz parte dessa matriz.
Relacionados
- Visão geral de QA - pilha geral de QA e contrato de transporte ao vivo
- Canal de QA - adaptador de canal sintético para cenários respaldados pelo repositório
- Testes - executar testes e adicionar cobertura de QA
- Matrix - o Plugin de canal em teste