DEV Community

Cover image for Como usar o Apidog CLI no Windsurf
Lucas
Lucas

Posted on • Originally published at apidog.com

Como usar o Apidog CLI no Windsurf

O agente Cascade do Windsurf trabalha em um loop: edita arquivos, executa comandos no terminal, lê a saída e decide a próxima ação. Seus testes de API devem fazer parte desse mesmo ciclo. Com a CLI do Apidog, o Cascade pode executar cenários diretamente no terminal, interpretar o código de saída e usar falhas como sinal para investigar e corrigir o código.

Experimente o Apidog hoje

A CLI do Apidog é o pacote npm apidog-cli. Depois de instalada e autenticada, ela permite executar os cenários criados no Apidog usando apidog run. Para o Cascade, isso funciona como qualquer outro teste de projeto: ele executa o comando, verifica o código de saída e trata uma execução diferente de zero como falha.

Antes de continuar, confirme que a CLI está disponível:

apidog --version
Enter fullscreen mode Exit fullscreen mode

Você também deve estar autenticado. Se ainda não configurou isso, siga o guia de instalação da CLI do Apidog com um agente de codificação de IA.

Qual Windsurf estamos falando

Windsurf é a IDE com agentes da Codeium, e o agente integrado se chama Cascade. Ele executa localmente, lê o repositório, edita arquivos e roda comandos no terminal integrado.

O ponto desta configuração é ensinar o Cascade a tratar testes de API como uma etapa padrão após alterações que afetam endpoints, contratos ou respostas.

Se necessário, comece instalando a IDE com o guia de como baixar e instalar o Windsurf.

Passo 1: Crie uma regra do Apidog no projeto

O Cascade lê regras do projeto em arquivos Markdown dentro de .windsurf/rules/. Crie o arquivo:

.windsurf/rules/apidog.md
Enter fullscreen mode Exit fullscreen mode

Use uma regra explícita, curta e versionada no Git:

# Testes de API do Apidog

Este projeto possui cenários de teste do Apidog. Execute-os com a CLI do Apidog:

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

Regras:
- Use o comando exato acima; não invente flags. Execute `apidog run --help` se tiver dúvidas.
- `apidog run` sai com 0 quando todas as asserções passam e com valor diferente de zero quando alguma falha.
  Trate 0 como sucesso e qualquer outro código como falha. Relate o código de saída real.
- A máquina já está autenticada via `apidog login`. Nunca adicione token de acesso ao comando
  nem faça commit de tokens neste arquivo.
- Depois de alterar código que afeta a API, execute o cenário e aja com base no resultado.
Enter fullscreen mode Exit fullscreen mode

O Windsurf também oferece suporte ao arquivo legado .windsurfrules na raiz do workspace e a regras globais em ~/.codeium/windsurf/memories/global_rules.md. Para uma instrução específica do repositório, prefira .windsurf/rules/.

Consulte a referência de regras e memórias do Windsurf para detalhes sobre o carregamento dessas regras.

Passo 2: Copie o comando real do Apidog

Não adivinhe os valores de <scenario_id> e <env_id>.

No Apidog:

  1. Abra o cenário de teste.
  2. Acesse a aba CI/CD.
  3. Copie o comando apidog run gerado.
  4. Substitua a linha de exemplo em .windsurf/rules/apidog.md.

O comando copiado já contém os IDs corretos do cenário e do ambiente, além das flags de relatório configuradas para o projeto.

Exemplo:

apidog run -t seu_scenario_id -e seu_env_id -r cli
Enter fullscreen mode Exit fullscreen mode

Para consultar a sintaxe e as flags disponíveis, veja a referência do comando apidog run.

Passo 3: Execute o cenário pelo Cascade

Com a regra criada, abra o Cascade no repositório. Ele deve carregar .windsurf/rules/apidog.md no contexto da sessão.

Você pode pedir uma execução diretamente:

Execute o cenário Apidog e me diga o código de saída.
Enter fullscreen mode Exit fullscreen mode

