DEV Community

Cover image for Apidog CLI: Workflow Completo de Agente do PRD ao Loop de Testes
Lucas
Lucas

Posted on • Originally published at apidog.com

Apidog CLI: Workflow Completo de Agente do PRD ao Loop de Testes

Esta é uma série de 10 partes sobre como a Apidog desenvolveu o Apidog CLI, uma ferramenta de linha de comando para testes de API e gerenciamento do ciclo de vida da API. Leia em ordem ou pule para a postagem mais relevante para o seu fluxo de trabalho:

Experimente o Apidog hoje

# Título Foco
1 Construímos 126 Ferramentas MCP. Mas Não É a Melhor Solução para o Agente Descoberta do problema
2 Por Que Desenvolvemos o Novo Apidog CLI Desenvolvimento da arquitetura
3 A Regra de Ouro: CLI Produz Fatos, Modelo Atua com Base nos Fatos Filosofia central
4 agentHints: Ensinando CLIs a Falar com Agentes Saída estruturada
5 SKILL: Entregando Experiência Operacional como Código Experiência operacional
6 Os Números Não Mentem: 30% Menos Chamadas de Ferramentas, 25% Menos Tokens Resultados quantitativos
7 Do PRD ao Ciclo de Testes: Um Fluxo de Trabalho Completo do Agente com Apidog CLI Tutorial prático
8 Por Que a Compatibilidade com CI/CD Não É Negociável para Ferramentas de Agente Perspectiva DevOps
9 AI Branch: Mudanças de Projeto Mais Seguras com Agentes de IA Camada de segurança
10 Spec-First Foi Ontem. Bem-Vindo ao Skill-First. Visão e futuro

Neste artigo, vamos percorrer um fluxo de trabalho completo: uma equipe tem um PRD de Reembolso de Pedido e uma base de código existente. O Agente usa Apidog CLI + SKILL para gerar OpenAPI, importar endpoints, criar casos de teste, validar estruturas e executar a verificação.

Cenário

Contexto: uma equipe escreveu um PRD para a funcionalidade de “Reembolso de Pedido”. A base de código já possui rotas e controladores correspondentes.

Solicitação do usuário ao Agente:

Gere testes de API para a funcionalidade de reembolso com base no PRD e na base de código, e em seguida execute a verificação.

O objetivo é transformar requisitos e código em ativos testáveis dentro do Apidog, com validação em cada etapa.

O problema da abordagem antiga

Com ferramentas MCP, o Agente precisa decidir manualmente qual caminho seguir e qual ferramenta usar em cada etapa.

Ponto de decisão Incerteza
Consultar o projeto primeiro? Ou criar o endpoint primeiro?
Escrever o caso de teste primeiro? Ou gerar o schema primeiro?
Executar os testes diretamente? Ou ler os recursos primeiro?
Qual ferramenta usar? Pesquisar entre 126 ferramentas

O custo operacional fica concentrado em decidir o próximo passo, não em executar a tarefa.

O fluxo CLI + SKILL

Com CLI + SKILL, o fluxo fica explícito:

Gerar OpenAPI a partir do PRD e da base de código
        ↓
Importar para o Apidog
        ↓
Adicionar casos de teste de endpoint único
        ↓
Validar antes de escrever
        ↓
Gerar cenário de teste para o fluxo de negócios
        ↓
Validar antes de escrever
        ↓
Executar testes automatizados
Enter fullscreen mode Exit fullscreen mode

A ideia principal é simples:

  1. O Agente gera ou lê arquivos locais.
  2. O CLI valida a estrutura antes de gravar.
  3. O Apidog armazena endpoints, casos e cenários.
  4. agentHints orienta o próximo passo.

Passo 1: gerar e importar OpenAPI

O Agente começa lendo o PRD e a base de código para montar uma especificação OpenAPI.

Trecho do PRD:

API de Reembolso de Pedido

POST /api/orders/{orderId}/refund
- Corpo da requisição: { "reason": string, "amount": number }
- Resposta: { "refundId": string, "status": string, "processedAt": datetime }

GET /api/orders/{orderId}/refund/{refundId}
- Resposta: { "refundId": string, "status": string, "amount": number }
Enter fullscreen mode Exit fullscreen mode

OpenAPI gerado pelo Agente:

