openclaw-qa-testing

Testes de QA do OpenClaw

Use esta skill para trabalhos com qa-lab / qa-channel. Apenas QA local ao repositório.

Leia primeiro

• docs/concepts/qa-e2e-automation.md
• docs/help/testing.md
• docs/channels/qa-channel.md
• qa/README.md
• qa/scenarios/index.yaml
• extensions/qa-lab/src/suite.ts
• extensions/qa-lab/src/character-eval.ts

Política de modelo

• Execuções normais de suíte ao vivo usam os padrões conscientes de origem e autenticação do QA Lab.
• Não passe --model, --alt-model ou --fast por padrão. A omissão de --fast não significa que rápido está desabilitado; o comportamento rápido é de propriedade da origem.
• Para execuções específicas de cenário, o execution.summary completo é autoritativo e substitui a orientação padrão genérica, inclusive quando requer outras flags. Adicione pinagens explícitas de provedor/modelo apenas quando execution.config.requiredProvider ou requiredModel as exigir.

Fluxo de trabalho padrão

1. Leia o pacote de cenários e a implementação atual da suíte.
2. Decida a pista:
   • mock/dev: mock-openai
   • validação real: live-frontier
3. Para uma suíte ao vivo normal, use:

pnpm openclaw qa suite \
  --provider-mode live-frontier \
  --output-dir .artifacts/qa-e2e/run-all-live-frontier-<tag>

4. Monitore as saídas:
   • resumo: .artifacts/qa-e2e/run-all-live-frontier-<tag>/qa-suite-summary.json
   • relatório: .artifacts/qa-e2e/run-all-live-frontier-<tag>/qa-suite-report.md
5. Se o usuário quiser monitorar a UI ao vivo, encontre a porta de escuta atual do openclaw-qa e informe http://127.0.0.1:<porta>.
6. Se um cenário falhar, corrija a causa raiz do produto ou do harness e reexecute a pista completa.

Teste rápido de OTEL

Para validação local de OpenTelemetry no QA-lab, use:

pnpm qa:otel:smoke

Isso inicia um receptor local de traces OTLP/HTTP, executa o cenário otel-trace-smoke através do qa-channel, decodifica os spans protobuf emitidos e verifica os nomes de trace exportados e o contrato de privacidade. Não requer Opik, Langfuse ou credenciais de coletor externo.

Credenciais de QA e 1Password

• Use op apenas dentro do tmux para busca de secrets de QA neste repositório.
• Verificação rápida de autenticação dentro do tmux:

op account list

• Resolva as referências aprovadas de item e campo do 1Password para:
  • OPENCLAW_QA_CONVEX_SITE_URL
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER para a função de mantenedor
  • OPENCLAW_QA_CONVEX_SECRET_CI para a função de CI
• Se uma referência necessária estiver ausente ou desatualizada, pergunte ao mantenedor/operador qual é a referência atual de item e campo. Não peça valores de secrets no chat nem os copie para logs ou artefatos de prova.
• A pista Docker do npm Telegram requer leasing de credenciais Convex. O lease fornece o bot SUT do Test Server, autorização de usuário de QA e metadados de grupo de teste definidos pelo Telegram E2E userbot. Variáveis diretas de token do Telegram não substituem a configuração necessária do Convex.
• Carregue a URL do site aprovada e o secret específico da função no ambiente do comando através da fonte de secret aprovada. O pré-voo requer a URL do site e o secret da função correspondente antes da execução do Docker.
• Com a configuração de mantenedor carregada, execute:

OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex \
OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=maintainer \
OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE=mock-openai \
OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC="openclaw@beta" \
pnpm test:docker:npm-telegram-live

• scripts/e2e/npm-telegram-live-runner.ts lê OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE, não OPENCLAW_QA_PROVIDER_MODE.
• Para prova hospedada autorizada, use a pista manual existente quando seu ambiente qa-live-shared tiver configuração Convex de CI válida. Um dispatch não provisiona credenciais nem contorna uma recusa de credencial.