Ou pode solicitar que o Cascade execute os testes após uma alteração de API:

Atualize o handler de checkout, execute o cenário Apidog e corrija o código se o teste falhar.
Enter fullscreen mode Exit fullscreen mode

O Cascade deve emitir o comando definido na regra:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

A execução automática depende da configuração de auto-execução do Windsurf:

  • Desabilitado: todo comando exige aprovação.
  • Somente Lista de Permissão: apenas comandos permitidos são executados automaticamente.
  • Auto: o modelo decide quando executar.
  • Turbo: os comandos são executados automaticamente, exceto os bloqueados.

Para permitir especificamente a CLI sem liberar todos os comandos, adicione apidog a:

windsurf.cascadeCommandsAllowList
Enter fullscreen mode Exit fullscreen mode

A configuração correspondente para bloqueio é:

windsurf.cascadeCommandsDenyList
Enter fullscreen mode Exit fullscreen mode

A lista de negação prevalece se o comando corresponder às duas listas. Veja os detalhes na documentação do terminal do Windsurf.

Use a lista de permissão apenas para comandos adequados ao seu ambiente. Um cenário somente leitura contra homologação costuma ser um bom candidato.

Passo 4: Leia o resultado no terminal

O reporter cli imprime os detalhes da execução no terminal do Cascade:

  • requisições executadas;
  • asserções validadas;
  • valores esperados e recebidos;
  • códigos de status;
  • resumo da execução;
  • código de saída do processo.

A regra principal é simples:

Código de saída 0 = sucesso
Código de saída diferente de 0 = falha
Enter fullscreen mode Exit fullscreen mode

Quando houver falha, peça para o Cascade usar a saída bruta para investigar:

Leia a saída do apidog run, identifique a asserção que falhou e corrija apenas a causa relacionada.
Enter fullscreen mode Exit fullscreen mode

Para gerar também um relatório navegável, adicione o reporter HTML:

apidog run -t <scenario_id> -e <env_id> -r cli,html
Enter fullscreen mode Exit fullscreen mode

O reporter html grava um relatório autocontido em:

./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Mantenha cli na lista de reporters: é ele que entrega ao Cascade a saída inline necessária para decidir o próximo passo.

Para outros formatos, incluindo JUnit para pipelines de CI, consulte o guia completo da CLI do Apidog e o guia sobre como ler relatórios de teste da CLI do Apidog.

Transforme o teste de API em parte do loop do agente

Depois de configurar a regra, o fluxo esperado é:

  1. O Cascade altera um handler, serviço ou contrato.
  2. Ele executa apidog run.
  3. Ele lê o código de saída.
  4. Se o resultado for 0, continua.
  5. Se o resultado for diferente de 0, lê a asserção com falha.
  6. Ele aplica uma correção e executa o cenário novamente.

Por exemplo, ao alterar uma resposta de checkout, o Cascade pode detectar que um campo esperado desapareceu ou que o status HTTP mudou. Em vez de encerrar a tarefa após editar o código, ele usa o cenário Apidog como uma verificação concreta.

Você continua criando e mantendo cenários visualmente no Apidog. O Cascade passa a executá-los no momento em que a mudança é feita.

Esse é o modelo de delegar e verificar: o agente executa e interpreta o resultado, enquanto você valida que o comando, o cenário e o código de saída usados são reais. Para aprofundar esse padrão, veja como usar agentes de IA para testes de API e a estrutura de teste de IA do Apidog.

Verifique se o Cascade realmente executou a CLI

Não confie apenas no resumo do agente. Faça estas três verificações.

1. Confirme o comando executado

No terminal do Cascade, procure a linha literal:

apidog run ...
Enter fullscreen mode Exit fullscreen mode

Ela deve ser seguida pela saída da execução. Se o Cascade disser que executou testes, mas não houver comando nem saída no terminal, peça a execução novamente com a saída bruta.

2. Confirme o código de saída

Pergunte de forma explícita:

Qual foi o código de saída desse comando apidog run?
Enter fullscreen mode Exit fullscreen mode

O comportamento que importa é:

