Một yêu cầu API trả về phản hồi không phải là một bài kiểm tra thành công. Nó chỉ là một phản hồi. Bài kiểm tra chỉ tồn tại khi có thứ gì đó kiểm tra xem phản hồi có chính xác hay không. Kiểm tra đó là một khẳng định (assertion), và chất lượng của các khẳng định của bạn quyết định liệu bộ kiểm thử của bạn có bắt được lỗi thực sự hay chỉ xác nhận máy chủ đang hoạt động.
Hướng dẫn này giải thích các khẳng định API là gì, các loại khẳng định đáng viết, nơi các nhóm thường mắc lỗi và cách xây dựng các khẳng định một cách trực quan trong Apidog mà không cần viết mã.
Khẳng định API là gì
Một khẳng định là một tuyên bố về một phản hồi phải đúng để bài kiểm tra vượt qua. Bạn gửi một yêu cầu, API phản hồi, và khẳng định so sánh một phần của phản hồi đó với một giá trị mong đợi. Nếu chúng khớp, vượt qua. Nếu không, thất bại.
Nếu không có khẳng định, một bài kiểm tra tự động chỉ chứng minh được rằng điểm cuối có thể truy cập được. Với chúng, nó chứng minh rằng điểm cuối là chính xác. Khoảng cách giữa hai điều này là nơi hầu hết các sự cố sản xuất tồn tại: API đã hoạt động, nó trả về mã 200, nhưng phần thân (body) lại sai.
Một khẳng định hữu ích phải cụ thể và độc lập. Cụ thể, để một lỗi chỉ ra một điều duy nhất. Độc lập, để nó không âm thầm phụ thuộc vào việc một khẳng định khác phải vượt qua trước. Một bước kiểm tra đơn lẻ thường chứa nhiều khẳng định, mỗi khẳng định kiểm tra một khía cạnh khác nhau của cùng một phản hồi.
Khẳng định mã trạng thái, và tại sao nó chưa đủ
Khẳng định phổ biến nhất kiểm tra mã trạng thái HTTP: mong đợi 200 cho một lần đọc thành công, 201 cho một tài nguyên đã tạo, 400 cho đầu vào xấu, 401 cho xác thực thiếu. Điều này là cần thiết. Việc sử dụng đúng mã trạng thái là một lĩnh vực riêng; các mã trạng thái HTTP mà API REST nên sử dụng rất đáng đọc nếu API của bạn không nhất quán ở đây.
Nhưng một khẳng định mã trạng thái đơn thuần là yếu. Một API có thể trả về 200 OK với một phần thân rỗng, một giá trị cũ, một giá trị null ở nơi lẽ ra phải có đối tượng, hoặc một thông báo lỗi được ngụy trang thành thành công. Trạng thái cho biết yêu cầu đã được xử lý. Nó không nói gì về việc dữ liệu có đúng hay không.
Hãy xem khẳng định trạng thái là dòng đầu tiên của một bước kiểm tra, chứ không bao giờ là dòng duy nhất.
Các loại khẳng định đáng viết
Khẳng định nội dung thân phản hồi. Kiểm tra các giá trị thực tế trong phản hồi. Trường id tồn tại và không rỗng. Trường email khớp với những gì bạn đã gửi. Trường total bằng tổng của các mặt hàng. Những khẳng định này bắt được các lỗi logic mà mã trạng thái bỏ sót.
Khẳng định lược đồ. Xác thực hình dạng của phản hồi dựa trên JSON Schema hoặc định nghĩa OpenAPI: các trường bắt buộc phải có, kiểu dữ liệu chính xác, không có trường không mong muốn xuất hiện. Khẳng định lược đồ bắt được sự sai lệch hợp đồng, nơi backend âm thầm thay đổi một trường từ chuỗi sang đối tượng và làm hỏng mọi client. Điều này trùng với kiểm thử hợp đồng API, một khái niệm chính thức hóa ý tưởng giữa nhà sản xuất và người tiêu dùng.
Khẳng định tiêu đề. Xác nhận rằng Content-Type là application/json, các tiêu đề bộ nhớ đệm được đặt đúng như dự định, các tiêu đề CORS có mặt, và các tiêu đề bảo mật như Strict-Transport-Security cũng có mặt.
Khẳng định thời gian phản hồi. Đặt một ngân sách độ trễ, ví dụ 800 ms, và làm cho bài kiểm tra thất bại khi phản hồi chậm hơn. Các suy giảm hiệu suất không thể nhìn thấy đối với các loại khẳng định khác, vì vậy đây là loại duy nhất có thể phát hiện chúng trong một bộ kiểm thử chức năng.
Khẳng định cấu trúc lỗi. Đối với các trường hợp tiêu cực, hãy khẳng định phần thân lỗi, chứ không chỉ mã 4xx. Trường error bằng validation_error, mảng details đặt tên trường gây lỗi và không có dữ liệu nhạy cảm nào bị rò rỉ trong thông báo.
Khẳng định bảo mật. Xác nhận rằng điểm cuối từ chối các yêu cầu không có mã thông báo, từ chối các mã thông báo đã hết hạn, thực thi quyền hạn giữa các người dùng và không lặp lại các payload tấn công dưới dạng không thoát (unescaped).
Một bước kiểm tra khẳng định trạng thái, hai hoặc ba trường trong phần thân, lược đồ và ngân sách thời gian phản hồi đang thực hiện công việc thực sự. Một bước chỉ khẳng định trạng thái chỉ mang tính trang trí.
Nơi logic khẳng định thường mắc lỗi
Khẳng định quá mức trên dữ liệu biến động. Việc khẳng định một dấu thời gian created_at chính xác hoặc một UUID được tạo ra sẽ khiến bài kiểm tra thất bại mỗi lần chạy mà không có lý do. Hãy khẳng định rằng trường tồn tại và có kiểu dữ liệu đúng, chứ không phải giá trị chính xác của nó.
Khẳng định chưa đủ trên trường hợp thành công. Bài kiểm tra trường hợp thành công là bài kiểm tra có khả năng cao nhất chỉ khẳng định mã trạng thái. Đây cũng là trường hợp người dùng truy cập nhiều nhất. Hãy cung cấp cho nó những khẳng định kỹ lưỡng nhất, chứ không phải ít nhất.
Các khẳng định phụ thuộc thứ tự. Nếu khẳng định B chỉ có ý nghĩa khi khẳng định A đã vượt qua, nhưng cả hai đều chạy một cách mù quáng, thì một lỗi ở A sẽ tạo ra một lỗi thứ hai gây nhầm lẫn ở B. Cấu trúc các bước sao cho các phụ thuộc là rõ ràng.
Một khẳng định làm hai việc. “Phản hồi chính xác” không phải là một khẳng định. Hãy chia nhỏ nó: trạng thái là 200, token tồn tại, expires_in bằng 3600. Ba kiểm tra, ba thông báo lỗi rõ ràng.
Bỏ qua các trường hợp tiêu cực. Các nhóm khẳng định rất nhiều về trường hợp thành công và hầu như không khẳng định gì về trường hợp thất bại. Một trường hợp tiêu cực không có khẳng định thân phản hồi chỉ chứng minh API đã nói "không," chứ không phải nó đã nói không một cách chính xác.
Xây dựng khẳng định trong Apidog
Trong Apidog, các khẳng định là một phần của trình xây dựng kiểm thử trực quan, vì vậy bạn định nghĩa chúng bằng cách nhấp chuột thay vì viết kịch bản.
Đối với bất kỳ yêu cầu nào trong một kịch bản kiểm thử, hãy mở bảng điều khiển khẳng định và thêm các kiểm tra:
- Khẳng định trạng thái. Chọn “trạng thái phản hồi” và đặt nó bằng
200. - Khẳng định trường thân phản hồi. Sử dụng biểu thức JSONPath như
$.tokenvà khẳng định nó tồn tại và là một chuỗi không rỗng; khẳng định$.expires_inbằng3600. Apidog đọc cấu trúc phản hồi, vì vậy bạn chọn các trường thay vì gõ đường dẫn một cách mù quáng. - Khẳng định lược đồ. Xác thực phản hồi dựa trên lược đồ đã định nghĩa của điểm cuối. Vì Apidog giữ thiết kế API và các kiểm thử trong cùng một không gian làm việc, lược đồ mà khẳng định của bạn sử dụng cũng là lược đồ mà tài liệu của bạn công bố; không có bản sao thứ hai nào có thể sai lệch.
- Khẳng định thời gian phản hồi. Thêm kiểm tra rằng thời gian phản hồi nằm dưới ngân sách của bạn.
- Kịch bản tùy chỉnh, chỉ khi cần. Đối với các logic mà các kiểm tra trực quan không thể diễn đạt, hãy sử dụng bộ xử lý hậu kỳ JavaScript. Hầu hết các khẳng định không bao giờ cần điều này.
Nhóm các khẳng định trong một kịch bản và Apidog sẽ chạy chúng cùng nhau. Để có phạm vi bao phủ có khả năng mở rộng, hãy đính kèm một tệp dữ liệu để một bộ khẳng định chạy với mỗi hàng của đầu vào kiểm thử dựa trên dữ liệu. Khi kịch bản chạy, báo cáo được tạo sẽ hiển thị chính xác khẳng định nào đã thất bại, trên yêu cầu nào, với các giá trị mong đợi và thực tế cạnh nhau.
Cùng một kịch bản chạy không thay đổi trong CI, vì vậy mỗi lần commit đều kiểm tra lại mọi khẳng định; tự động hóa kiểm thử API trong CI/CD bao gồm việc kết nối đó. Tải xuống Apidog để xây dựng một bộ khẳng định cho điểm cuối của riêng bạn.
Một bộ khẳng định đã được thực hiện
Ví dụ: GET /users/{id} trả về một đối tượng người dùng. Một bộ khẳng định vững chắc cho trường hợp thành công:
- Trạng thái bằng
200 - Tiêu đề
Content-Typechứaapplication/json $.idbằng ID được yêu cầu$.emailtồn tại và khớp với một mẫu email$.rolelà một trong các giá trịadmin,member,viewer- Thân phản hồi tuân thủ lược đồ
User - Thời gian phản hồi dưới 600 ms
Và đối với GET /users/{id} với một ID không xác định:
- Trạng thái bằng
404 $.errorbằngnot_found- Thân phản hồi không chứa
email,id, hoặc các trường người dùng khác
Hai yêu cầu, mười một khẳng định, và bạn đã xác minh hợp đồng, dữ liệu, tiêu đề, hiệu suất và hành vi lỗi. Đó là điều tạo nên sự khác biệt giữa một bộ kiểm thử bảo vệ một bản phát hành so với một bộ kiểm thử chỉ kiểm tra máy chủ.
Các khẳng định trong một quy trình CI
Các khẳng định đạt được giá trị đầy đủ khi chúng chạy tự động. Một bộ kiểm thử mà ai đó chạy thủ công mỗi tuần một lần sẽ phát hiện lỗi muộn một tuần. Cùng một bộ kiểm thử được tích hợp vào CI sẽ phát hiện chúng ngay tại pull request.
Khi các khẳng định chạy trong một quy trình, hai lựa chọn thiết kế quan trọng. Thứ nhất, lỗi phải rõ ràng. Một nhật ký CI chỉ nói “kiểm thử thất bại” buộc nhà phát triển phải tái tạo chạy cục bộ; một nhật ký nói “mong đợi $.expires_in bằng 3600, nhưng nhận được 7200 trên POST /auth/login” cho họ biết ngay lập tức phải tìm ở đâu. Các khẳng định mạnh mẽ, cụ thể là những gì tạo ra lỗi dễ hiểu đó.
Thứ hai, các khẳng định cần ổn định trên các môi trường khác nhau. Một khẳng định mã hóa cứng một id người dùng sản xuất sẽ thất bại trong môi trường staging vì một lý do không liên quan gì đến mã. Giữ các giá trị cụ thể cho từng môi trường trong các biến, và khẳng định về cấu trúc và kiểu dữ liệu nơi giá trị chính xác phụ thuộc vào môi trường. Một khẳng định lược đồ hoạt động tốt giữa các môi trường; một khẳng định trên một id được tạo cụ thể thì không.
Mẫu thực tế: khẳng định trạng thái và lược đồ trên mọi điểm cuối làm nền tảng chạy ở mọi nơi, sau đó thêm các khẳng định giá trị nhận biết môi trường lên trên. Nền tảng bắt được sự sai lệch hợp đồng trong bất kỳ môi trường nào; các khẳng định giá trị bắt được các lỗi logic khi bạn có dữ liệu ổn định. Chạy cả hai trên mỗi lần commit và bộ kiểm thử trở thành một cổng kiểm soát thay vì một báo cáo.
Các câu hỏi thường gặp
Sự khác biệt giữa một khẳng định và một trường hợp kiểm thử là gì? Một trường hợp kiểm thử là toàn bộ quá trình kiểm tra: một yêu cầu cộng với kết quả mong đợi của nó. Các khẳng định là các so sánh riêng lẻ bên trong nó quyết định pass hay fail. Xem cách viết các trường hợp kiểm thử API.
Một yêu cầu nên có bao nhiêu khẳng định? Đủ để bao gồm trạng thái, các trường thân phản hồi chính, lược đồ và ngân sách độ trễ. Đối với hầu hết các điểm cuối, đó là từ bốn đến tám. Nhiều hơn cũng tốt nếu mỗi khẳng định kiểm tra một điều riêng biệt.
Tôi có nên khẳng định toàn bộ phần thân phản hồi chính xác không? Hãy khẳng định các trường ổn định một cách chính xác và các trường biến động theo kiểu hoặc sự hiện diện. Việc khẳng định toàn bộ phần thân bao gồm dấu thời gian và ID được tạo ra sẽ tạo ra các kiểm thử thất bại trong mọi lần chạy.
Tôi có thể khẳng định hiệu suất API trong một kiểm thử chức năng không? Có. Một khẳng định thời gian phản hồi bắt được các suy giảm độ trễ trong quá trình chạy chức năng bình thường, không cần kiểm thử tải riêng biệt cho việc kiểm tra ngân sách cơ bản.
Các trường hợp kiểm thử tiêu cực có nên có khẳng định không? Tuyệt đối có, và chúng là những trường hợp thường xuyên bị bỏ qua nhất. Một trường hợp tiêu cực chỉ có kiểm tra mã trạng thái chỉ chứng minh API đã nói không, chứ không phải nó đã nói không một cách chính xác. Hãy khẳng định trường lỗi, chi tiết trường gây lỗi và sự vắng mặt của bất kỳ dữ liệu nhạy cảm nào trong thông báo.
Nên sử dụng các kịch bản khẳng định tùy chỉnh ở đâu? Hãy dành các kịch bản cho các logic mà trình xây dựng trực quan không thể diễn đạt: so sánh giữa các yêu cầu, giá trị phái sinh, hoặc các kiểm tra có điều kiện phụ thuộc vào các phản hồi trước đó. Hầu hết các khẳng định, trạng thái, lược đồ, các trường thân phản hồi và thời gian, đều sạch sẽ và dễ xem xét hơn dưới dạng các kiểm tra trực quan.