Bạn có một điểm cuối GraphQL và bạn cần biết nó có hoạt động không. Không phải là “máy chủ đang hoạt động,” mà là điều thực sự: truy vấn user có trả về các trường mà ứng dụng của bạn đọc không, một createOrder mutation có thực sự lưu trữ một đơn hàng không, và liệu các định dạng có giữ nguyên khi bạn thay đổi một biến. Một công cụ REST chỉ biết các lệnh theo đường dẫn và động từ sẽ làm điều này trở nên khó khăn. GraphQL gửi mọi thứ đến một URL dưới dạng thân POST, vì vậy bạn cần một client hiểu ngôn ngữ truy vấn, cung cấp gợi ý trường và cho phép bạn xác nhận trên dữ liệu JSON trả về.
Apidog xử lý GraphQL như một loại yêu cầu hạng nhất, bên cạnh HTTP, gRPC, WebSocket, SSE và SOAP. Hướng dẫn này sẽ trình bày cách xây dựng một yêu cầu GraphQL từ đầu: viết một truy vấn, lấy lược đồ (schema) để tự động hoàn thành mã, truyền biến, chạy một mutation và xác nhận phản hồi. Ví dụ đang chạy là một API thương mại điện tử, nơi bạn truy vấn một người dùng và các đơn hàng của họ, sau đó tạo một đơn hàng mới. Nếu bạn muốn tìm hiểu cơ sở lý thuyết về lý do tại sao GraphQL gửi một truy vấn được định kiểu duy nhất thay vì nhiều điểm cuối, tài liệu GraphQL chính thức là tài liệu tham khảo chuẩn mực, và bài so sánh REST vs GraphQL của chúng tôi sẽ đề cập đến khi nào mỗi loại phù hợp.
Bạn đang kiểm thử gì và tại sao GraphQL khác biệt
REST cung cấp cho bạn nhiều điểm cuối, mỗi điểm cuối trả về một định dạng cố định. GraphQL cung cấp cho bạn một điểm cuối và cho phép người gọi yêu cầu chính xác các trường mà họ muốn. Sự linh hoạt đó là toàn bộ vấn đề, và nó cũng là điều khiến việc kiểm thử trở nên khác biệt.
Hai điều thay đổi. Đầu tiên, yêu cầu là một tài liệu truy vấn trong phần thân, chứ không phải là một URL bạn thay đổi. Một GET /users/42 trở thành một lựa chọn user(id: 42) { ... } được gửi bằng POST. Thứ hai, GraphQL hầu như không bao giờ trả về trạng thái không phải 200 cho một lỗi nghiệp vụ. Một truy vấn thất bại vẫn trả về 200 OK với một mảng errors trong JSON. Vì vậy, kiểm tra mã trạng thái là chưa đủ. Bạn phải đọc phần thân. Thực tế duy nhất đó định hình cách bạn xác nhận sau này trong hướng dẫn này.
Apidog cung cấp cho bạn một loại thân yêu cầu GraphQL chuyên dụng, tính năng tự động hoàn thành mã nhận biết lược đồ (schema), các biến cho các truy vấn có thể tái sử dụng, và các công cụ xác nhận và kịch bản kiểm thử tương tự mà bạn sẽ sử dụng cho REST. Bạn thiết kế và chạy yêu cầu trong ứng dụng, sau đó lưu nó vào một kịch bản mà bạn có thể chạy lại. Hãy cùng xây dựng một cái.
Tạo một yêu cầu GraphQL trong Apidog
Đầu tiên, Tải xuống Apidog hoặc mở nó trong trình duyệt của bạn, sau đó mở dự án của bạn. Nếu bạn bắt đầu mới, hãy tạo một dự án để yêu cầu có nơi lưu trữ.
Bước 1: tạo một yêu cầu mới và chuyển phần thân sang GraphQL
Nhấp vào nút + và chọn New Request (Yêu cầu mới). Thao tác này sẽ mở trình tạo yêu cầu tiêu chuẩn, giống như trình bạn sẽ sử dụng cho một lệnh gọi REST: phương thức, URL, tham số và Authorization (Ủy quyền).
Đặt phương thức thành POST và dán điểm cuối GraphQL của bạn vào thanh URL. Một điểm cuối điển hình trông như thế này:
https://api.yourstore.com/graphql
Bây giờ hãy nói cho Apidog biết đây là một yêu cầu GraphQL. Trong khu vực phần thân yêu cầu, nhấp vào Body (Thân), sau đó chọn GraphQL. Trình chỉnh sửa thân sẽ chuyển sang chế độ xem nhận biết GraphQL với một hộp Query (Truy vấn), nơi chứa ngôn ngữ truy vấn.
Nếu điểm cuối của bạn cần một token, hãy mở phần Authorization (Ủy quyền) và thêm nó vào đó, ví dụ như một Bearer token. Việc xác thực trên một yêu cầu GraphQL hoạt động tương tự như bất kỳ yêu cầu HTTP nào khác trong Apidog, bởi vì về cơ bản nó vẫn là một HTTP POST.
Bước 2: viết truy vấn đầu tiên của bạn
Trên tab Run (Chạy), gõ truy vấn của bạn vào hộp Query (Truy vấn). Bắt đầu với một cái gì đó cụ thể. Ở đây bạn muốn một người dùng và các đơn hàng được đính kèm với họ:
query GetUserWithOrders {
user(id: "usr_1024") {
id
name
email
orders {
id
total
status
createdAt
}
}
}
Điều này yêu cầu một người dùng và một danh sách lồng ghép các đơn hàng của họ. Tên trường phải khớp chính xác với lược đồ (schema) của máy chủ của bạn. Nếu lược đồ của bạn gọi nó là emailAddress thay vì email, truy vấn này sẽ thất bại. Đó là nhiệm vụ của bước tiếp theo để ngăn chặn điều này.
Bước 3: lấy lược đồ (schema) để tự động hoàn thành mã
Việc đoán tên trường là nơi kiểm thử GraphQL trở nên chậm chạp. Apidog có thể đọc lược đồ của bạn để trình chỉnh sửa gợi ý các trường và loại hợp lệ khi bạn gõ, thay vì bạn phải đối chiếu tài liệu ở một tab khác.
Đây là một hành động thủ công, theo yêu cầu. Nhấp vào nút Fetch Schema (Lấy lược đồ) trong hộp nhập liệu. Apidog chạy một truy vấn introspection đối với điểm cuối của bạn và kéo hệ thống kiểu dữ liệu. Khi thành công, tính năng tự động hoàn thành mã sẽ bật: bắt đầu gõ một trường bên trong một lựa chọn và bạn sẽ nhận được các gợi ý kiểu IntelliSense về những gì thực sự có sẵn trên kiểu đó.
Hai điều đáng lưu ý. Tự động hoàn thành mã không tự động; nó chỉ bật sau khi bạn nhấp vào Fetch Schema. Và nếu điểm cuối của bạn đã tắt introspection (một số máy chủ sản xuất làm vậy vì lý do bảo mật), việc lấy sẽ không trả về lược đồ, vì vậy bạn sẽ phải tự viết các trường dựa trên tài liệu của riêng bạn. Nếu việc lấy hoạt động, hãy lấy lại nó sau bất kỳ thay đổi lược đồ nào để các gợi ý luôn cập nhật.
Bước 4: chạy và đọc phản hồi
Nhấp vào Send (Gửi). Phản hồi xuất hiện ở nửa dưới của giao diện. Một kết quả tốt trông như thế này:
{
"data": {
"user": {
"id": "usr_1024",
"name": "Dana Whitfield",
"email": "dana@example.com",
"orders": [
{ "id": "ord_5001", "total": 89.90, "status": "SHIPPED", "createdAt": "2026-07-01T09:14:00Z" },
{ "id": "ord_5002", "total": 12.50, "status": "PENDING", "createdAt": "2026-07-12T16:03:00Z" }
]
}
}
}
Lưu ý khóa data cấp cao nhất. Mọi phản hồi GraphQL đều lồng kết quả của bạn dưới data, và mọi vấn đề đều xuất hiện trong một mảng errors cùng cấp. Hãy ghi nhớ cấu trúc đó, bởi vì các xác nhận của bạn sẽ trỏ đến data.user..., chứ không phải ở gốc.
Truyền biến để làm cho yêu cầu có thể tái sử dụng
Việc gán cứng "usr_1024" vào truy vấn chỉ hoạt động một lần. Đối với một yêu cầu bạn sẽ chạy lại trên nhiều người dùng và môi trường, hãy di chuyển giá trị đó vào một biến. GraphQL có cú pháp biến hạng nhất cho điều này, và Apidog hỗ trợ nó. Cú pháp này là GraphQL tiêu chuẩn chứ không phải là sáng tạo của Apidog, vì vậy tài liệu GraphQL chính thức về biến là nguồn đáng tin cậy.
Khai báo biến trong chữ ký truy vấn với tiền tố $ và một kiểu, sau đó sử dụng nó trong các đối số:
query GetUserWithOrders($userId: ID!) {
user(id: $userId) {
id
name
orders {
id
total
status
}
}
}
Sau đó cung cấp giá trị dưới dạng một đối tượng JSON nhỏ chứa các biến:
{
"userId": "usr_1024"
}
Bây giờ, cùng một truy vấn sẽ chạy cho bất kỳ người dùng nào bằng cách thay đổi một giá trị JSON. Kết hợp điều này với các biến môi trường của Apidog và bạn có thể trỏ yêu cầu giống hệt nhau vào môi trường staging và production mà không cần chỉnh sửa truy vấn. Đây là điều biến một lệnh gọi một lần thành thứ bạn có thể lưu, chia sẻ và chạy trong một bộ kiểm thử.
Viết một mutation để tạo đơn hàng
Một mutation thay đổi dữ liệu. Trong GraphQL không có giao thức hoặc giao diện người dùng riêng biệt cho nó; một mutation được viết dưới dạng GraphQL trong cùng hộp Query, với từ khóa mutation thay vì query. Vì vậy, quy trình làm việc bạn đã biết được áp dụng trực tiếp.
Ở đây bạn tạo một đơn hàng cho người dùng mà bạn đã truy vấn trước đó:
mutation CreateOrder($input: CreateOrderInput!) {
createOrder(input: $input) {
id
total
status
createdAt
}
}
Các biến mang tải trọng (payload):
{
"input": {
"userId": "usr_1024",
"items": [
{ "sku": "TSHIRT-BLK-M", "quantity": 2 },
{ "sku": "MUG-CERAMIC", "quantity": 1 }
],
"currency": "USD"
}
}
Nhấp vào Send (Gửi). Một phản hồi tốt sẽ lặp lại đơn hàng đã tạo:
{
"data": {
"createOrder": {
"id": "ord_5003",
"total": 42.30,
"status": "PENDING",
"createdAt": "2026-07-15T10:22:11Z"
}
}
}
Vì các mutation ghi dữ liệu thực, hãy chạy chúng trên môi trường thử nghiệm hoặc staging, không phải production. Một mẫu phổ biến là chạy mutation, lấy id được trả về, sau đó chạy lại truy vấn GetUserWithOrders của bạn và xác nhận đơn hàng mới hiển thị trong danh sách. Vòng lặp truy vấn-mutation-truy vấn đó là một kiểm tra end-to-end thực tế, và đó chính xác là loại điều bạn sẽ muốn lưu dưới dạng một kịch bản trong phần tiếp theo.
Xác nhận phản hồi thay vì chỉ nhìn bằng mắt
Việc đọc JSON bằng tay là ổn khi bạn đang khám phá. Đối với một bài kiểm thử chạy tự động, bạn cần các xác nhận tự động đạt hoặc thất bại. Apidog cho phép bạn thêm các xác nhận vào một yêu cầu để một lần chạy được đánh giá tự động, đây là những gì bạn thiết lập trong xác nhận API.
Đối với GraphQL, ba kiểm tra bao gồm hầu hết các trường hợp:
- Xác nhận trạng thái HTTP là
200. Cần thiết nhưng không đủ, vì GraphQL trả về 200 ngay cả khi có lỗi nghiệp vụ. - Xác nhận rằng trường
errorskhông tồn tại. Đây là cổng đạt hay thất bại thực sự của GraphQL. Nếuerrorstồn tại, hoạt động đã thất bại bất kể trạng thái nói gì. - Xác nhận các giá trị cụ thể bên trong
data, sử dụng JSONPath như$.data.createOrder.statusbằngPENDING, hoặc$.data.user.orderscó độ dài lớn hơn không.
Sự kết hợp đó bắt được các chế độ thất bại mà kiểm tra trạng thái đơn thuần bỏ lỡ: một truy vấn trả về 200 với một mảng errors, hoặc một truy vấn thành công nhưng trả về định dạng sai. Trỏ các xác nhận giá trị của bạn vào đường dẫn lồng ghép dưới data, khớp với cấu trúc phản hồi bạn đã thấy trước đó.
Lưu nó vào một kịch bản kiểm thử
Một yêu cầu được xác nhận đơn lẻ là một bài kiểm thử sơ bộ tốt. Lợi ích thực sự là việc xâu chuỗi các yêu cầu thành một kịch bản: truy vấn người dùng, tạo đơn hàng, sau đó truy vấn lại để xác nhận nó đã được lưu trữ. Các kịch bản kiểm thử của Apidog cho phép bạn sắp xếp các bước này, truyền dữ liệu giữa chúng (lấy id từ mutation, đưa vào truy vấn xác nhận), và chạy toàn bộ luồng chỉ với một cú nhấp chuột. Hướng dẫn chi tiết nằm trong cách viết kịch bản kiểm thử với Apidog.
Ở cấp độ cao: tạo một kịch bản kiểm thử mới, thêm truy vấn và mutation GraphQL của bạn theo thứ tự các bước, trích xuất id đơn hàng từ phản hồi mutation vào một biến, và tham chiếu biến đó trong bước truy vấn cuối cùng. Đính kèm các xác nhận từ phần trước vào mỗi bước. Bây giờ bạn có một bài kiểm thử hồi quy có thể lặp lại cho API GraphQL của mình mà con người, một lịch trình hoặc một pipeline có thể chạy.
Đối với các nhóm đang cân nhắc GraphQL so với các kiểu khác trước khi cam kết, bài phân tích của chúng tôi về REST vs GraphQL vs gRPC và tổng hợp các công cụ kiểm thử và mô phỏng GraphQL đều giúp bạn đặt quy trình làm việc này vào bối cảnh. Và nếu ngăn xếp công nghệ của bạn cũng sử dụng SOAP, cùng một mẫu yêu cầu và xác nhận cũng áp dụng trong cách kiểm thử API SOAP trong Apidog.
Tự động hóa quy trình làm việc với Apidog CLI
Khi các kịch bản GraphQL của bạn đã có trong dự án, bạn có thể chạy các kịch bản kiểm thử đã lưu của dự án từ một terminal hoặc CI runner bằng Apidog CLI. Cài đặt và đăng nhập:
npm install -g apidog-cli
apidog login --with-token <your-token>
Sau đó chạy một kịch bản đã lưu theo ID, trỏ đến một môi trường:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Ở đây, -t là ID kịch bản kiểm thử, -e là ID môi trường, và -r là trình báo cáo (cli, html, hoặc junit; phân tách bằng dấu phẩy, ví dụ -r html,cli, để có nhiều hơn một). CLI chạy các kịch bản và bộ kiểm thử đã lưu từ dự án đám mây của bạn và báo cáo đạt hoặc thất bại, đây là cách kết nối Apidog vào một bản dựng. Một lưu ý chân thành: tài liệu CLI xác nhận việc thực thi kịch bản HTTP, và nó không nêu rõ liệu các kịch bản chứa các bước GraphQL có chạy không giao diện hay không. Hãy coi CLI là công cụ của bạn cho các lần chạy hồi quy HTTP và để giữ các thông số kỹ thuật đồng bộ thông qua lệnh import của nó (OpenAPI, HAR, Postman, và nhiều hơn nữa), và thực hiện công việc truy vấn, mutation và xác nhận GraphQL của bạn trong ứng dụng. Xem hướng dẫn cài đặt Apidog CLI để thiết lập token và Apidog CLI trong một pipeline GitHub Actions để kết nối nó vào CI.
Các câu hỏi thường gặp (FAQ)
Tôi có cần gói trả phí để kiểm thử GraphQL trong Apidog không? Tài liệu yêu cầu GraphQL không giới hạn tính năng này đằng sau một cấp gói, và họ cũng không phân biệt giữa đám mây và tự lưu trữ. Bạn có thể bắt đầu với gói miễn phí: dùng thử miễn phí, không yêu cầu thẻ tín dụng, và xem Apidog để biết chi tiết gói hiện tại.
Tại sao yêu cầu GraphQL của tôi trả về 200 nhưng vẫn thất bại? Đó là hành vi GraphQL bình thường. Việc truyền tải thành công, vì vậy trạng thái HTTP là 200, nhưng hoạt động gặp phải lỗi nghiệp vụ hoặc xác thực nằm trong mảng errors của phần thân JSON. Luôn xác nhận rằng errors không tồn tại ngoài việc kiểm tra trạng thái, như đã đề cập trong xác nhận API.
Làm cách nào để nhận gợi ý trường khi viết truy vấn? Nhấp vào nút Fetch Schema (Lấy lược đồ) trong hộp nhập liệu. Apidog introspection điểm cuối của bạn và bật tính năng tự động hoàn thành mã để trình chỉnh sửa gợi ý các trường và kiểu hợp lệ. Đây là một bước thủ công, không tự động, vì vậy hãy nhấp vào nó sau khi URL điểm cuối của bạn được thiết lập, và lấy lại sau bất kỳ thay đổi lược đồ nào.
Mutation đi đâu? Tôi không thấy tab mutation riêng biệt. Không có tab riêng. Một mutation được viết dưới dạng GraphQL trong cùng hộp Query, sử dụng từ khóa mutation thay vì query. Truyền tải trọng của nó thông qua các biến, sau đó nhấp Send (Gửi), giống như một truy vấn.
Làm cách nào để truyền các giá trị khác nhau mà không cần viết lại truy vấn? Sử dụng biến GraphQL. Khai báo chúng trong chữ ký hoạt động với tiền tố $ và cung cấp một đối tượng JSON các giá trị. Cú pháp tuân theo đặc tả GraphQL tiêu chuẩn, và hỗ trợ biến của Apidog kết hợp với các biến môi trường để một yêu cầu chạy trên cả môi trường staging và production.
Tổng kết
Kiểm thử GraphQL gói gọn trong một vài thói quen trung thực: viết truy vấn vào hộp Query, lấy lược đồ để trình chỉnh sửa hỗ trợ bạn, di chuyển các giá trị cố định vào biến, và xác nhận trên phần thân thay vì tin tưởng vào mã trạng thái. Chạy một mutation theo cùng một cách bạn chạy một truy vấn, sau đó xâu chuỗi cả hai vào một kịch bản đã lưu để kiểm tra lặp lại. Tải xuống Apidog để làm theo, xây dựng luồng người dùng và đơn hàng ở trên, và bạn sẽ có một bài kiểm thử hồi quy GraphQL mà bạn có thể chạy lại bất cứ khi nào lược đồ của bạn thay đổi.