Dùng OpenAPI làm hợp đồng để AI tạo test API có kiểm soát

Đừng chỉ đưa endpoint cho AI rồi chờ test happy path. Dùng OpenAPI làm đầu vào có cấu trúc để AI lập ma trận kiểm thử, chỉ ra khoảng trống yêu cầu và sinh khung test bám sát repository.

Đưa cho AI một endpoint rồi hỏi “viết test API” thường chỉ tạo ra vài ca happy path. Những tình huống dễ sót hơn — thiếu dữ liệu bắt buộc, sai kiểu dữ liệu, response lệch schema, xác thực hoặc phân quyền chưa rõ — phụ thuộc trực tiếp vào ngữ cảnh bạn cung cấp.

OpenAPI giúp QA bắt đầu đúng chỗ: thay vì mô tả API bằng vài câu rời rạc, hãy đưa cho AI một hợp đồng có cấu trúc. Khi đó, AI không cần đoán API làm gì; nó có thể chuyển endpoint, request, response và schema thành checklist kiểm thử, rồi thành khung mã để bạn review.

OpenAPI là gì và hữu ích thế nào khi test API?

OpenAPI Specification (OAS) định nghĩa một giao diện chuẩn, không phụ thuộc ngôn ngữ, để con người và công cụ hiểu khả năng của HTTP API mà không cần truy cập mã nguồn hoặc quan sát lưu lượng mạng.

Một OpenAPI Description có thể được biểu diễn bằng JSON hoặc YAML. Đặc tả cũng cho biết tên field có phân biệt chữ hoa, chữ thường, trừ các trường hợp được nêu khác đi.

Cùng một OpenAPI Description có thể phục vụ nhiều mục đích: sinh tài liệu, sinh client hoặc server, và hỗ trợ công cụ kiểm thử. Với QA, đây là đầu vào tốt hơn nhiều so với một mô tả endpoint ngắn trong ticket.

> Hãy xem OpenAPI là hợp đồng để kiểm tra, không chỉ là giao diện Swagger để thử request thủ công.

Nếu hợp đồng mô tả rõ request và response, AI có cơ sở để đề xuất test. Nếu đặc tả thiếu chi tiết, AI vẫn có thể tạo mã trông hợp lý, nhưng expected result có thể chỉ là phỏng đoán.

Trước khi dùng AI, kiểm tra OpenAPI có các thông tin sau hay chưa:

Path và HTTP method. Path parameter, query parameter, header và request body. Field bắt buộc, kiểu dữ liệu, enum, format hoặc các ràng buộc đã khai báo. Response và schema tương ứng. Cơ chế xác thực, nếu đã được mô tả. Ví dụ request/response đã được team xác nhận, nếu có.

Quy trình: từ OpenAPI đến test case và mã tự động

1. Chốt đúng phiên bản hợp đồng

OAS sử dụng phiên bản major.minor.patch. Phần major.minor biểu thị bộ tính năng; bản patch chủ yếu sửa lỗi hoặc làm rõ nội dung đặc tả.

Theo OAS, tooling hỗ trợ một dòng phiên bản như 3.1 nên tương thích với các bản 3.1.. Tuy vậy, khi làm việc thực tế, hãy nêu rõ file OpenAPI và phiên bản đang áp dụng trong prompt. Đừng lấy một đoạn YAML cũ trong chat để sinh test cho API đã thay đổi.

Nếu dùng YAML, OAS khuyến nghị YAML 1.2 và khuyến cáo không dựa vào các giá trị YAML không thể biểu diễn trong JSON. Chi tiết này có thể ảnh hưởng đến cách parser hoặc công cụ xử lý tài liệu.

2. Yêu cầu AI lập ma trận test trước khi sinh code

GitHub khuyến nghị prompt cần cụ thể, bao gồm edge case, xử lý lỗi và kiểm tra dữ liệu. Với API testing, hãy tách thiết kế test khỏi viết test automation.

Dùng AI để tạo ma trận test trước. Chỉ sinh code sau khi QA, dev hoặc BA đã review các giả định.

text Bạn là QA automation engineer.

Dựa duy nhất trên OpenAPI Description dưới đây, hãy tạo ma trận test cho: <HTTPMETHOD> <PATH>

Yêu cầu: Không tự giả định business rule không có trong đặc tả. Phân nhóm: happy path, validation, dữ liệu biên, xác thực, phân quyền và response contract. Nếu OpenAPI không mô tả xác thực hoặc phân quyền, ghi rõ “cần xác nhận”, không tự đặt status code. Mỗi test gồm: mục tiêu, precondition, dữ liệu gửi, expected HTTP response, expected body/header. Liệt kê các khoảng trống trong OpenAPI khiến assertion chưa đáng tin cậy.

Kết quả cần hướng đến là một bảng nháp để review, không phải một file test dài mà team chưa biết có thiếu yêu cầu hay không.

Cột “cần xác nhận” đặc biệt hữu ích. Nó biến phần AI chưa thể kết luận thành câu hỏi cụ thể cho owner API, chẳng hạn:

Endpoint có yêu cầu token không? Vai trò nào được phép gọi endpoint? Lỗi validation trả về status và body theo cấu trúc nào? Response lỗi có schema riêng không?