{
  "openapi": "3.0.0",
  "paths": {
    "/api/orders/{orderId}/refund": {
      "post": {
        "summary": "Criar solicitação de reembolso",
        "parameters": [],
        "requestBody": {},
        "responses": {}
      }
    },
    "/api/orders/{orderId}/refund/{refundId}": {
      "get": {
        "summary": "Obter status de reembolso"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Salve o arquivo como openapi.json e importe para o Apidog:

apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Exemplo de saída do CLI:

{
  "success": true,
  "data": {
    "importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],
    "endpointIds": ["ep-001", "ep-002"]
  },
  "agentHints": {
    "summary": "OpenAPI importado com sucesso. 2 endpoints criados.",
    "nextSteps": [
      "Listar os endpoints importados para confirmar a estrutura.",
      "Adicionar casos de teste para cada endpoint.",
      "Criar um cenário de teste para o fluxo completo de reembolso."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Neste ponto, o Agente já tem dois fatos importantes:

  • os endpoints foram criados;
  • os IDs reais dos endpoints estão disponíveis para as próximas chamadas.

Passo 2: criar caso de teste de endpoint único

Agora o Agente trabalha primeiro no endpoint de criação de reembolso.

Leia o endpoint importado:

apidog endpoint get ep-001 --project <projectId>
Enter fullscreen mode Exit fullscreen mode

Estrutura retornada pelo CLI:

{
  "id": "ep-001",
  "method": "POST",
  "path": "/api/orders/{orderId}/refund",
  "requestBody": {
    "schema": {
      "type": "object",
      "properties": {
        "reason": { "type": "string" },
        "amount": { "type": "number" }
      },
      "required": ["reason", "amount"]
    }
  },
  "responses": {
    "200": {}
  }
}
Enter fullscreen mode Exit fullscreen mode

Com a estrutura real do endpoint, o Agente gera um caso de teste:

{
  "name": "Criar reembolso - sucesso",
  "endpointId": "ep-001",
  "request": {
    "path": "/api/orders/order-123/refund",
    "body": {
      "reason": "Solicitação do cliente",
      "amount": 99.99
    }
  },
  "assertions": [
    {
      "subject": "responseJson.status",
      "comparator": "equal",
      "target": "processado"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Salve como test-case-create.json.

Antes de criar o caso de teste no projeto, valide a estrutura localmente:

apidog cli-schema validate test-case-create --file ./test-case-create.json
Enter fullscreen mode Exit fullscreen mode

Resultado esperado:

{
  "success": true,
  "agentHints": {
    "summary": "A estrutura do caso de teste é válida.",
    "nextSteps": [
      "Criar o caso de teste no Apidog.",
      "Ler o caso de teste criado para confirmar.",
      "Adicionar mais asserções, se necessário."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Depois da validação, crie o caso de teste:

apidog test-case create --project <projectId> --file ./test-case-create.json
Enter fullscreen mode Exit fullscreen mode

Saída do CLI:

{
  "success": true,
  "data": {
    "id": "tc-001",
    "name": "Criar reembolso - sucesso"
  },
  "agentHints": {
    "summary": "Caso de teste criado com sucesso.",
    "nextSteps": [
      "Ler o caso de teste tc-001 para confirmar as asserções.",
      "Criar caso de teste para GET /refund/{refundId}.",
      "Construir cenário de teste para o fluxo completo de reembolso."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

O mesmo padrão pode ser repetido para o endpoint GET /api/orders/{orderId}/refund/{refundId}.

Passo 3: criar cenário de teste para o fluxo completo

Com base no PRD, o fluxo de negócio completo é:

Criar pedido → Pagar → Reembolsar → Consultar status de reembolso
Enter fullscreen mode Exit fullscreen mode

O Agente então compõe um cenário usando casos de teste existentes:

{
  "name": "Fluxo Completo de Reembolso de Pedido",
  "steps": [
    { "type": "case", "caseId": "tc-create-order" },
    { "type": "case", "caseId": "tc-pay" },
    { "type": "case", "caseId": "tc-001" },
    { "type": "case", "caseId": "tc-get-refund" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Salve como scenario-update.json.

Valide antes de gravar:

apidog cli-schema validate test-scenario-update --file ./scenario-update.json
Enter fullscreen mode Exit fullscreen mode

Crie o cenário:

apidog test-scenario create --project <projectId> --file ./scenario-update.json
Enter fullscreen mode Exit fullscreen mode

Após criar ou atualizar cenários, é mais seguro ler novamente a estrutura real antes de fazer novas alterações. Quando aplicável, use detalhes dos casos para trabalhar com dados concretos:

apidog test-scenario get scenario-001 \
  --project <projectId> \
  --with-case-detail
Enter fullscreen mode Exit fullscreen mode

Isso evita que o Agente atualize o cenário com base em uma representação incompleta ou desatualizada.

Passo 4: executar a verificação

Com endpoints, casos de teste e cenário prontos, execute a verificação:

apidog run --project <projectId> \
  --test-scenario scenario-001 \
  --environment env-production \
  -r "cli,html,junit" \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Exemplo de saída:

{
  "success": true,
  "stats": {
    "total": 4,
    "passed": 4,
    "failed": 0
  },
  "reportFiles": {
    "cli": "./apidog-reports/cli-report.txt",
    "html": "./apidog-reports/report.html",
    "junit": "./apidog-reports/junit.xml"
  },
  "agentHints": {
    "summary": "Todos os testes passaram. 4 etapas executadas com sucesso.",
    "nextSteps": [
      "Revisar o relatório HTML para resultados detalhados.",
      "Se ocorrerem falhas, depurar usando os detalhes de erro do CLI.",
      "Integrar este teste no pipeline de CI."
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Os relatórios gerados podem ser usados em diferentes contextos:

  • cli: leitura direta no terminal;
  • html: inspeção visual dos resultados;
  • junit: integração com pipelines de CI.

Cadeia completa do fluxo

Ao final, todos os ativos estão conectados:

Elemento Status
PRD Lido e processado
Base de código Analisada para rotas
OpenAPI Gerado e importado
Ativos de endpoint Criados no Apidog
Testes de endpoint único Criados e validados
Cenário de negócios Construído e verificado

O resultado é um fluxo rastreável:

PRD + código
  → OpenAPI
  → endpoints
  → casos de teste
  → cenário
  → execução
  → relatórios
Enter fullscreen mode Exit fullscreen mode

Cada etapa produz dados verificáveis para a próxima.

Como agentHints guia o fluxo

agentHints reduz a necessidade de tentativa e erro. Depois de cada operação, o CLI informa o que faz sentido executar em seguida.

Depois de agentHints sugere
Importar endpoints Listar endpoints e adicionar casos de teste
Criar caso de teste Ler novamente, criar mais casos e construir cenário
Criar cenário Adicionar asserções, validar e executar
Executar testes Revisar relatório, depurar se necessário e integrar ao CI

Em vez de escolher entre dezenas de ferramentas, o Agente segue uma sequência operacional explícita.

Comparação: MCP vs. CLI + SKILL

Dimensão Abordagem MCP Abordagem CLI + SKILL
Ponto de partida Agente busca ferramentas de projeto SKILL identifica o tipo de tarefa
Criação de endpoint Agente adivinha ferramenta e campos Importação CLI a partir de OpenAPI
Criação de caso de teste Múltiplas tentativas em erros de campo Validação local antes da escrita
Construção de cenário Agente escreve a estrutura manualmente Importar etapas, ler novamente e atualizar
Verificação Agente encontra ferramenta de execução agentHints sugere após o cenário
Total de etapas ~20-25 chamadas com retentativas ~10-12 chamadas validadas

A diferença principal não é apenas a quantidade de chamadas. É a previsibilidade do fluxo.

Checklist de implementação

Para aplicar esse padrão em um projeto real:

  1. Leia o PRD e a base de código

    • Identifique endpoints, métodos, parâmetros, request bodies e respostas.

  2. Gere o OpenAPI

    • Salve a especificação como openapi.json.

  3. Importe para o Apidog

   apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode
  1. Leia os endpoints criados 
   apidog endpoint get <endpointId> --project <projectId>
Enter fullscreen mode Exit fullscreen mode

  1. Crie arquivos locais de casos de teste

    • Use os schemas reais retornados pelo CLI.

  2. Valide antes de gravar

   apidog cli-schema validate test-case-create --file ./test-case-create.json
Enter fullscreen mode Exit fullscreen mode
  1. Crie os casos de teste 
   apidog test-case create --project <projectId> --file ./test-case-create.json
Enter fullscreen mode Exit fullscreen mode
  1. Monte o cenário de negócio 
   apidog cli-schema validate test-scenario-update --file ./scenario-update.json
   apidog test-scenario create --project <projectId> --file ./scenario-update.json
Enter fullscreen mode Exit fullscreen mode
  1. Leia novamente quando precisar atualizar 
   apidog test-scenario get scenario-001 \
     --project <projectId> \
     --with-case-detail
Enter fullscreen mode Exit fullscreen mode

  1. Execute e gere relatórios

    apidog run --project <projectId> \
  --test-scenario scenario-001 \
  --environment env-production \
  -r "cli,html,junit" \
  --out-dir ./apidog-reports

O que vem a seguir

Este exemplo mostra como CLI + SKILL funciona em um fluxo real: do PRD até a verificação automatizada.

Na Parte 8, Por Que a Compatibilidade com CI/CD Não É Negociável para Ferramentas de Agente, veremos por que apidog run atende tanto pipelines de CI quanto Agentes de IA — e por que esse propósito duplo é importante para o design sustentável de ferramentas.

Conclusões principais

  • O fluxo completo é: PRD → OpenAPI → Importar → Casos de Teste → Cenário → Verificar.
  • Cada etapa combina comando CLI, validação e agentHints.
  • Validar antes de escrever reduz erros de estrutura.
  • Importar etapas e ler novamente é mais seguro do que editar cenários manualmente.
  • --with-case-detail fornece estrutura real para atualizações.
  • agentHints orienta cada transição.
  • O resultado final é verificável, rastreável e pronto para automação.

Baixe o Apidog para projetar, simular, testar e documentar APIs em um único workspace. Saiba mais sobre o Apidog CLI para testes de API via linha de comando, automação de CI e fluxos de trabalho de Agentes de IA.

Top comments (0)