O modo de agente do GitHub Copilot é um ciclo: ele edita arquivos, executa comandos de terminal, lê a saída e decide o que fazer a seguir. Então, por que seus testes de API não estão nesse ciclo? Eles ficam no Apidog atrás de uma GUI, executados quando alguém se lembra de clicar. O Copilot nunca os toca.
A solução é um arquivo 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 o Copilot saiba que ela existe, o modo de agente 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 do npm, o login e a primeira execução, com um agente fazendo a digitação. Este artigo assume que `apidog --version` imprime um número e sua conta Apidog está autenticada.
Sobre qual Copilot estamos falando
Copilot é vários produtos, e o nome se sobrepõe de maneiras confusas. Este artigo é sobre as interfaces que podem executar comandos de shell.
O principal é o **modo de agente no VS Code**. Você abre a visualização do Copilot Chat, muda o menu suspenso de modo para Agente, e ele pode editar vários arquivos, executar comandos de terminal e iterar até que a tarefa seja concluída. Quando ele quer executar um comando, ele mostra o comando e pede confirmação antes de executar. Esse passo de confirmação é exatamente onde `apidog run` se encaixa.
Duas interfaces relacionadas merecem ser mencionadas para que você saiba em qual delas você está. O **agente de codificação do Copilot** executa assincronamente em GitHub Actions depois que você atribui uma issue a ele; ele produz um pull request em vez de trabalhar no seu editor. A **CLI do Copilot** é um cliente de terminal separado. Ambos podem executar comandos, mas este artigo foca no modo de agente no VS Code, porque é onde você trabalha enquanto codifica e onde o ciclo de edição-teste-correção é mais apertado. A configuração abaixo também funciona para o agente de codificação, que lê o mesmo arquivo de instruções. Para uma visão mais ampla do que mudou quando o Copilot se tornou agêntico, veja o novo agente de codificação do GitHub Copilot.
A distinção é importante porque o Copilot tem sua própria maneira de aprender as regras do projeto, e esse mecanismo transforma um “execute meus testes” avulso em algo que o Copilot busca por conta própria. Esse mecanismo é um arquivo de instruções personalizado.
Passo 1: Adicione as regras do Apidog ao arquivo de instruções do Copilot
O Copilot lê instruções personalizadas do repositório de um único arquivo: `.github/copilot-instructions.md` na raiz do seu repositório. O modo de agente, o Copilot Chat, a revisão de código e o agente de codificação carregam-no automaticamente, de acordo com a documentação do GitHub sobre instruções personalizadas de repositório. Pense nisso como `CLAUDE.md` para Claude Code ou `AGENTS.md` para Codex: um arquivo Markdown simples de instruções de projeto que o Copilot puxa para o contexto antes de começar a trabalhar.
Crie o arquivo e adicione um pequeno bloco do Apidog:
## Teste de API com a CLI do Apidog
Quando você altera um endpoint de API, verifique-o com a CLI do Apidog antes
de declarar a tarefa concluída. Execute:
apidog run -t 812345 -e 671234 -r cli
- `apidog run` sai com 0 quando todas as asserções passam, e com um valor diferente de zero em caso de qualquer falha.
Trate uma saída diferente de zero como um teste falho, mesmo que o texto do resumo pareça bom.
- A máquina já está autenticada via `apidog login`. NÃO adicione um
parâmetro `--access-token` e nunca coloque um token neste arquivo.
- Se você encontrar um erro de "opção desconhecida", execute `apidog run --help` e use as
opções reais. Não tente adivinhar.
Substitua os valores de `-t` e `-e` pelos IDs reais do seu cenário e ambiente da próxima etapa.
Escreva-o no arquivo de instruções em vez de mencioná-lo no chat porque um ID de cenário digitado no chat desaparece quando a sessão termina. Um em `.github/copilot-instructions.md` estará lá para cada colega de equipe, cada sessão em modo de agente e cada pull request que o agente de codificação abrir a partir de agora. Se você quiser que a regra se aplique apenas a certos arquivos, o GitHub também oferece suporte a instruções específicas de caminho em `.github/instructions/NAME.instructions.md`, mas um único arquivo em todo o repositório é suficiente aqui.
Passo 2: Obtenha o comando do Apidog
Você não precisa escrever o comando `apidog run` manualmente. O Apidog o gera para você.
Abra o cenário de teste no Apidog, vá para a aba **CI/CD** e copie o comando. Ele vem totalmente formado com o ID correto do cenário (`-t`), ID do ambiente (`-e`) e um parâmetro de relatório:
apidog run -t 812345 -e 671234 -r cli
Cole esses IDs exatos no bloco em seu `.github/copilot-instructions.md`. Esses IDs são a fonte da verdade; quando o Copilot e seu arquivo de instruções discordam, a aba CI/CD prevalece. Para o conjunto completo de parâmetros e relatórios, consulte a referência do comando apidog run.
Passo 3: Faça o modo de agente executar o teste
Abra a visualização do Copilot Chat no VS Code e mude o menu suspenso de modo para **Agente**. Como o modo de agente carrega `.github/copilot-instructions.md` ao iniciar, ele já sabe que a CLI está lá. Faça uma alteração que afete sua API, ou pergunte diretamente:
Run the Apidog API test scenario and tell me the result.
O Copilot emite o comando `apidog run` do seu arquivo de instruções. O modo de agente não executa comandos de terminal silenciosamente; ele mostra o comando e pede sua confirmação antes de executar, para que você veja exatamente o que está prestes a ser executado. Aprove. O relatório `-r cli` então imprime um resultado passo a passo e um resumo diretamente no terminal integrado, onde você acompanha cada requisição e asserção à medida que acontecem.
Você quer ver duas coisas: a execução do teste e o Copilot reportando tanto o resumo quanto o código de saída. Se você aprovar o comando uma vez, o VS Code pode lembrar sua escolha para esse comando no workspace, então chamadas posteriores de `apidog run` serão executadas sem solicitar novamente. Um cenário de teste somente leitura contra o ambiente de staging é exatamente o tipo de comando seguro e dentro do workspace que pode ser permitido.
Passo 4: Leia o relatório dentro do Copilot
Quando um teste falha (fica vermelho), o relatório tem a resposta. Com `-r cli`, o Copilot obtém um detalhamento legível no terminal: cada requisição, cada asserção e qual delas falhou com o valor esperado versus o valor real. A asserção falha nomeia o campo exato ou o código de status, o que geralmente é suficiente para o Copilot encontrar a correção em sua próxima iteração.
Para um relatório que você pode abrir em um navegador ou entregar a um colega de equipe, adicione o relatório HTML:
apidog run -t 812345 -e 671234 -r cli,html
O relatório `html` escreve um arquivo autossuficiente em `./apidog-reports`. Mantenha `cli` na lista para que o Copilot ainda receba a saída inline que ele lê para decidir seu próximo passo. Para todos os formatos de relatório, incluindo a saída JUnit que os painéis de CI analisam, veja o guia completo da CLI do Apidog e como ler os relatórios de teste da CLI do Apidog.
Copilot testando dentro de seu próprio ciclo
O ponto é o que acontece quando você para de pedir e o Copilot executa o cenário por conta própria porque o arquivo de instruções o instruiu a fazer isso.
Imagine o modo de agente editando um manipulador que constrói uma resposta de checkout. Seu ciclo 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 incorreto), tenta uma correção e reexecuta. O teste de API se torna parte do mesmo ciclo de edição-teste-correção que o Copilot já usa para seus testes de unidade. Você escreveu uma instrução e o Copilot integrou o comando em como ele já funciona.
Este é o modelo de delegar-e-verificar que torna qualquer fluxo de trabalho de agente seguro. O Copilot 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, veja como usar agentes de IA para testes de API e o harness de teste de IA do Apidog.
Verifique se o Copilot está realmente executando a CLI
Agentes reportam sucesso que não conquistaram, e o Copilot não é exceção. Três verificações, na ordem de quão frequentemente elas detectam problemas.
Primeiro, confirme se o comando foi executado. O modo de agente mostra os comandos que ele executou e sua saída inline no terminal. Procure a linha literal `apidog run ...` e um resultado abaixo dela. Se o Copilot 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, aquele que importa:
What was the exit code of that apidog run command?
`apidog run` sai com `0` quando todas as asserções passam e com um valor diferente de zero quando algo falha. Esse comportamento único permite que o Copilot, ou um pipeline, trate a execução como um portão limpo. Quando o texto do Copilot diz “testes passaram”, mas o código de saída é diferente de zero, o código de saída está correto.
Terceiro, confirme que ele usou o cenário real. Se uma execução falhar com “cenário não encontrado”, o Copilot pode ter inventado ou lembrado incorretamente um ID. Verifique novamente os valores de `-t` e `-e` em relação ao seu arquivo de instruções e ao comando que o Apidog gerou na aba CI/CD. Os IDs do Apidog são a verdade.
Opcional: Conecte o servidor MCP do Apidog
Executar `apidog run` a partir do seu arquivo de instruções cobre a maior parte do que você precisa. Para ir um passo além, conecte o servidor MCP do Apidog.
O modo de agente no VS Code lê servidores MCP de um arquivo `.vscode/mcp.json` do workspace na raiz do seu repositório, de acordo com a documentação do GitHub sobre como estender o Copilot com MCP. O servidor MCP do Apidog expõe suas especificações de API via MCP, para que o Copilot possa ler seu esquema enquanto escreve código, não apenas depois do fato. A divisão do trabalho é clara: a CLI executa os testes, e o MCP alimenta o agente com a especificação.
Se você executar o agente de codificação do Copilot em GitHub Actions, sua configuração MCP reside em um local diferente. Você o adiciona como JSON nas Configurações do repositório, na seção Copilot em Cloud agent, com quaisquer segredos armazenados como segredos de Actions prefixados com `COPILOT_MCP_`. O arquivo `.vscode/mcp.json` é para o modo de agente no seu editor.
Quando o Copilot erra
Algumas falhas aparecem frequentemente durante a configuração.
Ele ignora o arquivo de instruções. Se o Copilot executa um comando genérico ou nenhum, o arquivo pode não estar sendo carregado. Confirme que ele está nomeado exatamente `.github/copilot-instructions.md`, que está no diretório `.github` na raiz do seu repositório, e que as instruções personalizadas estão habilitadas nas suas configurações do VS Code. Um caminho errado significa que o Copilot nunca o lê.
Ele passa um token de acesso de qualquer maneira. Se o Copilot tenta adicionar `--access-token`, ele está adivinhando 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 no arquivo de instruções. Para o modelo de autenticação, veja autenticação da CLI do Apidog.
Ele inventa um parâmetro. Um erro de “opção desconhecida” significa que o Copilot adivinhou um parâmetro que sua versão não possui. Peça para ele executar `apidog run --help` e copiar o parâmetro exato de lá, que estará sempre correto para sua versão instalada.
Ele relata uma aprovação em uma execução que falhou. Este é o erro mais custoso, e a razão pela qual a regra do código de saída está tanto no seu arquivo de instruções quanto na sua etapa de verificação. Quando o resumo e o código de saída discordam, o código de saída prevalece.
De um agente diário a um ciclo testado
Essa é a configuração. Instale `apidog-cli` uma vez seguindo o guia de instalação, adicione um pequeno bloco do Apidog ao arquivo `.github/copilot-instructions.md` do seu repositório, e o Copilot saberá como executar seus testes de API e ler o resultado dentro do mesmo ciclo que ele já usa para editar código. Um endpoint quebrado é detectado enquanto o Copilot ainda está trabalhando na alteração, e não depois de ser implantado.
Um teste por trás de uma GUI é executado quando um humano clica; um comando de uma linha é executado sempre que o Copilot 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, adicione seu comando `apidog run` em `.github/copilot-instructions.md`, e veja o Copilot incorporá-lo na próxima alteração. Quando estiver pronto para executar o mesmo comando em um pipeline sem o Copilot presente, A CLI do Apidog no GitHub Actions cobre os segredos, relatórios e o controle por código de saída.