Cách Kiểm Thử API GraphQL trong Apidog (Queries, Mutations và Tự động hóa)

Bạn có một endpoint GraphQL và cần xác minh nó thực sự hoạt động: truy vấn user có trả về đúng các trường mà ứng dụng sử dụng không, mutation createOrder có lưu đơn hàng không, và dữ liệu có giữ đúng định dạng khi thay đổi biến đầu vào không. Vì GraphQL gửi mọi thao tác đến cùng một URL, thường qua POST, bạn cần một client hiểu cú pháp truy vấn, hỗ trợ schema và giúp xác nhận JSON trả về thay vì chỉ kiểm tra URL, method và mã trạng thái.

Dùng thử Apidog ngay hôm nay

Apidog hỗ trợ GraphQL như một loại yêu cầu riêng, bên cạnh HTTP, gRPC, WebSocket, SSE và SOAP. Bài viết này hướng dẫn bạn tạo và kiểm thử một request GraphQL từ đầu:

1. Viết query.
2. Lấy schema để bật tự động hoàn thành.
3. Truyền biến để tái sử dụng request.
4. Chạy mutation.
5. Xác nhận phản hồi.
6. Lưu thành test scenario để chạy lại.

Ví dụ sử dụng API thương mại điện tử: truy vấn một người dùng cùng đơn hàng của họ, sau đó tạo đơn hàng mới. Tham khảo tài liệu GraphQL chính thức để hiểu mô hình GraphQL, hoặc xem bài REST vs GraphQL để chọn giao thức phù hợp.

Bạn đang kiểm thử gì và tại sao GraphQL khác biệt?

REST thường có nhiều endpoint, mỗi endpoint trả về một định dạng cố định. GraphQL thường dùng một endpoint duy nhất và cho phép client chọn chính xác các trường cần lấy.

Điều này thay đổi cách kiểm thử:

• Request nằm trong body dưới dạng tài liệu GraphQL, không phải URL thay đổi theo tài nguyên.
• Một request như GET /users/42 trở thành selection như user(id: 42) { ... }, thường được gửi bằng POST.
• Lỗi nghiệp vụ hoặc lỗi thực thi GraphQL vẫn có thể trả về 200 OK, nhưng body chứa mảng errors.

Vì vậy, chỉ kiểm tra HTTP status là không đủ. Bạn phải xác nhận cả nội dung phản hồi.

Apidog cung cấp GraphQL body chuyên dụng, tự động hoàn thành dựa trên schema, hỗ trợ biến và assertion tương tự REST. Bạn có thể lưu request vào project và kết hợp chúng thành kịch bản kiểm thử chạy lặp lại.

Tạo request GraphQL trong Apidog

Trước tiên, tải Apidog hoặc mở Apidog trên trình duyệt, sau đó mở project của bạn. Nếu chưa có project, hãy tạo mới để lưu request và test scenario.

Bước 1: Tạo request và chọn GraphQL body

1. Nhấp nút +.
2. Chọn New Request.
3. Đặt method là POST.
4. Nhập endpoint GraphQL, ví dụ:

https://api.yourstore.com/graphql

1. Mở tab Body.
2. Chọn GraphQL.

Apidog sẽ hiển thị trình chỉnh sửa GraphQL với vùng Query.

Nếu endpoint yêu cầu xác thực, mở tab Authorization và cấu hình token, ví dụ Bearer token. Về bản chất, GraphQL request vẫn là HTTP request nên cơ chế xác thực hoạt động giống REST.

Bước 2: Viết query đầu tiên

Trong tab Run, nhập query để lấy người dùng và đơn hàng của họ:

query GetUserWithOrders {
  user(id: "usr_1024") {
    id
    name
    email
    orders {
      id
      total
      status
      createdAt
    }
  }
}

Tên trường phải khớp chính xác với schema của server. Ví dụ, nếu schema dùng emailAddress thay vì email, query sẽ lỗi. Bước tiếp theo giúp bạn tránh phải đoán tên field.

Bước 3: Lấy schema để bật tự động hoàn thành

Để Apidog đọc schema:

1. Trong trình chỉnh sửa GraphQL, nhấp Fetch Schema.
2. Apidog gửi introspection query đến endpoint.
3. Khi thành công, trình chỉnh sửa sẽ gợi ý field và type hợp lệ khi bạn gõ.

Lưu ý:

• Tự động hoàn thành chỉ hoạt động sau khi bạn nhấp Fetch Schema.
• Nếu production endpoint đã tắt introspection, Apidog không thể lấy schema.
• Sau khi schema thay đổi, hãy chạy lại Fetch Schema để cập nhật gợi ý.

