O agente Cascade do Windsurf executa um loop: ele edita arquivos, executa comandos de terminal, lê a saída e decide o que fazer em seguida. Então, por que seus testes de API não estão nesse loop? Eles ficam no Apidog, por trás de uma interface gráfica, e são executados quando alguém se lembra de clicar. Cascade 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 o Cascade saiba de sua existência, o Windsurf executa um cenário do Apidog da mesma forma que executa seus testes unitários: dispara o comando, lê o código de saída, corrige o código se ele retornar em 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 via npm, a autenticação e a primeira execução, com um agente digitando. Este artigo assume que apidog --version imprime um número e que sua conta Apidog está autenticada.
Qual Windsurf estamos falando
Windsurf é a IDE agente da Codeium, e seu agente integrado é chamado Cascade. O Cascade é executado localmente, lê seu repositório, edita arquivos e executa comandos de shell em seu terminal integrado, solicitando aprovação com base em sua configuração de auto-execução. Este é o editor e seu agente, não uma extensão de navegador ou um plugin de autocompletar.
Se você ainda não o configurou, comece com como baixar e instalar o Windsurf. Uma vez que o Cascade esteja aberto em seu projeto, você pode ensiná-lo sobre a CLI do Apidog através de seu próprio mecanismo de regras, o que transforma um "execute meus testes" pontual em algo que o Cascade busca por conta própria.
Passo 1: Adicione uma regra Apidog a .windsurf/rules
O Cascade lê as regras do projeto a partir de arquivos Markdown antes de começar a trabalhar. Coloque-as em um diretório .windsurf/rules/ na raiz do seu repositório, uma regra por arquivo. O Windsurf ainda lê um arquivo único legado .windsurfrules na raiz do workspace, e um ~/.codeium/windsurf/memories/global_rules.md global que se aplica a todos os projetos, mas para uma instrução por projeto, o diretório .windsurf/rules/ é o local correto. Isso está documentado na referência de regras e memórias do Windsurf.
Crie .windsurf/rules/apidog.md com um bloco como este:
# 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 um valor diferente de zero quando alguma falha.
Trate a saída 0 como sucesso e diferente de zero como falha. Relate o código de saída real.
- A máquina já está autenticada via `apidog login`. Nunca adicione um
token de acesso ao comando ou o comite neste arquivo.
- Depois de alterar o código que afeta a API, execute o cenário e aja com base no resultado.
Por que um arquivo de regra em vez de uma mensagem de chat? Um ID de cenário digitado no chat desaparece quando a sessão termina. Um em .windsurf/rules/apidog.md está lá para cada colega de equipe e cada sessão do Cascade a partir de agora. Ele persiste, é versionado no Git, e o Cascade o carrega automaticamente no contexto na inicialização.
Passo 2: Obtenha o comando do Apidog
O <scenario_id> e <env_id> nesse bloco não são placeholders que você adivinha. O Apidog gera o comando exato para você.
Abra o cenário de teste no Apidog, vá para a aba CI/CD e copie o comando apidog run pronto. Ele já terá o ID do cenário, o ID do ambiente e as flags de relatório corretos preenchidos. Cole esse comando em seu .windsurf/rules/apidog.md no lugar da linha de exemplo. Agora a regra contém um comando que realmente funciona para o seu projeto, e não um modelo.
Para a anatomia completa desse comando e todas as flags que ele aceita, consulte a referência do comando apidog run.
Passo 3: Peça para o Cascade executar o teste
Com a regra no lugar, abra o Cascade em seu repositório. Ele carrega .windsurf/rules/apidog.md ao iniciar, então 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 Apidog e me diga o código de saída.
O Cascade emite o comando apidog run da sua regra. Se ele é executado sem um prompt depende da sua configuração de auto-execução. O Windsurf oferece quatro níveis: Desabilitado (cada comando precisa de aprovação), Somente Lista de Permissão (apenas comandos que correspondem à sua lista de permissão são executados automaticamente), Auto (uma decisão de julgamento do modelo premium) e Turbo (tudo é executado automaticamente, exceto comandos na lista de negação). No modo Turbo, um simples apidog run é executado por conta própria; nos modos mais rigorosos, o Cascade pausa e pergunta primeiro.
Se você deseja que o apidog run seja executado automaticamente sem flexibilizar tudo, adicione-o à sua lista de permissão. A configuração é windsurf.cascadeCommandsAllowList, acessível pela Paleta de Comandos em Abrir Configurações; adicione apidog e o Cascade executará o comando sem perguntar. A configuração de lista de negação correspondente é windsurf.cascadeCommandsDenyList, e a lista de negação prevalece quando um comando corresponde a ambas. Ambas são abordadas na documentação do terminal do Windsurf. Um cenário de somente leitura contra um ambiente de homologação é exatamente o tipo de comando seguro, no workspace, para o qual uma entrada na lista de permissão é feita.
Passo 4: Leia o relatório dentro do Windsurf
Quando uma execução falha (fica vermelha), o relatório tem a resposta. O reporter -r cli imprime um resultado passo a passo e um resumo diretamente no terminal do Cascade: cada requisição, cada asserção e qual delas falhou com o valor esperado versus o valor real. A asserção com falha nomeia o campo ou código de status exato, o que geralmente é suficiente para o Cascade encontrar a correção em sua próxima passagem.
Para um relatório que você pode abrir em um navegador ou entregar a um colega de equipe, adicione o reporter HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
O reporter html escreve um arquivo autocontido para ./apidog-reports. Mantenha cli na lista para que o Cascade ainda receba a saída inline que ele lê para decidir seu próximo passo. Para cada reporter, incluindo o formato JUnit que os dashboards de CI analisam, consulte o guia completo da CLI do Apidog e como ler relatórios de teste da CLI do Apidog.
Testes do Windsurf dentro de seu próprio loop
O ponto é o que acontece quando você para de perguntar e o Cascade executa o cenário por conta própria, porque a regra o instruiu.
Imagine o Cascade 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 homologação, lê o código de saída e age sobre ele. Verde, ele avança. 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 editar-testar-corrigir que o Cascade já usa para seus testes unitários. Você escreveu uma regra e o Cascade incorporou o comando em seu funcionamento usual.
Este é o modelo de "delegar e verificar" que torna qualquer fluxo de trabalho de agente seguro. O Cascade 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 a estrutura de teste de IA do Apidog.
Verifique se o Cascade está realmente executando a CLI
Agentes relatam sucesso que não conquistaram, e o Cascade 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 Cascade mostra os comandos que ele executa e suas saídas inline no terminal. Procure a linha literal apidog run ... e um resultado abaixo dela. Se o Cascade 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. Pergunte diretamente:
Qual foi o código de saída desse comando apidog run?
apidog run sai com 0 quando todas as asserções passam e com um valor diferente de zero quando algo falha. Esse único comportamento permite que o Cascade, ou um pipeline, trate a execução como um portão limpo. Quando a prosa do Cascade diz "testes passaram", mas o código de saída é diferente de 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 Cascade pode ter inventado ou se lembrado incorretamente de um ID. Verifique novamente os valores de -t e -e em seu arquivo de regras e no comando que o Apidog gerou na aba CI/CD. Os IDs em .windsurf/rules/apidog.md são a verdade.
Opcional: conecte o servidor Apidog MCP
Executar apidog run a partir de uma regra cobre a maior parte do que você precisa. Para ir um passo além, conecte um servidor MCP.
O Cascade suporta o Protocolo de Contexto do Modelo. O Windsurf lê sua lista de servidores de ~/.codeium/windsurf/mcp_config.json, que você pode editar diretamente ou gerenciar através do painel MCP do Cascade; o formato é documentado na referência MCP do Windsurf, e como configurar servidores MCP no Windsurf detalha o uso do painel. O servidor MCP do Apidog expõe suas especificações de API via MCP, para que o Cascade 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 Windsurf erra
Alguns problemas aparecem frequentemente durante a configuração.
Ele ignora a regra. Se o Cascade executa um comando genérico ou nenhum, a regra pode não estar carregando. Confirme se o arquivo está em .windsurf/rules/ na raiz do seu repositório e tem a extensão .md. Cada arquivo de regra é limitado a 12.000 caracteres, então mantenha o bloco Apidog curto. Reiniciar o Cascade força uma nova leitura.
Ele passa um token de acesso de qualquer forma. Se o Cascade tentar adicionar um token de acesso ao comando, ele está adivinhando a partir de exemplos públicos. Sua regra 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 um arquivo de regras que será commitado. Para entender como a autenticação realmente funciona, consulte o guia de autenticação da CLI do Apidog.
Ele inventa uma flag. Um erro de "opção desconhecida" significa que o Cascade adivinhou uma flag que sua versão não possui. Diga a ele para executar apidog run --help e copie a flag exata de lá, que é sempre correta para sua versão instalada.
Ele reporta sucesso em uma execução falha. O mais custoso, e a razão pela qual a regra do código de saída está tanto em seu arquivo de regras quanto em 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 uma regra Apidog curta ao diretório .windsurf/rules/ do seu repositório, e o Cascade 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 é detectado enquanto o Cascade ainda está trabalhando na mudança, 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 Cascade decide. Você continua construindo cenários visualmente no Apidog, e seu agente os executa onde você não está observando. Para executar o mesmo comando em um pipeline, uma vez que funcione localmente, a CLI do Apidog no GitHub Actions aborda os segredos, reporters e controle de código de saída. Baixe o Apidog, construa um cenário, insira seu comando apidog run em uma regra do Windsurf e observe o Cascade identificá-lo na próxima alteração.