ghx workflow run "NPM Telegram Beta E2E" --repo openclaw/openclaw --ref main \
  -f [email protected] \
  -f [email protected] \
  -f provider_mode=mock-openai

• Monitore o ID de execução exato a partir da URL de dispatch. gh run view --json artifacts não é suportado; liste artefatos com:

gh api repos/openclaw/openclaw/actions/runs/<run-id>/artifacts

Credenciais ao vivo do WhatsApp

Use isso ao configurar ou substituir credenciais Convex kind=whatsapp.

• Trate as credenciais de QA do WhatsApp como contas ao vivo de propriedade do operador, não fixtures geradas.
• Use dois números de teste dedicados com capacidade WhatsApp: uma conta driver e uma conta SUT. Não use números pessoais ou contas pessoais do OpenClaw WhatsApp no pool compartilhado.
• Registre e vincule cada conta manualmente com o WhatsApp ou WhatsApp Business, armazenando a autenticação web apenas em diretórios de autenticação locais isolados fora do repositório.
• Para cobertura de grupo, crie um grupo de teste dedicado que inclua ambas as contas de QA e armazene seu JID como groupJid; caso contrário, o cenário de verificação de menção em grupo deve ser pulado por padrão e falhar quando solicitado explicitamente.
• Empacote os dois diretórios de autenticação Baileys em campos de payload .tgz codificados em base64 e adicione uma nova linha de credencial Convex ativa. Prefira adicionar uma nova linha e desabilitar linhas antigas/quebradas em vez de sobrescrever credenciais no local.
• Campos de payload esperados: driverPhoneE164, sutPhoneE164, driverAuthArchiveBase64, sutAuthArchiveBase64 e groupJid opcional.
• Mantenha o material de credencial fora do repositório, logs, PRs e screenshots. Redija números de telefone a menos que o operador peça explicitamente depuração local.
• Valide com pnpm openclaw qa whatsapp --credential-source convex --credential-role maintainer --provider-mode mock-openai e preserve caminhos de artefatos mais resumos aprovados/ reprovados com dados redigidos.
• Se o WhatsApp expirar ou invalidar uma sessão web vinculada, religue localmente, empacote novos arquivos de autenticação, adicione uma nova linha Convex e desabilite a linha antiga.

Avaliações de personagem

Use qa character-eval para verificações de estilo/persona/vibe em vários modelos ao vivo.

pnpm openclaw qa character-eval \
  --output-dir .artifacts/qa-e2e/character-eval-<tag>

• Executa processos filhos do gateway de QA local, não Docker.
• O pnpm build empacotado omite QA Lab + qa-channel por design (apenas checkout da fonte). Para exercitar openclaw qa/qa-channel a partir de um dist construído, compile com OPENCLAW_BUILD_PRIVATE_QA=1 pnpm build (emite dist/plugin-sdk/qa-lab.js, qa-runtime.js, dist/extensions/{qa-lab,qa-channel}) ou execute via pnpm dev.
• Sem flags de modelo, a avaliação de personagem usa seus padrões atuais definidos pela fonte para candidato, juiz, pensamento e rápido.
• Repita --model provider/model,thinking=<nivel>[,fast|,no-fast|,fast=<bool>] ou --judge-model ... apenas para substituir o inventário correspondente explicitamente.
• Não adicione novos exemplos com --model-thinking separado; mantenha essa flag apenas como compatibilidade legada.
• O relatório inclui classificação do juiz, estatísticas de execução, durações e transcrições completas; não inclua respostas brutas do juiz. A duração é contexto de benchmark, não um sinal de avaliação.
• A concorrência de candidato e juiz padrão é 16. Use --concurrency <n> e --judge-concurrency <n> para substituir quando gateways locais ou limites de provedor precisarem de uma pista mais suave.
• A fonte do cenário é apenas YAML em qa/scenarios/: use index.yaml e arquivos *.yaml por cenário com title, scenario no nível superior e flow opcional. Nunca adicione arquivos Markdown com fences qa-scenario / qa-flow.
• Para avaliações isoladas de personagem/persona, escreva a persona em SOUL.md e deixe IDENTITY.md em branco no fluxo do cenário. Use SOUL.md + IDENTITY.md apenas ao testar intencionalmente como a identidade normal do OpenClaw se combina com o personagem.
• Mantenha os prompts naturais e formatados como tarefas. O modelo candidato deve receber a configuração do personagem através de SOUL.md, depois turnos normais de usuário como chat, ajuda no workspace e pequenas tarefas de arquivo; não pergunte "como você reagiria?" nem diga ao modelo que está em uma avaliação.
• Prefira pelo menos uma tarefa real, como criar ou editar um pequeno artefato no workspace, para que a transcrição capture o personagem sob uso normal de ferramentas, em vez de puro roleplay.

