# 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.

Bản gốc: https://fdetimes.net/vi/bach-khoa/thuc-hanh-kiem-thu-api-cua-khach-tu-openapi-bang-schemathesis/

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.

**Điểm mấu chốt:** Công cụ fuzzing gửi request thật: chỉ trỏ nó vào nơi được phép mất dữ liệu.

## 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:

```bash
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:

```bash
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:

```bash
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ỡ.

**Thử ngay tuần này:**

- Lấy một API nội bộ có file OpenAPI, chạy uvx schemathesis run với --url trỏ vào môi trường dev và ghi lại số lỗi 5xx tìm được
- Thêm lần chạy đó vào pipeline CI, cấu hình fail job khi exit code khác 0
- Viết một trang tóm tắt lỗi kèm request tái hiện, như thể gửi cho khách trước buổi go-live

## Nguồn

- [Schemathesis documentation (stable)](https://schemathesis.readthedocs.io/en/stable/)

- [schemathesis/schemathesis (GitHub README)](https://github.com/schemathesis/schemathesis)

- [Schemathesis reference: Checks](https://schemathesis.readthedocs.io/en/stable/reference/checks/)

- [Schemathesis reference: CLI](https://schemathesis.readthedocs.io/en/stable/reference/cli/)

- [Schemathesis guide: CI/CD](https://schemathesis.readthedocs.io/en/stable/guides/cicd/)

- [schemathesis · PyPI](https://pypi.org/project/schemathesis/)
