Como usar o Apidog CLI no Trae

Trae funciona em loop: o agente Builder lê o repositório, edita arquivos, executa comandos no terminal e usa a saída para decidir o próximo passo. Seus testes de API devem fazer parte desse mesmo ciclo. Com a CLI do Apidog, você executa os cenários criados na interface do Apidog diretamente no terminal, permitindo que o Builder valide alterações, interprete o código de saída e corrija falhas antes de concluir uma tarefa.

Experimente o Apidog hoje

A CLI é distribuída como o pacote npm apidog-cli. Depois de instalada e registrada nas regras do projeto, o Builder pode executar um cenário da mesma forma que executa testes unitários: chama o comando, verifica o código de saída e trata uma execução não zero como falha.

Antes de continuar, confirme que a CLI está instalada e autenticada:

apidog --version

Se ainda não concluiu essa etapa, siga o guia Como instalar a CLI do Apidog com um agente de codificação de IA. Este artigo parte do princípio de que apidog --version retorna uma versão e que sua conta já foi autenticada.

Sobre qual Trae estamos falando

Trae é a IDE de IA da ByteDance, baseada em VS Code. Seu modo de agente, Builder, pode editar arquivos e propor comandos para execução no terminal. Consulte os detalhes no site oficial do Trae.

Este fluxo usa a IDE desktop, não o projeto autônomo trae-agent no GitHub. Se você vê o painel de chat no editor e pode selecionar o agente Builder, está usando a versão correta.

A integração depende das regras de projeto do Trae. Em vez de repetir instruções no chat a cada sessão, você registra o comando de teste em um arquivo versionado no repositório. Para uma visão independente de IDE, consulte o guia completo da CLI do Apidog.

Passo 1: criar as regras do projeto

O Trae carrega regras antes de o Builder começar a trabalhar. Para regras compartilhadas pelo repositório, crie este arquivo na raiz:

.trae/rules/project_rules.md

Conforme a documentação de regras do Trae, também existe um user_rules.md global. Para garantir que a configuração acompanhe o projeto e seja usada por toda a equipe, prefira project_rules.md.

Crie o arquivo e adicione este bloco:

## Teste de API com a CLI do Apidog

Quando você alterar o código que afeta um endpoint de API, verifique-o executando o
cenário de teste do Apidog, não apenas os testes de unidade.

Comando:
  apidog run -t <scenario_id> -e <env_id> -r cli

Regras:
- `apidog run` sai com 0 quando todas as asserções passam e não zero em caso de falha.
  Trate um código de saída não zero como um teste com falha, mesmo que o resumo pareça bom.
- Esta máquina já está autenticada via `apidog login`. Nunca adicione um
  flag --access-token e nunca coloque um token neste arquivo.
- Se um flag for desconhecido, execute `apidog run --help` e use o flag exato de lá.

Esse arquivo evita que o Builder dependa do contexto temporário do chat. O ID do cenário e o comando ficam disponíveis em novas sessões, para outros desenvolvedores e para futuras execuções do agente.

Em monorepos, você também pode manter regras específicas por serviço em diretórios .trae/rules/ dentro de cada subprojeto.

Passo 2: copiar o comando gerado pelo Apidog

Não preencha os IDs manualmente. No Apidog:

1. Abra o cenário de teste.
2. Acesse a aba CI/CD.
3. Copie a linha apidog run gerada.
4. Cole os valores reais de -t e -e em .trae/rules/project_rules.md.

O resultado deve seguir este formato:

apidog run -t <scenario_id> -e <env_id> -r cli

Use os IDs fornecidos pelo Apidog para evitar erros como cenário inexistente ou ambiente incorreto. Para consultar todas as opções disponíveis, veja a referência do comando apidog run.

Passo 3: executar o cenário com o Builder

Com as regras configuradas:

1. Abra o repositório no Trae.
2. Selecione o agente Builder.
3. Faça uma alteração que afete um endpoint.
4. Peça explicitamente a validação, se necessário:

Execute o cenário de teste do Apidog e me diga o código de saída.

O Builder usa o comando definido no arquivo de regras. Quando ele solicita a execução de um comando shell, o Trae mostra o comando e um botão Executar. Após sua aprovação, o comando é executado no terminal integrado e o Builder pode analisar a saída.

Mantenha o relator cli:

apidog run -t <scenario_id> -e <env_id> -r cli

Ele imprime requisições, asserções e o resumo diretamente no terminal, onde o Builder pode interpretar o resultado.

Passo 4: interpretar o relatório

Quando o cenário falhar, use a saída do terminal para localizar a causa. Com -r cli, o relatório informa:

• a requisição executada;
• as asserções avaliadas;
• a asserção que falhou;
• o valor esperado e o valor recebido;
• o código de saída do processo.

Se precisar compartilhar ou abrir o relatório no navegador, inclua o relator HTML:

apidog run -t <scenario_id> -e <env_id> -r cli,html