Bước 4: Gửi request và đọc phản hồi

Nhấp Send. Một phản hồi thành công có thể có dạng:

{
  "data": {
    "user": {
      "id": "usr_1024",
      "name": "Dana Whitfield",
      "email": "[e-mail]",
      "orders": [
        {
          "id": "ord_5001",
          "total": 89.9,
          "status": "SHIPPED",
          "createdAt": "2026-07-01T09:14:00Z"
        },
        {
          "id": "ord_5002",
          "total": 12.5,
          "status": "PENDING",
          "createdAt": "2026-07-12T16:03:00Z"
        }
      ]
    }
  }
}

GraphQL thường dùng hai khóa cấp cao nhất:

• data: dữ liệu trả về từ query hoặc mutation.
• errors: danh sách lỗi GraphQL.

Khi viết assertion, hãy dùng các đường dẫn lồng bên trong data, ví dụ data.user.orders, thay vì kiểm tra trực tiếp ở root.

Truyền biến để tái sử dụng request

Không nên gán cứng "usr_1024" trong query nếu bạn cần chạy request cho nhiều user hoặc nhiều môi trường. Thay vào đó, dùng biến GraphQL.

Tham khảo tài liệu GraphQL về variables.

Khai báo biến trong operation signature:

query GetUserWithOrders($userId: ID!) {
  user(id: $userId) {
    id
    name
    orders {
      id
      total
      status
    }
  }
}

Sau đó cung cấp giá trị trong phần variables:

{
  "userId": "usr_1024"
}

Lợi ích của cách này:

• Không phải sửa query khi đổi user.
• Có thể dùng cùng request cho staging và production.
• Dễ kết hợp với environment variables trong Apidog.
• Dễ lưu và chạy lại trong test scenario.

Viết mutation để tạo đơn hàng

Mutation thay đổi dữ liệu. Bạn vẫn viết nó trong cùng vùng Query, nhưng dùng từ khóa mutation.

Ví dụ tạo đơn hàng:

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    id
    total
    status
    createdAt
  }
}

Truyền payload qua biến:

{
  "input": {
    "userId": "usr_1024",
    "items": [
      {
        "sku": "TSHIRT-BLK-M",
        "quantity": 2
      },
      {
        "sku": "MUG-CERAMIC",
        "quantity": 1
      }
    ],
    "currency": "USD"
  }
}

Nhấp Send. Phản hồi thành công có thể là:

{
  "data": {
    "createOrder": {
      "id": "ord_5003",
      "total": 42.3,
      "status": "PENDING",
      "createdAt": "2026-07-15T10:22:11Z"
    }
  }
}

Vì mutation ghi dữ liệu thực, hãy chạy chúng trên môi trường test hoặc staging thay vì production.

Một luồng end-to-end thực tế:

1. Query user hiện tại.
2. Chạy CreateOrder.
3. Lấy id đơn hàng từ phản hồi mutation.
4. Query lại user.
5. Xác nhận đơn hàng mới xuất hiện trong danh sách orders.

Xác nhận phản hồi thay vì kiểm tra thủ công

Khi khám phá API, bạn có thể đọc JSON bằng mắt. Nhưng với regression test, hãy thêm assertion để request tự động pass hoặc fail.

Apidog hỗ trợ assertion cho request. Xem thêm hướng dẫn về xác nhận API.

Với GraphQL, hãy tối thiểu kiểm tra ba điều sau:

1. HTTP status là 200
   
   Cần thiết, nhưng chưa đủ.

2. Trường errors không tồn tại
   
   Đây là kiểm tra quan trọng nhất. GraphQL có thể trả về HTTP 200 nhưng vẫn thất bại do lỗi xác thực, validation hoặc resolver.

3. Dữ liệu trong data đúng như mong đợi
   
   Ví dụ:

   • $.data.createOrder.status bằng PENDING
   • $.data.user.orders có số phần tử lớn hơn 0
   • $.data.user.id bằng ID đầu vào

Các assertion này phát hiện những lỗi mà kiểm tra HTTP status không phát hiện được, chẳng hạn request có 200 OK nhưng response chứa errors, hoặc dữ liệu trả về sai cấu trúc.

Lưu thành kịch bản kiểm thử

Một request có assertion là bước khởi đầu tốt. Giá trị lớn hơn đến từ việc nối nhiều request thành test scenario.

Ví dụ scenario:

1. Query người dùng.
2. Tạo đơn hàng.
3. Trích xuất id đơn hàng từ mutation.
4. Query lại người dùng.
5. Xác nhận đơn hàng vừa tạo có trong danh sách.

