Nếu bạn có một lược đồ OpenAPI hoặc GraphQL, Schemathesis có thể biến nó thành hàng ngàn trường hợp thử nghiệm mà không cần bạn viết bất kỳ câu lệnh khẳng định nào. Nó đọc đặc tả, tạo ra các đầu vào ngẫu nhiên và hợp lệ, gửi chúng đến API của bạn và báo cáo những nơi mà các phản hồi vi phạm hợp đồng. Hướng dẫn này giải thích Schemathesis là gì, cách cài đặt và chạy nó, ý nghĩa thực sự của thử nghiệm dựa trên thuộc tính, và cách nó phù hợp với quy trình thử nghiệm chức năng và thử nghiệm hợp đồng trong Apidog.
Tải ứng dụng
Schemathesis là gì?
Schemathesis là một công cụ Python mã nguồn mở tự động tạo các bài kiểm tra API từ một lược đồ. Bạn hướng nó đến một định nghĩa OpenAPI hoặc GraphQL, và nó xây dựng các trường hợp thử nghiệm từ các kiểu, định dạng và ràng buộc mà bạn đã khai báo. Nó được xây dựng dựa trên Hypothesis, thư viện kiểm thử dựa trên thuộc tính cho Python, và được phân phối theo giấy phép MIT.
Ý tưởng cốt lõi rất đơn giản. Đặc tả của bạn đã mô tả một yêu cầu và phản hồi hợp lệ trông như thế nào. Schemathesis coi mô tả đó là một nguồn đáng tin cậy và kiểm tra xem API đang chạy của bạn có thực sự tuân thủ nó hay không. Khi API trả về mã 500, gửi phản hồi vi phạm lược đồ đã khai báo, hoặc chấp nhận đầu vào đáng lẽ phải bị từ chối, Schemathesis sẽ gắn cờ báo hiệu.
Bạn chạy nó từ dòng lệnh bằng schemathesis run (hoặc biệt danh ngắn hơn là st run). Ngoài ra còn có tích hợp Python nếu bạn muốn điều khiển nó từ pytest thay vì CLI. Hầu hết các nhóm bắt đầu với CLI vì nó gần như không cần thiết lập gì.
Ý nghĩa của kiểm thử dựa trên thuộc tính
Hầu hết các bài kiểm tra API đều dựa trên ví dụ. Bạn viết một yêu cầu, bạn khẳng định về một phản hồi cụ thể, và bài kiểm tra đó sẽ đạt hoặc thất bại chỉ trong một trường hợp đó. Điều đó hữu ích, nhưng bạn chỉ bắt được những lỗi mà bạn nghĩ đến để viết bài kiểm tra.
Kiểm thử dựa trên thuộc tính thay đổi cách tiếp cận. Thay vì một ví dụ cố định, bạn mô tả một thuộc tính luôn phải đúng, sau đó để công cụ tạo ra hàng trăm đầu vào để cố gắng phá vỡ nó. Đối với Schemathesis, thuộc tính đó đại khái là: “không có yêu cầu hợp lệ nào được phép làm sập máy chủ hoặc tạo ra phản hồi vi phạm lược đồ.”
Schemathesis tạo đầu vào từ các ràng buộc trong đặc tả của bạn. Nếu một trường là số nguyên có giá trị tối thiểu là 1, nó sẽ thử 1, các số lớn, giá trị biên và các loại đầu vào có thể làm mất tác dụng của xác thực đơn giản. Khi một bài kiểm tra thất bại, Hypothesis sẽ thu nhỏ đầu vào xuống trường hợp nhỏ nhất vẫn tái tạo được lỗi, nhờ đó bạn có được một bản tái hiện tối thiểu, dễ đọc thay vì một tải trọng ngẫu nhiên 4KB.
Điều này khác với kiểm thử khỉ (monkey testing), vốn chỉ ném đầu vào ngẫu nhiên vào một giao diện để xem điều gì sẽ xảy ra. Kiểm thử dựa trên thuộc tính có cấu trúc. Nó sử dụng lược đồ để tạo ra các đầu vào hợp lý và có mục tiêu, và nó biết kết quả đúng phải như thế nào vì đặc tả đã chỉ ra.
Cài đặt và chạy Schemathesis
Schemathesis là một gói Python, vì vậy bạn cần Python 3 và pip. Cài đặt nó theo cách thông thường:
pip install schemathesis
Bạn cũng có thể chạy nó mà không cần cài đặt vĩnh viễn bằng uvx schemathesis nếu bạn đã thiết lập uv. Sau khi cài đặt, lệnh cơ bản sẽ trỏ đến một lược đồ và một URL cơ sở:
st run http://127.0.0.1:8000/openapi.json
Nếu lược đồ của bạn nằm trên đĩa thay vì đằng sau một URL, hãy truyền đường dẫn tệp và cho Schemathesis biết API đang hoạt động ở đâu:
st run ./openapi.yaml --url http://127.0.0.1:8000
Đối với một API được xác thực, hãy thêm một tiêu đề (header):
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer your-token'
Schemathesis khám phá mọi thao tác trong đặc tả, tạo các trường hợp cho từng thao tác và in ra một bản tóm tắt về những kiểm tra nào đã vượt qua và những kiểm tra nào đã thất bại. Các lỗi thất bại đi kèm với yêu cầu chính xác mà nó đã gửi, vì vậy bạn có thể phát lại chúng bằng curl hoặc bất kỳ ứng dụng khách API nào. Tên cờ và giá trị mặc định thay đổi giữa các phiên bản chính, vì vậy hãy kiểm tra st run --help với phiên bản đã cài đặt của bạn thay vì tin tưởng vào một đoạn blog, kể cả đoạn này.
Những gì Schemathesis phát hiện
Các kiểm tra mặc định nhắm vào khoảng cách giữa những gì đặc tả của bạn hứa hẹn và những gì máy chủ của bạn thực hiện. Dưới đây là những gì thường được phát hiện.
| Vấn đề | Trông như thế nào |
|---|---|
| Lỗi máy chủ | Một yêu cầu kích hoạt mã 500 thay vì mã 4xx được xử lý hoặc một phản hồi hợp lệ |
| Vi phạm lược đồ | Nội dung phản hồi không khớp với lược đồ bạn đã khai báo cho mã trạng thái đó |
| Không khớp mã trạng thái | API trả về một mã trạng thái mà đặc tả chưa bao giờ ghi nhận |
| Lệch loại nội dung | Loại nội dung phản hồi không khớp với những gì đặc tả quảng cáo |
| Lỗi trạng thái | Một thao tác hoạt động độc lập nhưng thất bại trong một quy trình làm việc nhiều bước thực tế |
Vấn đề cuối cùng đáng để xem xét kỹ hơn. Schemathesis có thể chạy các kiểm thử có trạng thái, nơi nó xâu chuỗi các thao tác lại với nhau dựa trên các liên kết trong đặc tả của bạn, ví dụ: tạo một tài nguyên, sau đó lấy nó, sau đó xóa nó. Các lỗi chỉ xuất hiện theo trình tự, như một tài nguyên báo cáo trạng thái sai sau khi cập nhật, rất khó tìm thấy bằng các kiểm thử một yêu cầu. Pha trạng thái điều khiển các trình tự đó như một máy trạng thái.
Bạn có thể mở rộng hành vi mặc định bằng các hook. Hook là các hàm Python cho phép bạn tùy chỉnh việc tạo dữ liệu, thêm các kiểm tra của riêng mình hoặc lọc những thao tác nào được kiểm tra. Đó là cách các nhóm điều chỉnh Schemathesis cho các API có luồng xác thực hoặc các ràng buộc không rõ ràng mà đặc tả không thể diễn tả.
Khi nào nên sử dụng Schemathesis
Schemathesis chứng tỏ giá trị của mình khi bạn có một đặc tả OpenAPI hoặc GraphQL đủ chính xác và bạn muốn có độ bao phủ rộng, hiệu quả về chi phí cho các trường hợp biên. Nó mạnh mẽ trong việc tìm ra những lỗi mà bạn sẽ không bao giờ viết kiểm thử thủ công: các đầu vào không được xử lý, các hình dạng lỗi không được ghi lại và sự lệch lạc hợp đồng giữa đặc tả và triển khai.
Nó phù hợp tốt khi:
- Bạn duy trì một đặc tả OpenAPI và muốn nó được thực thi đối với máy chủ thực.
- Bạn lo lắng về các lỗi 500 không được xử lý và muốn có một lớp fuzzing trong CI.
- API của bạn có các quy trình làm việc có trạng thái mà thứ tự rất quan trọng.
- Nhóm của bạn đã làm việc với Python và quen thuộc với
pipvàpytest.
Nó kém phù hợp hơn khi đặc tả của bạn mỏng hoặc lỗi thời, vì Schemathesis chỉ có thể kiểm tra những gì lược đồ mô tả. Đầu vào rác, đầu ra rác. Nó cũng sẽ không thay thế các bài kiểm tra chức năng dựa trên ví dụ của bạn. Biết rằng một điểm cuối không bao giờ gặp sự cố không giống như biết rằng nó trả về giá trị đúng cho một đầu vào đã biết. Bạn muốn cả hai.
Schemathesis và Apidog: vai trò của mỗi công cụ
Apidog và Schemathesis giải quyết các vấn đề khác nhau, và chúng hoạt động tốt khi kết hợp cùng nhau. Apidog là một nền tảng tất cả trong một để thiết kế, gỡ lỗi, kiểm thử, mô phỏng và tài liệu hóa API. Schemathesis là một công cụ fuzzing dựa trên thuộc tính có trọng tâm. Việc thành thật về ranh giới ở đây rất quan trọng.
Apidog không thực hiện fuzzing dựa trên thuộc tính. Tính năng gần nhất của nó là kiểm thử khỉ (monkey testing), vốn gửi đầu vào ngẫu nhiên để phát hiện sự cố. Điều đó hữu ích, nhưng nó không giống như kiểm thử dựa trên thuộc tính được điều khiển bởi lược đồ. Schemathesis tạo đầu vào từ các ràng buộc của đặc tả và kiểm tra phản hồi dựa trên lược đồ. Vì vậy, nếu fuzzing dựa trên thuộc tính là điều bạn cần, hãy tìm đến Schemathesis, không phải Apidog.
Vai trò của Apidog nằm ở phần còn lại của vòng đời xoay quanh quá trình fuzzing đó.
| Giai đoạn quy trình làm việc | Schemathesis | Apidog |
|---|---|---|
| Fuzzing dựa trên thuộc tính từ một đặc tả | Có, tính năng cốt lõi | Không |
| Thiết kế API trực quan và chỉnh sửa đặc tả | Không | Có |
| Kiểm thử chức năng dựa trên ví dụ | Hạn chế | Có, trình xây dựng kiểm thử trực quan |
| Kiểm thử hợp đồng dựa trên đặc tả | Một phần, thông qua kiểm tra lược đồ | Có, quy trình làm việc chuyên dụng |
| Máy chủ mock từ một lược đồ | Không | Có, smart mock |
| Trình chạy kiểm thử CI | Có, st run |
Có, apidog run |
| Tài liệu tự động tạo | Không | Có |
Một cách kết hợp thực tế trông như sau. Bạn thiết kế và duy trì đặc tả trong Apidog, tạo các trường hợp kiểm thử chức năng và máy chủ mock từ đó, sau đó chạy chúng trong CI với apidog run. Sau đó, bạn thêm một lượt Schemathesis để fuzz cùng đặc tả đó nhằm tìm kiếm các sự cố ở trường hợp biên và vi phạm hợp đồng. Hai lớp này bắt được các loại lỗi khác nhau. Apidog xác nhận API thực hiện đúng cho các trường hợp đã biết; Schemathesis tìm kiếm các trường hợp không xác định có thể làm hỏng API.
Nếu mục tiêu của bạn là biến một đặc tả thành một bộ chức năng có thể chạy được thay vì một lần chạy fuzzing, Apidog có thể tạo các bộ sưu tập kiểm thử API từ đặc tả OpenAPI của bạn trực tiếp, và bạn có thể tải xuống Apidog để thử quy trình đó.
Các câu hỏi thường gặp
Schemathesis có miễn phí không?
Có. Schemathesis là mã nguồn mở theo giấy phép MIT, và CLI miễn phí để cài đặt và chạy qua pip install schemathesis. Ngoài ra còn có một dịch vụ thương mại được lưu trữ cho các nhóm muốn có trải nghiệm được quản lý, nhưng công cụ cốt lõi bạn chạy cục bộ và trong CI không tốn phí.
Sự khác biệt giữa schemathesis run và st run là gì?
Chúng là cùng một lệnh. st là một biệt danh ngắn cho schemathesis, vì vậy st run và schemathesis run thực hiện chính xác điều tương tự. Hãy sử dụng cái nào bạn thích. Cả hai đều nhận đường dẫn lược đồ hoặc URL cùng với các tùy chọn như --url và --header.
Schemathesis có thể thay thế các bài kiểm thử API chức năng của tôi không?
Không, và nó không được thiết kế để làm điều đó. Schemathesis kiểm tra xem API của bạn có gặp sự cố không và liệu các phản hồi có khớp với lược đồ hay không. Nó không xác minh logic nghiệp vụ, chẳng hạn như liệu tính toán chiết khấu có đúng không. Bạn vẫn cần kiểm thử chức năng dựa trên ví dụ và kiểm thử hợp đồng cho mục đích đó, mà bạn có thể xây dựng và chạy trong Apidog. Hãy coi Schemathesis là một lớp fuzzing bổ sung, chứ không phải là một sự thay thế.
Schemathesis có hoạt động với GraphQL không?
Có. Schemathesis hỗ trợ cả lược đồ OpenAPI và GraphQL. Đối với GraphQL, nó tạo các truy vấn từ các định nghĩa kiểu của lược đồ và kiểm tra các phản hồi theo cùng một cách mà nó làm đối với các API REST được định nghĩa trong OpenAPI.
Kết luận
Schemathesis là một công cụ sắc bén cho một công việc: lấy đặc tả OpenAPI hoặc GraphQL của bạn và kiểm tra căng thẳng (stress-test) API đang hoạt động của bạn dựa trên nó bằng cách tạo dữ liệu dựa trên thuộc tính. Nó tìm ra các sự cố và vi phạm hợp đồng mà các bài kiểm thử dựa trên ví dụ bỏ sót, và bạn gần như không tốn chi phí nào để thêm nó vào CI. Những gì nó không làm là thiết kế, mô phỏng (mock), tài liệu hóa hoặc xác minh logic nghiệp vụ.
Đó là nơi Apidog bổ trợ cho nó. Thiết kế đặc tả, tạo các kiểm thử chức năng và mock, chạy chúng trong CI với apidog run, và tài liệu hóa kết quả, tất cả ở một nơi, sau đó thêm Schemathesis lên trên để fuzzing. Tải xuống Apidog để xây dựng phần thiết kế và chức năng của quy trình làm việc đó, và để Schemathesis xử lý việc tìm kiếm các trường hợp biên.
Tải ứng dụng