Del PRD al ciclo de pruebas: Un flujo de trabajo de agente completo con Apidog CLI

Esta es una serie de 10 partes que comparte cómo Apidog desarrolló Apidog CLI, una herramienta de línea de comandos para pruebas de API y gestión del ciclo de vida de la API. Lea en orden o salte a cualquier publicación que le interese:

Examine un ejemplo real: un equipo tiene un PRD de Reembolso de Pedido y su base de código. Vea cómo un Agente utiliza Apidog CLI + SKILL para generar OpenAPI, crear pruebas, validar y verificar —de principio a fin.

El Escenario

Hagamos todo concreto con un flujo de trabajo real.

Contexto:

Un equipo acaba de terminar de escribir un PRD de "Reembolso de Pedido". La base de código ya tiene las rutas y controladores correspondientes.

Solicitud del usuario al Agente:

"Genera pruebas de API para la funcionalidad de reembolso basadas en el PRD y la base de código, luego ejecuta la verificación."

El Problema del Enfoque Antiguo

Con las herramientas MCP, el Agente se enfrenta a una serie de dilemas:

El Agente dedica un esfuerzo significativo solo a decidir el camino, no a ejecutar la tarea.

El Camino CLI + SKILL

CLI + SKILL satisface los flujos de I+D reales con una secuencia clara:

Generar OpenAPI desde PRD y codebase
        ↓
Importar a Apidog
        ↓
Añadir casos de prueba de un solo endpoint
        ↓
Validar antes de escribir
        ↓
Generar escenario de prueba para flujo de negocio
        ↓
Validar antes de escribir
        ↓
Ejecutar pruebas automatizadas

Veamos cada paso.

Paso 1: Generar e Importar OpenAPI

El Agente lee el PRD y la base de código, luego genera la especificación OpenAPI.

Extracto del PRD:

Order Refund API

POST /api/orders/{orderId}/refund
- Request body: { "reason": string, "amount": number }
- Response: { "refundId": string, "status": string, "processedAt": datetime }

GET /api/orders/{orderId}/refund/{refundId}
- Response: { "refundId": string, "status": string, "amount": number }

El Agente genera OpenAPI:

{
  "openapi": "3.0.0",
  "paths": {
    "/api/orders/{orderId}/refund": {
      "post": {
        "summary": "Create refund request",
        "parameters": [...],
        "requestBody": {...},
        "responses": {...}
      }
    },
    "/api/orders/{orderId}/refund/{refundId}": {
      "get": {
        "summary": "Get refund status",
        ...
      }
    }
  }
}

Importar a Apidog:

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

Salida de CLI:

{
  "success": true,
  "data": {
    "importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],
    "endpointIds": ["ep-001", "ep-002"]
  },
  "agentHints": {
    "summary": "OpenAPI importado con éxito. 2 endpoints creados.",
    "nextSteps": [
      "Listar los endpoints importados para confirmar la estructura.",
      "Añadir casos de prueba para cada endpoint.",
      "Crear un escenario de prueba para el flujo completo de reembolso."
    ]
  }
}

Paso 2: Casos de Prueba de un Solo Endpoint

El Agente se enfoca primero en el "endpoint de reembolso".

El Agente lee el endpoint:

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

CLI devuelve la estructura del 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": {...}
  }
}

El Agente genera el caso de prueba:

{
  "name": "Crear reembolso - éxito",
  "endpointId": "ep-001",
  "request": {
    "path": "/api/orders/order-123/refund",
    "body": {
      "reason": "Customer request",
      "amount": 99.99
    }
  },
  "assertions": [
    {
      "subject": "responseJson.status",
      "comparator": "igual",
      "target": "processed"
    }
  ]
}

Validar antes de escribir:

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

Resultado de la validación CLI:

{
  "success": true,
  "agentHints": {
    "summary": "La estructura del caso de prueba es válida.",
    "nextSteps": [
      "Crear el caso de prueba en Apidog.",
      "Leer el caso de prueba creado para confirmar.",
      "Añadir más aserciones si es necesario."
    ]
  }
}

Crear caso de prueba:

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

Salida de CLI:

{
  "success": true,
  "data": {
    "id": "tc-001",
    "name": "Create refund - success"
  },
  "agentHints": {
    "summary": "Caso de prueba creado con éxito.",
    "nextSteps": [
      "Leer de nuevo el caso de prueba tc-001 para confirmar las aserciones.",
      "Crear caso de prueba para GET /refund/{refundId}.",
      "Construir escenario de prueba para el flujo completo de reembolso."
    ]
  }
}

Paso 3: Escenario de Prueba para el Flujo Completo

Basado en el PRD, el flujo de negocio completo es:

Crear pedido → Pagar → Reembolsar → Consultar estado de reembolso

El Agente genera el escenario:

{
  "name": "Order Refund Complete Flow",
  "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 escribir:

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

Crear escenario:

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

Paso 4: Ejecutar Verificación

Después de que los casos de prueba y los escenarios estén listos:

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

Salida de 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": "Todas las pruebas pasaron. 4 pasos ejecutados con éxito.",
    "nextSteps": [
      "Revisar el informe HTML para resultados detallados.",
      "Si ocurrieron fallos, depurar usando los detalles de error del CLI.",
      "Integrar esta prueba en el pipeline de CI."
    ]
  }
}

La Cadena Completa

Todos los elementos están ahora conectados:

Todo es verificable y rastreable.

agentHints a través del Flujo

Observe cómo agentHints guía cada transición:

El Agente nunca tiene que adivinar qué hacer a continuación.

Comparación: MCP vs. CLI + SKILL para esta Tarea

Qué Sigue

Este ejemplo práctico muestra cómo funciona CLI + SKILL en un flujo de trabajo real.

Pero hay una base debajo de todo esto: compatibilidad con CI/CD.

En la Parte 8, Por qué la compatibilidad con CI/CD no es negociable para las herramientas de agente, exploraremos por qué apidog run sirve tanto a los pipelines de CI como a los Agentes de IA, y por qué ese doble propósito es importante para un diseño de herramienta sostenible.

Puntos Clave

• Flujo de trabajo completo: PRD → OpenAPI → Importación → Casos de Prueba → Escenario → Verificación
• Cada paso tiene comando CLI + validación + agentHints
• Importar pasos + leer de nuevo es más seguro que escribir escenarios a mano
• --with-case-detail proporciona una estructura real para las actualizaciones
• agentHints guía cada transición
• Todo es verificable y rastreable

Descargue Apidog para diseñar, simular, probar y documentar APIs en un solo espacio de trabajo. Obtenga más información sobre Apidog CLI para pruebas de API de línea de comandos, automatización CI y flujos de trabajo de Agentes de IA.