Từ PRD đến Vòng lặp kiểm thử: Quy trình làm việc Agent hoàn chỉnh với Apidog CLI

Đây là một chuỗi 10 phần chia sẻ cách Apidog đã phát triển Apidog CLI, một công cụ dòng lệnh để kiểm thử API và quản lý vòng đời API. Bạn có thể đọc theo thứ tự hoặc chuyển đến bất kỳ bài viết nào bạn quan tâm:

Xem qua một ví dụ thực tế: một nhóm có PRD hoàn tiền đơn hàng và cơ sở mã. Hãy xem cách Agent sử dụng Apidog CLI + SKILL để tạo OpenAPI, tạo kiểm thử, xác thực và xác minh—từ đầu đến cuối.

Kịch bản

Hãy làm rõ mọi thứ bằng một quy trình làm việc thực tế.

Bối cảnh:

Một nhóm vừa hoàn thành việc viết PRD "Hoàn tiền đơn hàng". Cơ sở mã đã có các route và controller tương ứng.

Yêu cầu người dùng gửi đến Agent:

"Tạo kiểm thử API cho chức năng hoàn tiền dựa trên PRD và cơ sở mã, sau đó chạy xác minh."

Vấn đề của Cách tiếp cận cũ

Với các công cụ MCP, Agent đối mặt với một loạt các tình huống khó xử:

Agent phải tốn nhiều công sức chỉ để quyết định con đường—chứ không phải thực hiện tác vụ.

Con đường CLI + SKILL

CLI + SKILL đáp ứng các luồng R&D thực tế với một chuỗi rõ ràng:

Tạo OpenAPI từ PRD & cơ sở mã
        ↓
Nhập vào Apidog
        ↓
Thêm trường hợp kiểm thử cho một endpoint
        ↓
Xác thực trước khi ghi
        ↓
Tạo kịch bản kiểm thử cho luồng kinh doanh
        ↓
Xác thực trước khi ghi
        ↓
Chạy kiểm thử tự động

Hãy cùng xem xét từng bước.

Bước 1: Tạo OpenAPI & Nhập

Agent đọc PRD và cơ sở mã, sau đó tạo đặc tả OpenAPI.

Trích đoạn PRD:

API Hoàn tiền Đơn hàng

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 }

Agent tạo OpenAPI:

{
  "openapi": "3.0.0",
  "paths": {
    "/api/orders/{orderId}/refund": {
      "post": {
        "summary": "Tạo yêu cầu hoàn tiền",
        "parameters": [...],
        "requestBody": {...},
        "responses": {...}
      }
    },
    "/api/orders/{orderId}/refund/{refundId}": {
      "get": {
        "summary": "Lấy trạng thái hoàn tiền",
        ...
      }
    }
  }
}

Nhập vào Apidog:

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

Đầu ra CLI:

{
  "success": true,
  "data": {
    "importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],
    "endpointIds": ["ep-001", "ep-002"]
  },
  "agentHints": {
    "summary": "OpenAPI đã được nhập thành công. 2 endpoint đã được tạo.",
    "nextSteps": [
      "Liệt kê các endpoint đã nhập để xác nhận cấu trúc.",
      "Thêm trường hợp kiểm thử cho từng endpoint.",
      "Tạo một kịch bản kiểm thử cho toàn bộ luồng hoàn tiền."
    ]
  }
}

Bước 2: Các trường hợp kiểm thử một Endpoint

Agent tập trung vào "endpoint hoàn tiền" trước.

Agent đọc endpoint:

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

CLI trả về cấu trúc 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": {...}
  }
}

Agent tạo trường hợp kiểm thử:

{
  "name": "Tạo hoàn tiền - thành công",
  "endpointId": "ep-001",
  "request": {
    "path": "/api/orders/order-123/refund",
    "body": {
      "reason": "Yêu cầu của khách hàng",
      "amount": 99.99
    }
  },
  "assertions": [
    {
      "subject": "responseJson.status",
      "comparator": "equal",
      "target": "processed"
    }
  ]
}

Xác thực trước khi ghi:

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

Kết quả xác thực CLI:

