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

Esta é uma série de 10 partes compartilhando 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 qualquer postagem que lhe interesse:

Vamos analisar um exemplo real: uma equipe tem um PRD de Reembolso de Pedido e uma base de código. Veja como um Agente usa o Apidog CLI + SKILL para gerar OpenAPI, criar testes, validar e verificar – de ponta a ponta.

O Cenário

Vamos tornar tudo concreto com um fluxo de trabalho real.

Contexto:

Uma equipe acabou de escrever um PRD 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 Problema da Abordagem Antiga

Com as ferramentas MCP, o Agente enfrenta uma série de dilemas:

O Agente gasta um esforço significativo apenas para decidir o caminho – não para executar a tarefa.

O Caminho CLI + SKILL

CLI + SKILL atende a fluxos reais de P&D com uma sequência clara:

Gerar OpenAPI a partir do PRD e 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

Vamos analisar cada etapa.

Passo 1: Gerar e Importar OpenAPI

O Agente lê o PRD e a base de código, então gera a 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 }

Agente gera OpenAPI:

{
  "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",
        ...
      }
    }
  }
}

Importar para o Apidog:

apidog import --project <projectId> --format openapi --file ./openapi.json

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."
    ]
  }
}

Passo 2: Casos de Teste de Endpoint Único

O Agente foca primeiro no "endpoint de reembolso".

Agente lê o endpoint:

apidog endpoint get ep-001 --project <projectId>

CLI retorna a estrutura do endpoint:

{
  "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": {...}
  }
}

Agente gera 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"
    }
  ]
}

Validar antes de escrever:

apidog cli-schema validate test-case-create --file ./test-case-create.json

Resultado da validação do CLI:

{
  "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."
    ]
  }
}

Criar caso de teste:

apidog test-case create --project <projectId> --file ./test-case-create.json

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."
    ]
  }
}

Passo 3: Cenário de Teste para o Fluxo Completo

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

Criar pedido → Pagar → Reembolsar → Consultar status de reembolso

Agente gera cenário:

{
  "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" }
  ]
}

Validar antes de escrever:

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

Criar cenário:

apidog test-scenario create --project <projectId> --file ./scenario-update.json

Passo 4: Executar Verificação

Depois que os casos de teste e cenários estão prontos:

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

Saída do CLI:

{
  "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."
    ]
  }
}

A Cadeia Completa

Todos os elementos estão agora conectados:

Tudo é verificável e rastreável.

agentHints ao Longo do Fluxo

Observe como `agentHints` guia cada transição:

O Agente nunca precisa adivinhar o que fazer em seguida.

Comparação: MCP vs. CLI + SKILL para Esta Tarefa

O Que Vem a Seguir

Este exemplo prático mostra como o CLI + SKILL funciona em um fluxo de trabalho real.

Mas há uma base por trás de tudo isso: a compatibilidade com CI/CD.

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

Conclusões Principais

• Fluxo de trabalho completo: PRD → OpenAPI → Importar → Casos de Teste → Cenário → Verificar
• Cada etapa tem comando CLI + validação + agentHints
• Importar etapas + ler novamente é mais seguro do que escrever cenários manualmente
• --with-case-detail oferece estrutura real para atualizações
• `agentHints` guia cada transição
• Tudo é verificável e rastreável

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.