Test API cho QA manual: checklist từ status code tới hợp đồng dữ liệu

Nhiều bạn QA manual ngại test API vì nghĩ đó là việc “của dev” hoặc “của automation”. Thật ra test API là một trong những cách nhanh nhất để tìm lỗi: không phải chờ giao diện, không phải click qua năm màn hình, và lỗi tìm được thường là lỗi gốc.

Bài này là checklist để bạn bắt đầu test API một cách có hệ thống, kể cả khi chỉ dùng Postman hoặc curl.

Bước 0: Đọc API doc như đọc một bản hợp đồng

Một API doc tốt trả lời được các câu hỏi sau. Nếu thiếu, đó là câu hỏi đầu tiên gửi Dev:

Endpoint và method: GET /api/v1/prices, POST /api/v1/orders…
Tham số: tên, kiểu, bắt buộc hay không, giá trị mặc định, giá trị hợp lệ.
Response thành công: cấu trúc JSON, kiểu của từng trường, trường nào có thể null.
Response lỗi: status code và thông điệp cho từng loại lỗi.
Xác thực: cần token gì, hết hạn thì sao.
Giới hạn: phân trang, số bản ghi tối đa, giới hạn tần suất gọi.

Hãy coi API doc là hợp đồng giữa backend và frontend. Việc của bạn là kiểm xem hai bên có giữ đúng hợp đồng không.

Checklist 8 nhóm

1. Status code

Tình huống	Status thường dùng
Thành công, có dữ liệu	200
Tạo mới thành công	201
Thành công, không có nội dung	204
Tham số sai	400 hoặc 422
Chưa đăng nhập / token sai	401
Đăng nhập rồi nhưng không có quyền	403
Không tìm thấy	404
Gọi quá nhiều	429
Lỗi phía server	5xx

Lỗi hay gặp: API trả 200 kèm success: false cho mọi lỗi, hoặc trả 500 khi chỉ là tham số sai. Cả hai đều nên ghi lại để team thống nhất.

2. Tham số

Với mỗi tham số, thử:

Thiếu tham số bắt buộc.
Sai kiểu: chữ thay vì số, số thay vì ngày.
Ngoài khoảng: limit=0, limit=-1, limit=100000.
Giá trị không tồn tại: mã sản phẩm không có trong hệ thống.
Rỗng và khoảng trắng: symbol= và symbol=%20.
Ký tự đặc biệt: dấu nháy, tiếng Việt có dấu, emoji.
Tham số thừa mà API không định nghĩa: bị bỏ qua hay gây lỗi?

3. Hợp đồng dữ liệu (schema)

Mọi trường trong doc đều có mặt? Có trường lạ không có trong doc?
Kiểu dữ liệu đúng không? Số tiền trả về là số hay chuỗi?
Trường nào được phép null? Frontend có xử lý null không?
Ngày giờ theo định dạng nào (ISO 8601?), múi giờ nào?
Số thập phân có bị sai lệch do làm tròn số thực không?
Giá trị enum (trạng thái, loại) có nằm trong danh sách đã thống nhất?

4. Phân trang, sắp xếp, lọc

Trang cuối cùng, trang vượt quá tổng số trang.
Tổng số bản ghi (total) có khớp với số bản ghi thật?
Sắp xếp có ổn định không: hai lần gọi giống nhau có trả cùng thứ tự?
Lọc kết hợp nhiều điều kiện có đúng không?

5. Xác thực và phân quyền

Gọi không có token, token hết hạn, token của người dùng khác.
Người dùng A có đọc được dữ liệu của người dùng B bằng cách đổi ID trong URL không? Đây là lỗi bảo mật nghiêm trọng và rất phổ biến.

6. Tốc độ

Ghi lại thời gian phản hồi của các API chính. Ngưỡng chấp nhận nên được team thống nhất trước (ví dụ dưới 1–2 giây cho API hiển thị dữ liệu). Chú ý các API chậm dần theo lượng dữ liệu, như khi chọn kỳ 10 năm thay vì 1 năm.

7. Tính nhất quán

Gọi GET nhiều lần có trả cùng kết quả không (khi dữ liệu không đổi)?
Gọi POST hai lần liên tiếp có tạo ra hai bản ghi trùng không?

8. Đối chiếu với DB và giao diện

Đây là phần nhiều người bỏ qua nhưng lại tìm ra nhiều lỗi nhất:

API ↔ DB: dữ liệu trả về có khớp với dữ liệu trong database không? Có bị thiếu kỳ, sai đơn vị?
API ↔ UI: giao diện có hiển thị đúng những gì API trả về? Một API đúng hoàn toàn vẫn có thể bị frontend làm tròn sai, hiển thị sai đơn vị hoặc bỏ sót bản ghi.

Khi tìm được lỗi, việc chỉ ra lỗi nằm ở tầng nào giúp Dev sửa nhanh hơn rất nhiều.

Từ Postman tới script

Khi đã quen tay, bạn có thể chuyển các kiểm tra lặp lại thành script. Ví dụ với Playwright:

import { test, expect } from '@playwright/test';

test('GET /api/v1/prices trả đúng hợp đồng', async ({ request }) => {
  const res = await request.get('/api/v1/prices', {
    params: { symbol: 'GOLD', period: '1Y' },
  });
  expect(res.status()).toBe(200);

  const body = await res.json();
  expect(Array.isArray(body.data)).toBe(true);
  for (const point of body.data) {
    expect(point).toEqual(
      expect.objectContaining({
        date: expect.any(String),
        value: expect.any(Number),
      })
    );
  }
});

test('Thiếu symbol thì trả 400', async ({ request }) => {
  const res = await request.get('/api/v1/prices', { params: { period: '1Y' } });
  expect(res.status()).toBe(400);
});

Hai test trên chạy trong vài giây và có thể chạy lại sau mỗi lần deploy.

Ghi bug API để Dev tái hiện ngay

Một bug API tốt có đủ 5 thứ:

Request đầy đủ dưới dạng curl (che token): Dev copy chạy được ngay.
Response thực tế: status code và phần body liên quan.
Kỳ vọng: theo API doc mục nào, hoặc theo dữ liệu trong DB.
Môi trường: staging hay production, phiên bản build.
Tầng lỗi: lỗi ở API, ở dữ liệu nguồn, hay ở giao diện.

[API] GET /api/v1/prices trả value dạng chuỗi khi period=10Y

curl 'https://staging.example.com/api/v1/prices?symbol=GOLD&period=10Y'
→ 200, data[0] = { "date": "2016-10-01", "value": "1250.5" }

Kỳ vọng: value là số (API doc mục 3.2), giống khi period=1Y.
Ảnh hưởng: chart kỳ 10Y không vẽ được đường giá.

Kết

Test API không đòi hỏi bạn phải biết lập trình — chỉ cần đọc hiểu JSON và có tư duy kiểm tra hợp đồng. Bắt đầu bằng checklist trên với một API bạn đang test tay qua giao diện, bạn sẽ thấy nhiều lỗi lộ ra sớm hơn hẳn.