{
  "success": true,
  "agentHints": {
    "summary": "Cấu trúc trường hợp kiểm thử hợp lệ.",
    "nextSteps": [
      "Tạo trường hợp kiểm thử trong Apidog.",
      "Đọc lại trường hợp kiểm thử đã tạo để xác nhận.",
      "Thêm các khẳng định nếu cần."
    ]
  }
}

Tạo trường hợp kiểm thử:

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

Đầu ra CLI:

{
  "success": true,
  "data": {
    "id": "tc-001",
    "name": "Tạo hoàn tiền - thành công"
  },
  "agentHints": {
    "summary": "Trường hợp kiểm thử đã được tạo thành công.",
    "nextSteps": [
      "Đọc lại trường hợp kiểm thử tc-001 để xác nhận các khẳng định.",
      "Tạo trường hợp kiểm thử cho GET /refund/{refundId}.",
      "Xây dựng kịch bản kiểm thử cho luồng hoàn tiền hoàn chỉnh."
    ]
  }
}

Bước 3: Kịch bản kiểm thử cho luồng hoàn chỉnh

Dựa trên PRD, luồng nghiệp vụ hoàn chỉnh là:

Tạo đơn hàng → Thanh toán → Hoàn tiền → Truy vấn trạng thái hoàn tiền

Agent tạo kịch bản:

{
  "name": "Luồng hoàn tiền đơn hàng hoàn chỉnh",
  "steps": [
    { "type": "case", "caseId": "tc-create-order" },
    { "type": "case", "caseId": "tc-pay" },
    { "type": "case", "caseId": "tc-001" },
    { "type": "case", "caseId": "tc-get-refund" }
  ]
}

Xác thực trước khi ghi:

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

Tạo kịch bản:

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

Bước 4: Chạy Xác minh

Sau khi các trường hợp kiểm thử và kịch bản đã sẵn sàng:

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

Đầu ra 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": "Tất cả các kiểm thử đã vượt qua. 4 bước đã được thực hiện thành công.",
    "nextSteps": [
      "Xem lại báo cáo HTML để biết kết quả chi tiết.",
      "Nếu xảy ra lỗi, hãy gỡ lỗi bằng cách sử dụng chi tiết lỗi CLI.",
      "Tích hợp kiểm thử này vào đường ống CI."
    ]
  }
}

Chuỗi Hoàn chỉnh

Tất cả các yếu tố hiện đã được kết nối:

Mọi thứ đều có thể xác minh và truy vết được.

agentHints Xuyên suốt Luồng

Hãy chú ý cách agentHints hướng dẫn từng bước chuyển đổi:

Agent không bao giờ phải đoán phải làm gì tiếp theo.

So sánh: MCP so với CLI + SKILL cho Tác vụ này

Tiếp theo là gì

Ví dụ thực tế này cho thấy cách CLI + SKILL hoạt động trong một quy trình làm việc thực tế.

Nhưng có một nền tảng bên dưới tất cả điều này: khả năng tương thích CI/CD.

Trong Phần 8, Tại sao khả năng tương thích CI/CD là không thể thiếu đối với các công cụ Agent, chúng ta sẽ khám phá lý do tại sao apidog run phục vụ cả đường ống CI và AI Agents—và tại sao mục đích kép đó lại quan trọng đối với thiết kế công cụ bền vững.

Những điểm chính

• Quy trình làm việc hoàn chỉnh: PRD → OpenAPI → Nhập → Trường hợp kiểm thử → Kịch bản → Xác minh
• Mỗi bước đều có lệnh CLI + xác thực + agentHints
• Nhập các bước + đọc lại an toàn hơn là tự viết kịch bản
• --with-case-detail cung cấp cấu trúc thực để cập nhật
• agentHints hướng dẫn mọi sự chuyển đổi
• Mọi thứ đều có thể xác minh và truy vết được

Tải Apidog để thiết kế, giả lập, kiểm thử và tài liệu hóa API trong một không gian làm việc duy nhất. Tìm hiểu thêm về Apidog CLI để kiểm thử API dòng lệnh, tự động hóa CI và quy trình làm việc của AI Agent.