0: todas as asserções passaram
diferente de 0: uma ou mais asserções falharam
Enter fullscreen mode Exit fullscreen mode

Se o resumo disser “testes passaram”, mas o terminal mostrar um código diferente de zero, considere a execução uma falha.

3. Confirme o cenário e o ambiente

Erros como “cenário não encontrado” normalmente indicam IDs incorretos.

Compare:

  • os valores de -t e -e em .windsurf/rules/apidog.md;
  • o comando gerado pelo Apidog na aba CI/CD;
  • o comando efetivamente executado pelo Cascade.

O arquivo de regras deve conter o comando real do projeto, não valores estimados pelo agente.

Opcional: conecte o servidor MCP do Apidog

A CLI cobre a execução de testes. Para permitir que o Cascade consulte a especificação de API enquanto escreve código, você pode conectar um servidor MCP.

O Windsurf suporta o Model Context Protocol e lê a configuração de servidores em:

~/.codeium/windsurf/mcp_config.json
Enter fullscreen mode Exit fullscreen mode

Você pode editar o arquivo diretamente ou usar o painel MCP do Cascade. Consulte a referência MCP do Windsurf e o guia de como configurar servidores MCP no Windsurf.

O servidor MCP do Apidog expõe especificações de API via MCP. A divisão de responsabilidades fica clara:

  • CLI do Apidog: executa cenários e retorna resultados.
  • MCP do Apidog: fornece contexto de especificação para o agente.

Problemas comuns

O Cascade ignora a regra

Verifique:

  • se o arquivo está em .windsurf/rules/;
  • se o diretório está na raiz do repositório;
  • se o arquivo termina em .md;
  • se o conteúdo está abaixo do limite de 12.000 caracteres por regra.

Reinicie o Cascade para forçar uma nova leitura das regras.

O Cascade adiciona um token ao comando

A regra deve deixar explícito que a máquina já foi autenticada com:

apidog login
Enter fullscreen mode Exit fullscreen mode

Não inclua tokens reais em arquivos de regras que serão versionados. Se o agente tentar adicionar um token, reforce essa instrução e use o fluxo de autenticação correto descrito no guia de autenticação da CLI do Apidog.

O Cascade inventa uma flag

Se aparecer um erro de opção desconhecida, execute:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Use apenas flags mostradas pela versão instalada da CLI. Não aceite flags inferidas pelo agente.

O Cascade reporta sucesso após uma falha

O código de saída vence qualquer resumo textual.

Se o terminal retornar um valor diferente de zero, a execução falhou, mesmo que o Cascade descreva o resultado como sucesso.

Checklist de implementação

Antes de considerar a integração pronta, valide:

  • [ ] apidog --version retorna uma versão instalada.
  • [ ] A máquina está autenticada com apidog login.
  • [ ] O arquivo .windsurf/rules/apidog.md existe.
  • [ ] A regra contém o comando real copiado da aba CI/CD do Apidog.
  • [ ] O comando usa -r cli.
  • [ ] O Cascade consegue executar apidog run.
  • [ ] Você verifica o código de saída no terminal.
  • [ ] apidog está na lista de permissão, se necessário.
  • [ ] Nenhum token foi incluído em regras versionadas.

De um agente diário para um loop testado

A configuração é pequena: instale apidog-cli, adicione uma regra curta em .windsurf/rules/ e cole o comando apidog run gerado pelo seu cenário.

A partir daí, o Cascade pode executar testes de API no mesmo ciclo que usa para editar e validar código. Em vez de descobrir um endpoint quebrado depois do deploy, você recebe o sinal enquanto o agente ainda está trabalhando na alteração.

Você continua criando cenários no Apidog, e o Cascade os executa pelo terminal. Quando o fluxo local estiver funcionando, leve o mesmo comando para CI com o guia da CLI do Apidog no GitHub Actions.

Baixe o Apidog, crie um cenário, copie o comando para uma regra do Windsurf e use o código de saída como a fonte de verdade para o seu loop de testes.

Top comments (0)