Một file OpenAPI và môi trường staging đủ để tìm lỗi 500 trước go-live
Schemathesis tự sinh request từ schema, nhưng chỉ được phép bắn vào staging, không bao giờ vào production.
Tóm tắt nhanh
- Schemathesis tự sinh test từ schema OpenAPI, bạn không phải viết test cho từng endpoint.
- Check not_a_server_error bắt mọi mã 5xx và được bật sẵn, chỉ max_response_time phải bật riêng.
- Công cụ gửi request thật có thể tạo, sửa, xóa dữ liệu, nên chỉ chạy trên dev hoặc staging.
Khách gửi bạn một file openapi.json cùng lời nhắn rằng tuần sau sẽ go-live. Bạn có thể tin rằng mọi endpoint đều chịu được input lạ. Hoặc bạn có thể để một công cụ tự sinh request từ chính file đó, rồi xem server có trả 500 hay không.
Cách thứ hai gọi là property-based testing, và Schemathesis làm việc này mà không bắt bạn viết test cho từng endpoint. Tài liệu của dự án mô tả rõ: chỉ cần trỏ công cụ vào schema rồi chạy, nó sẽ bắt lỗi server, vi phạm schema và lỗ hổng validation mà test viết tay thường bỏ sót.
Kỹ năng này sát với việc hằng ngày của FDE. Bạn thường phải tích hợp với API mình không viết ra, tài liệu không đầy đủ, và lỗi 500 đầu tiên mà người dùng thật gặp phải sẽ bị tính là lỗi của bạn. Bài này đi từ cài đặt đến khi có báo cáo gửi được cho khách.
Bạn sẽ dựng gì, và cần chuẩn bị gì?
Kết quả cuối cùng là một lệnh chạy được trên laptop và trong CI. Lệnh đó đọc file OpenAPI của khách, gửi request vào môi trường staging kèm token, trả exit code rõ ràng và xuất báo cáo.
Bạn cần bốn thứ. Đầu tiên là Python 3.11 trở lên, vì PyPI ghi Schemathesis yêu cầu phiên bản này; công cụ xây trên Hypothesis, một thư viện property-based testing cho Python. Kế đến là uv để chạy công cụ mà không phải cài vào project, file OpenAPI của khách, và quan trọng nhất là một base URL không phải production.
Điều kiện cuối không phải để cho có. README của Schemathesis cảnh báo thẳng rằng công cụ gửi request thật, có thể tạo, sửa và xóa dữ liệu. Trước khi chạy bất cứ thứ gì, hãy xin khách một môi trường dev hoặc staging bằng văn bản.
Bước 1: chạy lần đầu với file của khách
README đưa ra cách chạy cơ bản nhất, trỏ thẳng vào URL của schema:
uvx schemathesis run https://your-api.com/openapi.json
Nhưng ngoài thực tế, khách thường gửi file chứ không phải URL. Với schema là file local, tài liệu CLI yêu cầu bắt buộc phải có --url để chỉ ra base URL của API cần test:
uvx schemathesis run ./openapi.json \
--url https://staging.khach-hang.example
Sau bước này, hãy xác nhận rằng lệnh đã thực sự gửi request tới staging. Nếu bạn quên --url, Schemathesis không chạy được và trả exit code 2, mã dành cho lỗi cấu hình. Đây chưa phải là lỗi của API.
Bước 2: gắn token để vượt qua lớp xác thực
Lần chạy đầu thường trả về một loạt 401. Lý do đơn giản: phần lớn API của khách nằm sau lớp xác thực, và request không có token sẽ không chạm tới logic thật. Tùy chọn --header thêm header vào mọi request và có thể lặp lại nhiều lần:
uvx schemathesis run ./openapi.json \
--url https://staging.khach-hang.example \
--header "Authorization: Bearer $STAGING_TOKEN" \
--header "X-Tenant-Id: test-tenant"
Header thứ hai ở đây chỉ là ví dụ giả định, bạn thay bằng header mà API của khách thực sự cần. Giữ token trong biến môi trường, đừng dán thẳng vào lệnh để rồi nó nằm trong lịch sử shell hoặc log CI.
Kiểm tra: tỷ lệ 401/403 phải giảm mạnh. Nếu vẫn còn nhiều, hãy xem token có đủ quyền cho mọi endpoint không, trước khi kết luận API có lỗi.
Bước 3: đọc lỗi 500 như một kỹ sư, không như một người chấm điểm
Check bạn quan tâm nhất là not_a_server_error, check bắt mọi mã 5xx, trong đó có 500. Bạn không cần bật nó: theo tài liệu, mọi check đều bật mặc định, trừ max_response_time.
Thử hình dung một kết quả điển hình. Endpoint POST /orders trả 500 khi trường quantity là số âm, trong khi schema không đặt giới hạn dưới. Đây là hai vấn đề chứ không phải một: server thiếu validation, còn schema mô tả sai hợp đồng thật.
Vì thế, với mỗi lỗi, hãy ghi lại ba thứ: request tái hiện được lỗi, endpoint bị ảnh hưởng, và đề xuất sửa nằm ở code hay ở schema. Khách sẽ coi trọng danh sách này hơn nhiều so với một con số “37 lỗi”.
Bước 4: thu hẹp phase để lặp nhanh hơn
Tùy chọn --phases cho phép chọn giai đoạn cần chạy trong bốn giai đoạn: examples, coverage, fuzzing và stateful. Mặc định công cụ chạy tất cả, và đó là lựa chọn đúng cho lần quét đầu tiên lẫn lần quét cuối trước go-live.
Khi bạn đang sửa một lỗi cụ thể và chỉ muốn kiểm lại nhanh, giới hạn --phases vào một vài giai đoạn là đủ. Nhưng đừng bỏ stateful trong lần chạy đầy đủ: PyPI ghi rằng stateful testing suy ra liên kết giữa các operation từ schema.
Thử hình dung luồng tạo một đơn hàng rồi đọc lại chính đơn đó: test từng endpoint riêng lẻ không đi qua chuỗi này, còn phase stateful được thiết kế để nối các bước như vậy lại.
Bước 5: biến lần chạy thành cổng chặn trong CI
Exit code là thứ giúp Schemathesis gắn được vào pipeline. Mã 1 nghĩa là ít nhất một check đã fail hoặc có lỗi được báo cáo. Mã 2 nghĩa là chính Schemathesis không chạy được vì cấu hình sai.
Hướng dẫn CI/CD của dự án khuyên fail job mỗi khi exit code khác 0. Hướng dẫn cũng lưu ý một bẫy: lần chạy không test được gì cũng trả exit 2. Nhờ đó, một file schema rỗng hay một bộ lọc sai sẽ không lặng lẽ cho ra màu xanh.
Để có thứ gửi cho khách, công cụ xuất báo cáo ở nhiều định dạng cùng lúc, liệt kê cách nhau bằng dấu phẩy: junit, vcr, har, json, html. Lời khuyên thực tế: chọn định dạng theo người nhận. Định dạng máy đọc được dành cho pipeline CI, còn bản HTML là thứ dễ đính kèm nhất khi bạn gửi email cho khách trước go-live.
Những sai lầm khiến bạn mất lòng tin của khách
Sai lầm đắt nhất là chạy vào production. Một lần fuzz có thể tạo ra hàng loạt bản ghi rác hoặc xóa dữ liệu thật, và không lỗi 500 nào bạn tìm được bù lại nổi chuyện đó.
Sai lầm tiếp theo là tưởng mình đã kiểm tra độ trễ. max_response_time là check duy nhất không bật sẵn, nên nếu khách có SLA về thời gian phản hồi, bạn phải chủ động bật nó. Cuối cùng là đọc exit 2 thành “API hỏng” rồi báo động khách, trong khi thực ra chỉ là bạn quên --url hoặc cấu hình sai.
Kỹ năng này xuất hiện thế nào trong công việc FDE?
Ở site khách, giá trị nằm ở thời điểm. Chạy Schemathesis trong tuần đầu tích hợp cho bạn một bản đồ endpoint nào dễ vỡ, trước khi bạn xây logic lên trên chúng. Chạy lại trước go-live cho khách bằng chứng rằng hợp đồng API đã ổn.
Về nghề nghiệp, khi đọc tin tuyển dụng FDE, hãy để ý các cụm như “integrate with customer APIs” hay “production readiness”: đó là nơi kỹ năng này được dùng. Trong CV, đừng chỉ ghi “API testing”. Hãy viết theo kết quả, ví dụ: đã đưa kiểm thử dựa trên schema vào CI, tìm và tái hiện lỗi 5xx trước go-live, kèm báo cáo cho đội của khách.
Lần tới khi khách gửi file OpenAPI kèm hạn go-live, bạn không cần đoán xem API có chịu được input lạ hay không. Bạn có thể chạy một lệnh, đưa ra một báo cáo và chỉ đúng chỗ dễ vỡ.
Bài này có hữu ích không?
Cảm ơn bạn đã góp ý!