3. Review riêng validation, auth, role và dữ liệu biên

Khi AI trả về ma trận test, QA có thể rà theo checklist sau:

Xác thực: thiếu credential, credential không hợp lệ, credential hợp lệ. Chỉ chốt expected status khi hợp đồng hoặc quy ước dự án đã nêu rõ. Phân quyền: chạy cùng request với các vai trò khác nhau. Nếu OpenAPI không mô tả role, đưa thành câu hỏi cần làm rõ. Dữ liệu bắt buộc: bỏ từng field được đánh dấu required. Kiểu dữ liệu: gửi giá trị không khớp schema. Dữ liệu biên: kiểm tra min/max khi đặc tả có khai báo; không tự đặt giới hạn. Response contract: kiểm tra status, content type, field bắt buộc, kiểu dữ liệu và enum đã mô tả. Tính nhất quán: kiểm tra path parameter, query parameter và body có đúng tên theo hợp đồng hay không.

Vì các field trong OpenAPI Description có phân biệt chữ hoa, chữ thường, đừng để AI tự “chuẩn hóa” tên field chỉ vì thấy cách viết khác đẹp hơn. Một thay đổi như orderId thành orderid có thể khiến request không còn khớp với API.

Ví dụ: từ spec đến pytest hoặc Playwright API

Giả sử OpenAPI mô tả endpoint tạo tài nguyên:

Request body có field name bắt buộc. Có response thành công. Có response lỗi validation. Không mô tả quyền theo role.

Trong trường hợp này, AI không nên tự kết luận “admin được phép, user bị cấm”. Một ma trận test phù hợp hơn sẽ gồm:

Gửi name hợp lệ: kiểm tra response thành công theo contract. Bỏ name: kiểm tra response lỗi validation theo contract. Gửi name sai kiểu: kiểm tra response lỗi nếu schema đã mô tả kiểu. Gửi credential thiếu hoặc sai: đánh dấu expected result là cần xác nhận nếu hợp đồng chưa mô tả. Gọi với từng role: đưa vào danh sách cần bổ sung đặc tả, chưa hard-code assertion.

Sau khi duyệt ma trận, mới yêu cầu AI sinh mã theo framework đang dùng trong repository:

text Chuyển các test case đã được duyệt bên dưới thành test API cho <pytest hoặc Playwright API>.

Ràng buộc: Giữ nguyên endpoint, tên field, request và expected result đã duyệt. Dùng fixture, helper, cách đặt tên và cơ chế cấu hình base URL hiện có. Không hard-code token, mật khẩu, URL môi trường hoặc dữ liệu production. Nếu repository đang tách dữ liệu test khỏi mã, hãy giữ cấu trúc đó. Nếu thiếu thông tin để mã chạy được, đặt TODO rõ ràng thay vì tự bịa. Trả về: file test, fixture/helper cần thêm và biến môi trường cần cấu hình.

GitHub cũng lưu ý rằng việc mở các file test có sẵn ở những tab lân cận có thể giúp Copilot nhận ra framework và phong cách test hiện tại. Đây là cách đơn giản để tăng khả năng output dùng đúng fixture, assertion và convention của dự án.

Review output AI trước khi đưa vào CI

GitHub nêu rõ test do Copilot tạo có thể không bao phủ mọi tình huống và cần được review. Đừng coi mã AI sinh ra là bằng chứng API đã được kiểm thử đầy đủ.

Trước khi merge, kiểm tra:

Traceability: mỗi test map được về path, method, schema hoặc response nào trong OpenAPI? Expected result: AI có tự đoán status code, error message hoặc business rule không? Assertion: test chỉ kiểm tra status thành công, hay đã kiểm tra response contract? Test data: dữ liệu có phù hợp với cách quản lý dữ liệu test của dự án không? Phụ thuộc môi trường: test có dựa vào dữ liệu dùng chung, thời gian chờ hoặc trạng thái khó kiểm soát không? Secrets: token, cookie, mật khẩu hoặc dữ liệu production có xuất hiện trong prompt, mã hay log không?

Không đưa credential và dữ liệu thật của production vào công cụ AI công khai. Dùng placeholder, dữ liệu giả lập hoặc công cụ đã được tổ chức phê duyệt.

Checklist cho ticket tiếp theo

[ ] OpenAPI đúng phiên bản và khớp endpoint cần test. [ ] AI đã lập ma trận test trước khi sinh code. [ ] Validation, dữ liệu biên, auth và role được review riêng. [ ] Mọi giả định của AI đã được đánh dấu hoặc xác nhận. [ ] Code AI sinh bám fixture và convention của repository. [ ] Test được chạy trong môi trường phù hợp trước khi vào CI. [ ] Không có secret hoặc dữ liệu production trong prompt và mã.

AI không thay QA quyết định điều gì là đúng. Nhưng khi OpenAPI đủ rõ, AI có thể hỗ trợ tốt phần tốn công: chuyển hợp đồng thành tình huống kiểm thử, chỉ ra khoảng trống và dựng khung automation để tester tập trung vào rủi ro thực sự.