Trae é um loop. Seu agente Builder lê seu repositório, edita arquivos, executa comandos no terminal e lê a saída para decidir o que fazer em seguida. Então, por que seus testes de API não estão nesse loop? Eles ficam no Apidog atrás de uma GUI e são executados quando alguém se lembra de clicar. Seu agente nunca os toca.
A solução é um único bloco de configuração. A CLI do Apidog é um pacote npm, apidog-cli, que executa os cenários de teste que você construiu no Apidog diretamente de um terminal. Uma vez que a CLI esteja instalada e Trae saiba de sua existência, o Builder executa um cenário do Apidog da mesma forma que executa seus testes de unidade: dispara o comando, lê o código de saída, corrige o código se estiver vermelho.
Se você ainda não instalou a CLI, faça isso primeiro. Como instalar a CLI do Apidog com um agente de codificação de IA detalha a instalação npm, autenticação e a primeira execução, com o agente fazendo a digitação. Este artigo assume que apidog --version imprime um número e que sua conta Apidog está autenticada.
Sobre qual Trae estamos falando
Trae é a IDE de IA da ByteDance, construída sobre o VS Code, com um modo de agente chamado Builder que edita arquivos e executa comandos de terminal por conta própria. Você pode ler os detalhes do produto no site oficial do Trae. Este artigo é sobre a IDE de desktop, não sobre o projeto de pesquisa trae-agent autônomo no GitHub. Se você abrir o Trae, vir um painel de chat ao lado do seu editor e puder alternar o agente para Builder, você está no lugar certo.
A distinção importa porque o Trae tem sua própria maneira de aprender as regras do projeto, e esse mecanismo transforma um "executar meus testes" único em algo que o Builder busca por conta própria. Esse mecanismo é um arquivo de regras do projeto. Se você quiser a versão agnóstica de ferramentas deste fluxo de trabalho primeiro, o guia completo da CLI do Apidog cobre a CLI por si só.
Passo 1: Adicionar o arquivo de regras do projeto
Trae lê os arquivos de regras antes que o Builder comece a trabalhar. O arquivo de nível de projeto reside em .trae/rules/project_rules.md na raiz do seu repositório, conforme a documentação de regras do Trae. O Agente carrega essas regras durante a inicialização e as referencia enquanto gera e edita código. Há também um user_rules.md de nível de usuário que se aplica a todos os seus projetos; para este fluxo de trabalho, um arquivo de projeto na raiz do repositório é suficiente.
Crie .trae/rules/project_rules.md e adicione um pequeno bloco que nomeia a CLI, o comando exato do cenário e as regras que mantêm o Builder honesto:
## 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á.
É por isso que você escreve a CLI em project_rules.md em vez de mencioná-la no chat. Um ID de cenário digitado no painel de chat desaparece quando a sessão termina. Um em .trae/rules/project_rules.md está lá para cada colega de equipe e para cada execução do Builder a partir de agora. Trae também lê pastas .trae/rules/ em subdiretórios, então um monorepo pode manter regras por serviço ao lado de cada serviço.
Passo 2: Obter o comando do Apidog
Você não precisa adivinhar o comando. Abra o cenário de teste no Apidog, vá para a aba CI/CD e copie a linha apidog run gerada. Ela já possui o ID real do cenário após -t e o ID do ambiente após -e, então você está colando um comando que o Apidog sabe ser válido, em vez de inventar IDs manualmente.
Insira esses IDs exatos no bloco em .trae/rules/project_rules.md, substituindo os placeholders <scenario_id> e <env_id>. Para o conjunto completo de flags e o que cada um faz, consulte a referência de comandos apidog run.
Passo 3: Fazer o Builder executar o teste
Com o bloco no lugar, mude o agente do Trae para Builder e inicie-o em seu repositório. O Builder carrega project_rules.md durante a inicialização, então ele já sabe que a CLI está lá. Faça uma alteração que afete sua API, ou apenas peça para ele executar a verificação:
Execute o cenário de teste do Apidog e me diga o código de saída.
O Builder emite o comando apidog run do seu arquivo de regras. O modelo de aprovação do Trae é importante aqui: quando o agente quer executar um comando shell, ele recomenda o comando e mostra um botão Executar, e o comando é executado no terminal do Trae somente depois que você clica nele. Uma vez executado, o Builder lê e analisa automaticamente a saída. Então você aprova o apidog run uma vez, e o agente pega o resultado a partir daí.
O relator -r cli imprime um resultado passo a passo e um resumo diretamente no terminal, onde o Builder lê cada requisição e asserção à medida que acontecem. Você quer ver a execução sendo realizada e o Builder reportando tanto o resumo quanto o código de saída.
Passo 4: Ler o relatório dentro do Trae
Quando uma execução fica vermelha, o relatório tem a resposta. Com -r cli, o Builder obtém um detalhamento legível no terminal do Trae: cada requisição, cada asserção e qual falhou com o valor esperado versus o real. A asserção com falha nomeia o campo exato ou o código de status, o que geralmente é suficiente para o Builder encontrar a correção.
Para um relatório que você pode abrir em um navegador ou entregar a um colega de equipe, adicione o relator HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
O relator html escreve um arquivo autocontido em ./apidog-reports. Mantenha cli na lista para que o Builder ainda receba a saída em linha que ele lê para decidir seu próximo passo. Para todos os relatores, incluindo os formatos JSON e JUnit que os painéis de CI analisam, consulte o guia para relatórios de teste da CLI do Apidog.
Testando o Trae dentro de seu próprio loop
O ponto é o que acontece quando você para de pedir e o Builder executa o cenário por conta própria porque project_rules.md o instruiu a fazer isso.
Imagine o Builder editando um handler que constrói uma resposta de checkout. Seu loop muda: ele edita o código, então, em vez de declarar vitória, executa seu cenário Apidog contra o ambiente de staging, lê o código de saída e age sobre ele. Verde, ele segue em frente. Vermelho, ele abre o relatório, lê qual asserção falhou (o código de status, o campo ausente, o valor errado), tenta uma correção e executa novamente. O teste de API se torna parte do mesmo loop de edição-teste-correção que o Builder já usa para seus testes de unidade. Você escreveu uma instrução e o Builder incorporou o comando em como ele já funciona.
Este é o modelo de delegar-então-verificar que torna qualquer fluxo de trabalho de agente seguro. O Builder executa o comando e lê o resultado; você continua criando cenários visualmente no Apidog e verifica se o agente lê os códigos de saída honestamente. Para o padrão mais amplo, consulte como usar agentes de IA para testes de API e o arnes de teste de IA do Apidog.
Verificar se o Trae está realmente executando a CLI
Agentes relatam sucesso que não conquistaram, e o Builder não é exceção. Três verificações, em ordem de quão frequentemente elas detectam problemas.
Primeiro, confirme se o comando foi executado. O Trae mostra os comandos que o Builder executou e a saída deles no terminal. Procure pela linha literal apidog run e um resultado abaixo dela. Se o Builder diz que executou os testes, mas você não vê o comando, ele resumiu algo que nunca fez. Peça para ele executar novamente e mostrar a saída bruta.
Segundo, confirme o código de saída:
Qual foi o código de saída desse comando apidog run?
apidog run sai com 0 quando todas as asserções passam e não zero quando algo falha. Esse comportamento único permite que o Builder, ou um pipeline, trate a execução como um portão limpo. Quando o texto do Builder diz "testes passaram", mas o código de saída não é zero, o código de saída está correto.
Terceiro, confirme se ele usou o cenário real. Se uma execução falhar com "cenário não encontrado", o Builder pode ter inventado ou lembrado mal um ID. Verifique novamente os valores de -t e -e em relação a project_rules.md e o comando que o Apidog gerou na aba CI/CD. Os IDs no seu arquivo de regras são a verdade.
Opcional: conectar o servidor Apidog MCP
Executar apidog run de project_rules.md cobre a maioria do que você precisa. Conectar um servidor MCP vai um passo além. Os agentes do Trae atuam como clientes MCP, então o Builder pode chamar ferramentas que um servidor MCP expõe.
Para adicionar um, abra as configurações do Trae, vá para a aba MCP e escolha um servidor do marketplace ou selecione Adicionar Manualmente e cole um bloco JSON com command, args e env do servidor, conforme o guia do Trae para adicionar servidores MCP. O servidor Apidog MCP expõe suas especificações de API via MCP, para que o Builder possa ler seu esquema enquanto escreve código, e não apenas depois. A divisão do trabalho é clara: a CLI executa os testes, e o MCP alimenta o agente com a especificação.
Quando o Trae erra
Algumas falhas aparecem frequentemente durante a configuração.
Ele ignora o arquivo de regras. Se o Builder executa um comando genérico ou nenhum, o arquivo pode não estar carregando. Confirme se ele está em .trae/rules/project_rules.md na raiz do seu repositório e que a pasta se chama rules, não rule. Reiniciar a sessão força uma nova leitura das regras.
Ele passa um token de acesso de qualquer forma. Se o Builder tentar adicionar --access-token, ele está adivinhando a partir de exemplos públicos. O bloco já o instrui a não fazer isso, já que a máquina está autenticada via apidog login. Reforce a linha e nunca coloque um token real em project_rules.md. Para como a CLI lida com credenciais em uso interativo e em CI, consulte autenticação da CLI do Apidog.
Ele inventa um flag. Um erro de "opção desconhecida" significa que o Builder adivinhou um flag que sua versão não possui. Peça para ele executar apidog run --help e copiar o flag exato de lá, o que é sempre correto para sua versão instalada.
Ele relata um sucesso em uma execução falha. O mais caro, e a razão pela qual a regra do código de saída está no seu project_rules.md e na sua etapa de verificação. Quando o resumo e o código de saída discordam, o código de saída vence.
De um agente diário a um loop testado
Essa é a configuração. Instale apidog-cli uma vez seguindo o guia de instalação, adicione um pequeno bloco do Apidog em .trae/rules/project_rules.md, e o Builder saberá como executar seus testes de API e ler o resultado dentro do mesmo loop que ele já usa para editar código. Um endpoint quebrado é pego enquanto o Builder ainda está trabalhando na mudança, não depois que ela é implementada.
Um teste atrás de uma GUI é executado quando um humano clica; um comando de uma linha é executado sempre que o Builder decide. Você continua construindo cenários visualmente no Apidog, e seu agente os executa onde você não está observando. Baixe o Apidog, construa um cenário, insira seu comando apidog run em .trae/rules/project_rules.md, e veja o Builder pegá-lo na próxima alteração. Quando estiver pronto para executar o mesmo cenário sem a presença de um agente, Apidog CLI no GitHub Actions cobre os segredos, relatores e controle de código de saída para CI.