Pista de modelo Codex CLI

Use refs de modelo no formato codex-cli/<codex-model> sempre que o QA precisar exercitar o Codex como backend de modelo.

Exemplos:

pnpm openclaw qa suite \
  --provider-mode live-frontier \
  --model codex-cli/<codex-model> \
  --alt-model codex-cli/<codex-model> \
  --scenario <scenario-id> \
  --output-dir .artifacts/qa-e2e/codex-<tag>

pnpm openclaw qa manual \
  --model codex-cli/<codex-model> \
  --message "Reply exactly: CODEX_OK"

• Trate o nome concreto do modelo Codex como entrada do usuário/configuração; não o codifique na fonte, exemplos de docs ou cenários.
• O QA ao vivo preserva CODEX_HOME para que a autenticação/configuração do Codex CLI funcione enquanto mantém HOME e OPENCLAW_HOME em sandbox.
• O QA mock deve limpar CODEX_HOME.
• Se o Codex retornar texto de fallback/autenticação a cada turno, primeiro verifique CODEX_HOME, a autenticação relevante baseada em secret e os logs filhos do gateway antes de alterar as asserções do cenário.
• Para comparação de modelos, inclua codex-cli/<codex-model> como outro candidato em qa character-eval; o relatório deve rotulá-lo como um nome de modelo opaco.

Fatos do repositório

• Cenários semente estão em qa/scenarios/index.yaml e qa/scenarios/<tema>/*.yaml.
• Runner principal ao vivo: extensions/qa-lab/src/suite.ts
• Servidor do QA lab: extensions/qa-lab/src/lab-server.ts
• Harness do gateway filho: extensions/qa-lab/src/gateway-child.ts
• Canal sintético: extensions/qa-channel/

Como é "pronto"

• Suíte completa verde para a pista solicitada.
• O usuário recebe:
  • URL de monitoramento, se aplicável
  • contagens de aprovações/reprovações
  • caminhos de artefatos
  • nota concisa sobre o que foi corrigido

Padrões comuns de falha

• Tempo limite ao vivo muito curto:
  • aumente as esperas ao vivo em extensions/qa-lab/src/suite.ts
• Descoberta não encontra arquivos do repositório:
  • aponte prompts para repo/... dentro do workspace semeado
• Prova do subagente muito frágil:
  • prefira evidência estável de resposta final em vez de listagem transitória de sessão filha
• Atraso de "reconstrução" do harness:
  • árvore suja pode acionar uma compilação pré-execução; espere isso antes dos portos aparecerem

Ao adicionar cenários

• Adicione ou atualize YAML de cenário em qa/scenarios/; não adicione arquivos .md de cenário ou blocos YAML com fence.
• Mantenha as expectativas de início em qa/scenarios/index.yaml alinhadas.
• Adicione cobertura executável em extensions/qa-lab/src/suite.ts.
• Prefira asserções ponta a ponta a verificações apenas com mock.
• Salve saídas em .artifacts/qa-e2e/.