O relator html cria um arquivo autocontido em ./apidog-reports. Mantenha cli na lista para que o Builder continue recebendo a saída textual no terminal.

Para formatos adicionais, como JSON e JUnit para pipelines de CI, consulte o guia de relatórios de teste da CLI do Apidog.

Colocar o Trae no loop de teste

Depois dessa configuração, o Builder pode seguir um loop prático de edição, teste e correção:

1. Edita um handler ou serviço.
2. Detecta que a alteração afeta um endpoint.
3. Executa o cenário configurado com apidog run.
4. Verifica o código de saída.
5. Se o resultado for 0, continua a tarefa.
6. Se o resultado for diferente de 0, lê a asserção com falha, corrige o código e executa novamente.

Por exemplo, ao alterar um handler que monta a resposta de checkout, o Builder pode executar o cenário contra o ambiente de staging, identificar um status HTTP incorreto ou um campo ausente e repetir o teste após a correção.

O ponto central é delegar a execução ao agente, mas verificar evidências: comando executado, saída bruta e código de saída. Para aprofundar esse padrão, veja como usar agentes de IA para testes de API e o arnês de teste de IA do Apidog.

Verificar se o Trae executou a CLI de verdade

Não aceite apenas um resumo textual do agente. Faça estas três verificações.

1. Confirme o comando no terminal

Procure a linha literal apidog run no terminal do Trae e confira se há saída logo abaixo dela.

Se o Builder disser que executou os testes, mas o comando não aparecer no histórico do terminal, peça uma nova execução e solicite a saída bruta.

2. Confirme o código de saída

Pergunte diretamente:

Qual foi o código de saída desse comando apidog run?

O comportamento esperado é:

• 0: todas as asserções passaram;
• diferente de 0: pelo menos uma asserção falhou.

Se o resumo disser que os testes passaram, mas o código de saída for diferente de zero, trate a execução como falha. O código de saída é o sinal confiável para o Builder e para pipelines de CI.

3. Confirme os IDs do cenário e do ambiente

Se aparecer um erro como “cenário não encontrado”, valide os argumentos usados:

apidog run -t <scenario_id> -e <env_id> -r cli

Compare os valores de -t e -e com:

• o conteúdo de .trae/rules/project_rules.md;
• o comando gerado pelo Apidog na aba CI/CD.

Os IDs copiados do Apidog devem ser a fonte de verdade.

Opcional: conectar o servidor Apidog MCP

A CLI cobre a execução dos testes. Um servidor MCP complementa esse fluxo ao disponibilizar a especificação da API para o agente durante a implementação.

Os agentes do Trae atuam como clientes MCP. Para adicionar um servidor:

1. Abra as configurações do Trae.
2. Acesse a aba MCP.
3. Escolha um servidor no marketplace ou selecione Adicionar Manualmente.
4. Informe o bloco JSON do servidor com command, args e env.

Consulte o guia do Trae para adicionar servidores MCP.

O servidor Apidog MCP expõe especificações de API via MCP. Na prática, a divisão fica clara:

• CLI do Apidog: executa cenários e retorna resultados;
• Apidog MCP: fornece contexto de especificação para o Builder enquanto ele escreve código.

Solução de problemas

O Builder ignora o arquivo de regras

Confirme o caminho e o nome do diretório:

.trae/rules/project_rules.md

Verifique se a pasta se chama rules, e não rule. Se necessário, reinicie a sessão do Builder para forçar o carregamento das regras.

O Builder tenta usar --access-token

Se o Builder adicionar --access-token, ele provavelmente está seguindo exemplos genéricos. Reforce a regra de que a máquina já está autenticada com:

apidog login

Nunca coloque tokens reais em project_rules.md. Para entender credenciais em uso local e CI, consulte o guia de autenticação da CLI do Apidog.

O Builder inventa uma flag

Se o comando falhar com “opção desconhecida”, peça ao agente para consultar a versão instalada:

apidog run --help

Depois, use exatamente a flag listada nessa saída.

O Builder relata sucesso em uma execução falha

Quando o resumo visual e o código de saída discordarem, o código de saída vence. Mantenha essa regra explícita no project_rules.md para que o Builder trate corretamente qualquer execução não zero.

De agente diário a loop testado

A configuração é simples:

1. Instale apidog-cli seguindo o guia de instalação.
2. Autentique a máquina com apidog login.
3. Crie .trae/rules/project_rules.md.
4. Cole o comando apidog run gerado pelo Apidog.
5. Instrua o Builder a executar cenários de API sempre que alterar endpoints.

Assim, uma alteração quebrada pode ser detectada enquanto o Builder ainda trabalha nela, e não depois que a implementação foi considerada concluída.

Você continua criando cenários visualmente no Apidog, enquanto o Trae os executa no loop de desenvolvimento. Baixe o Apidog, crie um cenário, adicione o comando ao arquivo de regras e valide a próxima alteração de API com o Builder.

Para executar os mesmos cenários em automação sem um agente, consulte Apidog CLI no GitHub Actions.