Apidog cho phép bạn sắp xếp các bước, truyền dữ liệu giữa chúng và chạy toàn bộ luồng chỉ với một lần chạy. Xem hướng dẫn cách viết kịch bản kiểm thử với Apidog.

Ở mức triển khai:

• Tạo test scenario mới.
• Thêm query và mutation theo đúng thứ tự.
• Trích xuất id từ $.data.createOrder.id.
• Lưu giá trị đó vào biến.
• Dùng biến trong query xác nhận cuối cùng.
• Gắn assertion cho từng bước.

Kết quả là một regression test có thể chạy lại bởi developer, lịch chạy định kỳ hoặc pipeline.

Để so sánh GraphQL với các giao thức khác, xem REST vs GraphQL vs gRPC và danh sách công cụ kiểm thử và mô phỏng GraphQL. Nếu hệ thống của bạn dùng SOAP, cùng mô hình request và assertion cũng áp dụng trong hướng dẫn kiểm thử API SOAP bằng Apidog.

Tự động hóa workflow với Apidog CLI

Sau khi lưu test scenario trong project, bạn có thể chạy các kịch bản đã lưu từ terminal hoặc CI runner bằng Apidog CLI.

Cài đặt CLI và đăng nhập:

npm install -g apidog-cli
apidog login --with-token <your-token>

Chạy một test scenario theo ID và environment:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Trong đó:

• -t: ID của test scenario.
• -e: ID môi trường.
• -r: reporter, như cli, html hoặc junit.

Bạn có thể dùng nhiều reporter:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r html,cli

CLI chạy các scenario và test suite đã lưu trong cloud project, sau đó báo pass hoặc fail để tích hợp vào build.

Lưu ý: tài liệu CLI xác nhận việc chạy HTTP scenario nhưng không nêu rõ các scenario chứa GraphQL step có chạy headless hay không. Hãy dùng CLI cho regression run HTTP và đồng bộ specification qua lệnh import như OpenAPI, HAR hoặc Postman; đồng thời thực hiện query, mutation và xác nhận GraphQL trong ứng dụng khi cần.

Xem thêm:

• Hướng dẫn cài đặt Apidog CLI
• Apidog CLI trong pipeline GitHub Actions

Các câu hỏi thường gặp

Tôi có cần gói trả phí để kiểm thử GraphQL trong Apidog không?

Tài liệu GraphQL request không nêu tính năng này bị giới hạn bởi một gói cụ thể, cũng không phân biệt cloud và self-hosted. Bạn có thể bắt đầu với gói miễn phí, không cần thẻ tín dụng. Xem Apidog để biết thông tin gói hiện tại.

Tại sao GraphQL request trả về 200 nhưng vẫn thất bại?

Đây là hành vi GraphQL bình thường. HTTP transport thành công nên server trả về 200, nhưng query hoặc mutation có thể gặp lỗi nghiệp vụ, validation hoặc xác thực trong mảng errors.

Luôn kiểm tra errors bên cạnh status code, như trong hướng dẫn xác nhận API.

Làm thế nào để nhận gợi ý field khi viết query?

Nhấp Fetch Schema trong trình chỉnh sửa GraphQL. Apidog sẽ introspection endpoint và bật tự động hoàn thành cho field và type hợp lệ.

Đây là thao tác thủ công. Hãy chạy lại sau khi thay đổi endpoint hoặc schema.

Mutation nằm ở đâu? Tôi không thấy tab riêng.

Không có tab mutation riêng. Viết mutation trong cùng vùng Query, thay từ khóa query bằng mutation, truyền payload qua variables rồi nhấp Send.

Làm thế nào để truyền giá trị khác mà không sửa query?

Dùng biến GraphQL:

1. Khai báo biến với tiền tố $ trong operation signature.
2. Chỉ định type cho biến.
3. Cung cấp giá trị qua JSON variables.

Cú pháp này theo đặc tả GraphQL chuẩn. Kết hợp biến GraphQL với environment variables của Apidog để dùng một request cho cả staging và production.

Tổng kết

Để kiểm thử GraphQL hiệu quả trong Apidog:

1. Viết query hoặc mutation trong vùng Query.
2. Dùng Fetch Schema để giảm lỗi sai field và type.
3. Chuyển giá trị cố định sang variables.
4. Kiểm tra errors, không chỉ HTTP status.
5. Xác nhận dữ liệu theo các JSONPath nằm dưới data.
6. Nối query và mutation thành test scenario để chạy regression.

Hãy tải Apidog, xây dựng luồng user và order như ví dụ trên, rồi lưu nó thành bài kiểm thử GraphQL có thể chạy lại sau mỗi thay đổi schema.