PRD부터 테스트 루프까지: Apidog CLI로 완성하는 에이전트 워크플로우

이것은 Apidog이 API 테스트 및 API 수명 주기 관리를 위한 명령줄 도구인 Apidog CLI를 개발한 방법을 공유하는 10부작 시리즈입니다. 순서대로 읽거나 관심 있는 게시물로 이동하세요:

실제 예시를 살펴보세요: 한 팀이 주문 환불 PRD와 코드베이스를 가지고 있습니다. 에이전트가 Apidog CLI + SKILL을 사용하여 OpenAPI를 생성하고, 테스트를 만들고, 유효성을 검사하고, 엔드 투 엔드(end to end)로 확인하는 방법을 알아보세요.

시나리오

실제 워크플로우를 통해 모든 것을 구체화해 봅시다.

맥락:

한 팀이 "주문 환불" PRD 작성을 마쳤습니다. 코드베이스에는 이미 해당 경로와 컨트롤러가 있습니다.

에이전트에 대한 사용자 요청:

"PRD 및 코드베이스를 기반으로 환불 기능에 대한 API 테스트를 생성한 다음, 검증을 실행하세요."

기존 접근 방식의 문제점

MCP 도구를 사용하면 에이전트는 다음과 같은 일련의 딜레마에 직면합니다:

에이전트는 작업을 실행하는 것이 아니라 경로를 결정하는 데 상당한 노력을 기울입니다.

CLI + SKILL 경로

CLI + SKILL은 명확한 순서로 실제 R&D 흐름을 만족시킵니다:

PRD 및 코드베이스에서 OpenAPI 생성
        ↓
Apidog으로 가져오기
        ↓
단일 엔드포인트 테스트 케이스 추가
        ↓
작성 전 유효성 검사
        ↓
비즈니스 흐름을 위한 테스트 시나리오 생성
        ↓
작성 전 유효성 검사
        ↓
자동화된 테스트 실행

각 단계를 살펴보겠습니다.

1단계: OpenAPI 생성 및 가져오기

에이전트는 PRD와 코드베이스를 읽은 다음 OpenAPI 사양을 생성합니다.

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 }

에이전트가 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",
        ...
      }
    }
  }
}

Apidog으로 가져오기:

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

CLI 출력:

{
  "success": true,
  "data": {
    "importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],
    "endpointIds": ["ep-001", "ep-002"]
  },
  "agentHints": {
    "summary": "OpenAPI가 성공적으로 가져와졌습니다. 2개의 엔드포인트가 생성되었습니다.",
    "nextSteps": [
      "가져온 엔드포인트 목록을 확인하여 구조를 확인하세요.",
      "각 엔드포인트에 대한 테스트 케이스를 추가하세요.",
      "전체 환불 흐름에 대한 테스트 시나리오를 만드세요."
    ]
  }
}

2단계: 단일 엔드포인트 테스트 케이스

에이전트는 먼저 "환불 엔드포인트"에 집중합니다.

에이전트가 엔드포인트를 읽습니다:

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

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

에이전트가 테스트 케이스를 생성합니다:

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

작성 전 유효성 검사:

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

CLI 유효성 검사 결과:

{
  "success": true,
  "agentHints": {
    "summary": "테스트 케이스 구조가 유효합니다.",
    "nextSteps": [
      "Apidog에서 테스트 케이스를 생성하세요.",
      "생성된 테스트 케이스를 다시 읽어와 확인하세요.",
      "필요하면 더 많은 어설션을 추가하세요."
    ]
  }
}

테스트 케이스 생성:

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

CLI 출력:

{
  "success": true,
  "data": {
    "id": "tc-001",
    "name": "Create refund - success"
  },
  "agentHints": {
    "summary": "테스트 케이스가 성공적으로 생성되었습니다.",
    "nextSteps": [
      "tc-001 테스트 케이스를 다시 읽어와 어설션을 확인하세요.",
      "GET /refund/{refundId}에 대한 테스트 케이스를 만드세요.",
      "전체 환불 흐름에 대한 테스트 시나리오를 구축하세요."
    ]
  }
}

3단계: 전체 흐름을 위한 테스트 시나리오

PRD를 기반으로 전체 비즈니스 흐름은 다음과 같습니다:

주문 생성 → 결제 → 환불 → 환불 상태 조회

에이전트가 시나리오를 생성합니다:

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

작성 전 유효성 검사:

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

시나리오 생성:

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

4단계: 검증 실행

테스트 케이스와 시나리오가 준비된 후:

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

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": "모든 테스트가 통과되었습니다. 4단계가 성공적으로 실행되었습니다.",
    "nextSteps": [
      "자세한 결과를 보려면 HTML 보고서를 검토하세요.",
      "실패가 발생한 경우 CLI 오류 세부 정보를 사용하여 디버그하세요.",
      "이 테스트를 CI 파이프라인에 통합하세요."
    ]
  }
}

완전한 연결고리

모든 요소가 이제 연결되었습니다:

모든 것이 검증 가능하고 추적 가능합니다.

흐름을 통한 agentHints

agentHints가 각 전환을 어떻게 안내하는지 주목하세요:

에이전트는 다음에 무엇을 해야 할지 추측할 필요가 없습니다.

비교: 이 작업을 위한 MCP vs. CLI + SKILL

다음 단계

이 실용적인 예시는 실제 워크플로우에서 CLI + SKILL이 어떻게 작동하는지 보여줍니다.

하지만 이 모든 것의 기반에는 CI/CD 호환성이 있습니다.

8부, 에이전트 도구에 CI/CD 호환성이 필수적인 이유에서 apidog run이 CI 파이프라인과 AI 에이전트 모두에 사용되는 이유와 지속 가능한 도구 설계에 이 이중 목적이 중요한 이유를 살펴보겠습니다.

주요 요점

• 완전한 워크플로우: PRD → OpenAPI → 가져오기 → 테스트 케이스 → 시나리오 → 검증
• 각 단계는 CLI 명령 + 유효성 검사 + agentHints를 포함합니다.
• 가져오기 단계 + 다시 읽기는 시나리오를 수동으로 작성하는 것보다 안전합니다.
• --with-case-detail은 업데이트를 위한 실제 구조를 제공합니다.
• agentHints는 모든 전환을 안내합니다.
• 모든 것이 검증 가능하고 추적 가능합니다.

Apidog을 다운로드하여 단일 작업 공간에서 API를 설계하고, 모의하며, 테스트하고, 문서화하세요. 명령줄 API 테스트, CI 자동화 및 AI 에이전트 워크플로우를 위한 Apidog CLI에 대해 더 자세히 알아보세요.

button