O Agente do Cursor já edita arquivos, executa seu terminal, lê a saída e corrige o que quebrou. O próximo passo é colocar seus testes de API nesse ciclo: deixe o Cursor executar seus cenários reais do Apidog, ler o sucesso ou falha e continuar. O componente que faz isso funcionar é um executor de linha de comando que o Cursor pode chamar.
Esse executor é o Apidog CLI, um pacote npm chamado apidog-cli. Ele executa os cenários de teste que você construiu visualmente no Apidog a partir de um terminal e sai com um código de status que o Cursor pode usar. Este guia aborda a parte específica do Cursor: o arquivo de regra que ensina ao Cursor seu fluxo de trabalho, o prompt que executa um teste, como a execução se integra ao seu ciclo de editar-testar-corrigir, e o servidor MCP opcional que fornece ao Cursor sua especificação de API enquanto ele codifica.
Se o CLI ainda não estiver instalado, comece com como instalar o Apidog CLI com um agente de codificação de IA, que orienta o Cursor na instalação e autenticação. Volte assim que apidog --version imprimir um número. Você também precisa de uma conta Apidog com pelo menos um cenário de teste salvo. Baixe o Apidog se você não tiver um.
O que significa "usar o CLI no Cursor"
Não há um plugin Apidog para o Cursor, e você não precisa de um. O Agente do Cursor já executa comandos de shell no terminal do seu projeto. Portanto, usar o Apidog CLI no Cursor significa três coisas:
- Ensine o fluxo de trabalho ao Cursor uma vez com uma regra de projeto, para que ele saiba o comando, as flags e que o código de saída é a fonte da verdade.
- Faça o Agente executar
apidog runcomo uma etapa normal em seu ciclo, assim como ele executa seus testes de unidade. - Opcionalmente, conecte o servidor Apidog MCP, para que o Cursor possa ler sua especificação de API enquanto escreve o código que esses testes verificam.
A regra é o que torna isso específico do Cursor, em vez de um guia genérico de "abrir um terminal e digitar".
Passo 1: Adicionar uma regra de projeto
O Cursor lê as regras do projeto a partir de um diretório .cursor/rules na raiz do seu repositório. Cada regra é um arquivo .mdc com um pequeno bloco de frontmatter, versionado junto com seu código para que toda a equipe obtenha o mesmo comportamento.
Crie um de duas maneiras: digite /create-rule no chat e descreva o que você quer, ou abra Configurações do Cursor > Regras, Comandos, clique em + Adicionar Regra. De qualquer forma, você obterá um arquivo em .cursor/rules.
Salve isso como .cursor/rules/apidog-cli.mdc:
---
description: Como executar testes de API do Apidog a partir do terminal
alwaysApply: false
---
# Executando testes de API do Apidog
Este projeto possui cenários de teste de API no Apidog. Execute-os com o
apidog-cli, que está instalado globalmente e já autenticado.
- O comando é `apidog run`. O binário é `apidog`.
- Execute um único cenário por ID: `apidog run -t <scenarioId> -e <environmentId> -n 1 -r cli`
- `-t` é o ID do cenário de teste, `-e` é o ID do ambiente.
- `-n 1` o executa uma vez. `-r cli` imprime um relatório legível no terminal.
- Não passe `--access-token`. A autenticação é feita por um `apidog login` anterior.
- O código de saída é a fonte da verdade: `0` significa que todas as asserções passaram,
diferente de zero significa uma falha. Relate o código de saída, não apenas um resumo.
- Se uma flag for desconhecida, execute `apidog run --help` e use a flag exata de lá.
Nunca adivinhe nomes de flags.
- Após alterar o código que afeta um endpoint, execute o cenário relevante
e leia o resultado antes de afirmar que a alteração funciona.
O frontmatter importa. description mais alwaysApply: false torna esta uma regra de aplicação inteligente: o Cursor a utiliza quando o chat é sobre a execução de testes, em vez de queimar contexto em todas as conversas. Defina alwaysApply: true para mantê-la sempre no escopo. Para limitar seu escopo a um tipo de arquivo, remova a descrição e adicione uma linha globs, e o Cursor a anexará automaticamente quando um arquivo correspondente estiver aberto.
O conteúdo faz o trabalho real. Ele define a forma do comando, indica de onde vem a autenticação e estabelece a linha que mantém um agente honesto: o código de saída prevalece sobre o texto. Agentes às vezes leem um relatório de falha e o chamam de "tudo parece bem". Escrever essa regra uma vez significa que você não precisa pegá-la manualmente.
Passo 2: Obtenha o comando do Apidog
Antes de pedir ao Agente para executar qualquer coisa, obtenha um comando comprovadamente bom. Não faça o Cursor adivinhar os IDs.
Abra seu cenário de teste no Apidog, mude para a aba CI/CD e escolha a opção de linha de comando. O Apidog constrói o comando apidog run completo com o ID do cenário, ID do ambiente e um token de acesso já preenchido:
apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli
605067 é o ID do cenário de teste e 1629989 é o ID do ambiente; os seus serão diferentes. Como você autenticou o CLI durante a instalação, ignore a parte --access-token e mantenha os IDs. Esse é o comando que sua regra disse ao Cursor para usar.
Passo 3: Faça o Agente executar o teste
Abra o Agente do Cursor (o modo de chat que executa comandos de terminal, não a edição inline). Com a regra em vigor, o prompt é curto:
Execute meu cenário de teste do Apidog e Mostre-me a saída completa e diga-me o código de saída.
O Cursor propõe o comando e, depois que você o aprova, o executa no terminal integrado:
apidog run -t 605067 -e 1629989 -n 1 -r cli
Por padrão, o Cursor pergunta antes de executar um comando de terminal, então você vê exatamente o que ele está prestes a executar. Aprová-lo, e o Agente executa o cenário, então lê de volta a execução e um resumo.
Sua verificação: observe o código de saída, não o resumo. apidog run sai com 0 quando todas as asserções passam e diferente de zero quando uma falha. Esse comportamento é o motivo pelo qual isso funciona como um portão, para CI e para o Agente. Se o Cursor diz “testes passaram” mas o código de saída foi diferente de zero, ele está errado; confie no código. Esta é a falha exata que a regra do Passo 1 previne.
Para um formato de relatório diferente ou mais iterações, peça ao Agente para executar apidog run --help para que ele leia a lista real de flags para sua versão instalada. O guia completo do Apidog CLI documenta todas as flags, incluindo os relatórios html, json e junit e iteração orientada a dados.
Passo 4: Leia o relatório dentro do Cursor
O relatório -r cli imprime os resultados no terminal que o Cursor já lê, o que o torna adequado para o trabalho do Agente. O Agente vê as mesmas linhas que você: qual cenário foi executado, cada requisição, cada asserção e a contagem final de sucesso ou falha.
Quando uma execução falha (fica "vermelha"), o relatório nomeia a asserção com falha, o valor esperado e o que o endpoint retornou. Como esse texto está no contexto do Agente, continue no mesmo chat:
O cenário falhou. Leia a asserção com falha no relatório, encontre o handler que produz esse campo e proponha uma correção. Em seguida, execute o cenário novamente e mostre-me o novo código de saída.
Agora o teste faz parte do ciclo. O Cursor edita o handler, executa novamente apidog run, lê o novo código de saída e segue em frente ou tenta novamente. Suas verificações de API vivem no mesmo ciclo de editar-testar-corrigir que o Cursor usa para testes de unidade, exceto que estes são executados contra endpoints reais. Para o padrão mais amplo, como usar agentes de IA para testes de API cobre onde ele se encaixa e onde não se encaixa.
Opcional: conectar o servidor Apidog MCP
O CLI permite ao Cursor executar seus testes. O servidor Apidog MCP permite ao Cursor ler sua especificação de API enquanto ele escreve código. Os dois se complementam: o servidor MCP alimenta o Cursor com seu esquema para que ele gere código que corresponda ao contrato, e o CLI verifica esse código contra cenários reais.
O Cursor suporta servidores MCP através de uma configuração JSON. Coloque servidores com escopo de projeto em .cursor/mcp.json na raiz do seu repositório, ou servidores globais em ~/.cursor/mcp.json. A estrutura é um objeto mcpServers indexado por um nome, cada um com um command, um array args e valores env opcionais:
{
"mcpServers": {
"apidog": {
"command": "npx",
"args": ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"],
"env": {
"APIDOG_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
}
}
}
}
Duas observações. O MCP é controlado por uma chave em algumas instalações, então abra as Configurações do Cursor, encontre a seção "Model Context Protocol" e confirme se o servidor Apidog está habilitado. E se você commitar .cursor/mcp.json, não coloque o token diretamente no código; faça referência a uma variável de ambiente. Para a configuração completa, incluindo onde obter o ID do projeto e o token, consulte o guia do servidor Apidog MCP. Para um fluxo de trabalho empacotado e reutilizável em vez de configurá-lo manualmente, o guia do Apidog CLI com Habilidades Claude mostra a versão baseada em habilidades.
Do loop local para o CI
Depois que o Cursor executa o cenário localmente e age com base no código de saída, você validou o comando exato que sua pipeline usará. O salto para o CI é pequeno: o mesmo apidog run, com o token passado como um segredo mascarado em vez de um login armazenado. Você pode até pedir ao Cursor para escrever a etapa, já que ele conhece o comando de sua regra:
A mecânica dessa etapa (segredos, relatórios, controle de código de saída) está em Apidog CLI no GitHub Actions. O mesmo comando agora é executado em três lugares, seu terminal, o loop do Agente do Cursor e o CI, todos confiando no mesmo código de saída.
Dificuldades comuns
A regra não se aplica. Com description e alwaysApply: false, o Cursor carrega a regra apenas quando julga o chat relevante. Se uma sessão de teste não a estiver captando, mencione-a com @apidog-cli no chat, ou mude para alwaysApply: true.
O Agente não consegue executar o comando. Se ele apenas sugere comandos em vez de executá-los, você provavelmente está no modo de edição em vez do Agente, ou perdeu o prompt de aprovação. Confirme que você está no chat do Agente e aprove quando o Cursor perguntar. Se as execuções do terminal falharem completamente, geralmente é o problema de PATH apidog: command not found que o guia de instalação aborda.
apidog whoami mostra que você não está autenticado. O login é armazenado em sua máquina, não no Cursor. Execute apidog login --with-token você mesmo com um novo token do Apidog, então peça ao Agente para confirmar com apidog whoami. Mantenha o token fora do chat.
Ele inventa uma flag. Se uma execução falhar com um erro de "opção desconhecida", o Agente adivinhou uma flag que não existe em sua versão. Peça para ele executar apidog run --help e copie a flag exata.
Concluindo
A configuração do Cursor consiste em um arquivo e um hábito: uma regra .cursor/rules/apidog-cli.mdc que fixa o comando, a fonte de autenticação e a regra do código de saída, além do hábito de deixar o Agente executar apidog run e verificar o código de saída você mesmo. Adicione o servidor Apidog MCP e o Cursor também poderá ler sua especificação enquanto codifica.
Você continua criando cenários visualmente no Apidog; o Cursor apenas os executa. A partir daqui, aponte o mesmo comando para sua pipeline com o Apidog CLI no GitHub Actions, ou leia a referência completa das flags no guia completo do Apidog CLI.