DEV Community

Cover image for Schemathesis là gì? Kiểm thử API dựa trên thuộc tính từ đặc tả OpenAPI
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Schemathesis là gì? Kiểm thử API dựa trên thuộc tính từ đặc tả OpenAPI

Nếu bạn đã có lược đồ OpenAPI hoặc GraphQL, Schemathesis có thể tự tạo hàng ngàn ca kiểm thử từ đặc tả đó. Công cụ này đọc schema, sinh input hợp lệ hoặc gần-biên, gửi request đến API đang chạy, rồi báo lỗi khi response vi phạm contract. Bài viết này hướng dẫn cách cài đặt, chạy Schemathesis, hiểu kiểm thử dựa trên thuộc tính, và kết hợp nó với kiểm thử chức năng / kiểm thử hợp đồng trong Apidog.

Thử Apidog ngay hôm nay

Schemathesis là gì?

Schemathesis là công cụ Python mã nguồn mở dùng để tạo kiểm thử API tự động từ schema OpenAPI hoặc GraphQL. Bạn đưa vào một đặc tả, Schemathesis sẽ dựa trên type, format, enum, required field, min/max và các ràng buộc khác để sinh test case.

Nó được xây dựng 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.

Demo Schemathesis

Ý tưởng cốt lõi:

  1. Schema mô tả request và response hợp lệ.
  2. Schemathesis dùng schema đó làm “nguồn sự thật”.
  3. Công cụ gửi nhiều request được sinh tự động đến API.
  4. Nếu API trả về 500, response sai schema, sai content type, hoặc status code không được khai báo, test sẽ fail.

Bạn có thể chạy Schemathesis bằng CLI:

schemathesis run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Hoặc dùng alias ngắn hơn:

st run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Nếu muốn tích hợp sâu hơn vào test suite Python, bạn cũng có thể dùng Schemathesis cùng pytest, nhưng phần lớn team nên bắt đầu bằng CLI vì gần như không cần cấu hình.

Kiểm thử dựa trên thuộc tính là gì?

Kiểm thử API truyền thống thường dựa trên ví dụ:

GET /users/1
Enter fullscreen mode Exit fullscreen mode

Sau đó bạn assert response cụ thể:

{
  "id": 1,
  "name": "Alice"
}
Enter fullscreen mode Exit fullscreen mode

Cách này hữu ích, nhưng chỉ kiểm tra những case bạn đã nghĩ tới.

Kiểm thử dựa trên thuộc tính đảo ngược cách tiếp cận. Thay vì viết từng ví dụ cố định, bạn mô tả một thuộc tính luôn phải đúng, rồi để công cụ tự tạo nhiều input để cố phá vỡ thuộc tính đó.

Với Schemathesis, thuộc tính mặc định có thể hiểu là:

Không request hợp lệ nào được phép làm server crash hoặc tạo response vi phạm schema.

Ví dụ, nếu OpenAPI khai báo field như sau:

age:
  type: integer
  minimum: 1
Enter fullscreen mode Exit fullscreen mode

Schemathesis có thể thử các giá trị như:

1
2
999999
giá trị biên
các input có khả năng làm lộ lỗi validation
Enter fullscreen mode Exit fullscreen mode

Khi phát hiện lỗi, Hypothesis sẽ “thu nhỏ” input thất bại thành case nhỏ nhất vẫn tái hiện được bug. Vì vậy thay vì nhận một payload ngẫu nhiên rất dài, bạn thường nhận được request tối thiểu để debug.

Điểm này khác với kiểm thử khỉ. Monkey testing thường ném input ngẫu nhiên vào hệ thống. Schemathesis có cấu trúc hơn: nó sinh dữ liệu từ schema và kiểm tra kết quả dựa trên contract đã khai báo.

Cài đặt Schemathesis

Schemathesis là package Python, vì vậy bạn cần Python 3 và pip.

Cài đặt bằng pip:

pip install schemathesis
Enter fullscreen mode Exit fullscreen mode

Kiểm tra lệnh đã sẵn sàng:

st --version
Enter fullscreen mode Exit fullscreen mode

Nếu bạn dùng uv, có thể chạy mà không cần cài đặt cố định:

uvx schemathesis run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Chạy Schemathesis với OpenAPI URL

Nếu API expose schema qua URL, ví dụ:

http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Chạy:

st run http://127.0.0.1:8000/openapi.json
Enter fullscreen mode Exit fullscreen mode

Schemathesis sẽ:

  1. Tải OpenAPI schema.
  2. Duyệt qua các operation.
  3. Sinh request cho từng operation.
  4. Gửi request đến server.
  5. Kiểm tra status code, content type và response body.
  6. In báo cáo pass/fail.

Chạy với file OpenAPI local

Nếu schema nằm trên máy local:

st run ./openapi.yaml --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode

Trong đó:

  • ./openapi.yaml là file schema.
  • --url là base URL của API thật đang chạy.

Ví dụ với file JSON:

st run ./openapi.json --url https://api.example.com
Enter fullscreen mode Exit fullscreen mode

Thêm authentication header

Với API cần token:

st run http://127.0.0.1:8000/openapi.json \
  --header 'Authorization: Bearer your-token'
Enter fullscreen mode Exit fullscreen mode

Nếu API cần nhiều header:

st run ./openapi.yaml \
  --url https://api.example.com \
  --header 'Authorization: Bearer your-token' \
  --header 'X-Tenant-ID: demo'
Enter fullscreen mode Exit fullscreen mode

Tên flag và giá trị mặc định có thể thay đổi giữa các phiên bản chính. Luôn kiểm tra phiên bản bạn đang dùng:

st run --help
Enter fullscreen mode Exit fullscreen mode

Đọc kết quả thất bại

Khi test fail, Schemathesis thường in ra request đã gây lỗi. Bạn có thể dùng thông tin đó để tái hiện bằng curl hoặc API client.

Ví dụ workflow debug:

st run ./openapi.yaml --url http://127.0.0.1:8000
Enter fullscreen mode Exit fullscreen mode

Nếu Schemathesis báo một endpoint trả về 500, hãy:

  1. Copy request tối thiểu được báo cáo.
  2. Chạy lại bằng curl.
  3. Kiểm tra log server.
  4. Sửa validation hoặc logic xử lý.
  5. Chạy lại Schemathesis.

Ví dụ curl tái hiện:

curl -i \
  -H 'Content-Type: application/json' \
  -d '{"age":1}' \
  http://127.0.0.1:8000/users
Enter fullscreen mode Exit fullscreen mode

Những lỗi Schemathesis thường phát hiện

Vấn đề Biểu hiện
Lỗi server Request làm API trả về 500 thay vì response hợp lệ hoặc lỗi 4xx được xử lý
Vi phạm schema Response body không khớp schema đã khai báo cho status code đó
Status code không khớp API trả về status code không được mô tả trong OpenAPI
Sai content type Response Content-Type khác với đặc tả
Lỗi theo trạng thái Một operation chạy riêng thì đúng, nhưng fail trong workflow nhiều bước

Ví dụ, OpenAPI khai báo:

responses:
  "200":
    description: OK
  "404":
    description: Not found
Enter fullscreen mode Exit fullscreen mode

Nhưng API thực tế trả về:

HTTP/1.1 204 No Content
Enter fullscreen mode Exit fullscreen mode

Schemathesis có thể báo đây là status code không được khai báo.

Kiểm thử workflow có trạng thái

Một số lỗi chỉ xuất hiện khi các request chạy theo thứ tự:

  1. Tạo resource.
  2. Lấy resource.
  3. Cập nhật resource.
  4. Xóa resource.
  5. Lấy lại resource sau khi xóa.

Các test một request thường khó bắt lỗi kiểu này. Schemathesis có thể chạy kiểm thử có trạng thái bằng cách xâu chuỗi operation dựa trên thông tin trong đặc tả, ví dụ tạo một tài nguyên rồi dùng ID đó cho request tiếp theo.

Loại kiểm thử này hữu ích khi API có lifecycle rõ ràng:

POST /users
GET /users/{id}
PATCH /users/{id}
DELETE /users/{id}
Enter fullscreen mode Exit fullscreen mode

Nếu sau khi PATCH, API trả về trạng thái sai hoặc sau khi DELETE vẫn lấy được resource như bình thường, kiểm thử theo chuỗi có thể phát hiện vấn đề đó.

Tùy chỉnh bằng hook

Bạn có thể mở rộng Schemathesis bằng hook Python để:

  • Tùy chỉnh dữ liệu được sinh.
  • Thêm check riêng.
  • Bỏ qua một số operation.
  • Xử lý authentication flow phức tạp.
  • Áp dụng rule nghiệp vụ mà schema không mô tả được.

Cách này phù hợp khi OpenAPI không thể biểu diễn hết constraint thực tế của API, ví dụ:

  • Field startDate phải nhỏ hơn endDate.
  • User phải thuộc cùng tenant.
  • Một endpoint chỉ chạy được sau khi tạo session.
  • Một số route không nên fuzz trong môi trường staging.

Khi nào nên dùng Schemathesis?

Schemathesis phù hợp khi bạn có schema OpenAPI hoặc GraphQL tương đối chính xác và muốn tăng độ bao phủ cho edge case với chi phí thấp.

Nên dùng khi:

  • Bạn duy trì đặc tả OpenAPI và muốn kiểm tra nó với server thật.
  • Bạn muốn phát hiện lỗi 500 chưa được xử lý.
  • Bạn muốn thêm một lớp fuzzing vào CI.
  • API có workflow có trạng thái.
  • Team đã quen với Python, pip, hoặc pytest.

Không nên kỳ vọng Schemathesis thay thế toàn bộ test suite. Nó không xác minh đầy đủ logic nghiệp vụ.

Ví dụ, Schemathesis có thể phát hiện:

API trả về response sai schema
Enter fullscreen mode Exit fullscreen mode

Nhưng nó không tự biết:

Công thức tính giảm giá có đúng theo rule kinh doanh hay không
Enter fullscreen mode Exit fullscreen mode

Với logic nghiệp vụ, bạn vẫn cần test dựa trên ví dụ cụ thể.

Đưa Schemathesis vào CI

Một cách triển khai đơn giản trong CI:

pip install schemathesis
st run ./openapi.yaml --url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

Ví dụ GitHub Actions tối giản:

name: API fuzzing

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  schemathesis:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: |
          pip install schemathesis

      - name: Start API
        run: |
          docker compose up -d
          sleep 10

      - name: Run Schemathesis
        run: |
          st run ./openapi.yaml --url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

Trong môi trường thực tế, bạn nên đảm bảo:

  • API test chạy với database riêng.
  • Dữ liệu có thể reset.
  • Token test không có quyền nguy hiểm.
  • Các endpoint phá dữ liệu production không được fuzz trực tiếp.
  • CI fail khi Schemathesis phát hiện lỗi contract hoặc lỗi server.

Schemathesis và Apidog: vai trò của mỗi công cụ

Apidog và Schemathesis giải quyết hai phần khác nhau của vòng đời API.

Apidog là nền tảng để thiết kế, gỡ lỗi, kiểm thử, mock và tài liệu hóa API. Schemathesis là công cụ fuzzing dựa trên thuộc tính từ schema.

Điểm cần phân biệt: Apidog không thực hiện fuzzing dựa trên thuộc tính giống Schemathesis. Tính năng gần nhất là kiểm thử khỉ, dùng input ngẫu nhiên để phát hiện sự cố. Schemathesis đi theo hướng khác: sinh input từ ràng buộc trong schema và kiểm tra response theo contract.

Giai đoạn workflow Schemathesis Apidog
Fuzzing dựa trên thuộc tính từ schema 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ó
Kiểm thử hợp đồng dựa trên đặc tả Một phần, qua kiểm tra schema Có
Mock server từ schema Không Có
Chạy test trong CI Có, qua st run Có, qua apidog run
Tài liệu API tự động Không Có

Một workflow thực tế:

  1. Thiết kế và duy trì OpenAPI schema trong Apidog.
  2. Tạo test chức năng dựa trên ví dụ.
  3. Tạo mock server khi cần phát triển song song.
  4. Chạy test trong CI bằng apidog run.
  5. Chạy thêm Schemathesis để fuzz cùng schema.
  6. Sửa các lỗi contract, lỗi 500, hoặc response sai schema.

Hai lớp test này bổ sung cho nhau:

  • Apidog xác minh API đúng với case đã biết.
  • Schemathesis tìm edge case chưa được viết thủ công.

Nếu mục tiêu của bạn là biến OpenAPI thành bộ test chức năng có thể chạy được, Apidog có thể tạo bộ sưu tập kiểm thử API từ đặc tả OpenAPI. Bạn cũng có thể tải xuống Apidog để thử workflow đó.

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. CLI có thể cài đặt và chạy miễn phí:

pip install schemathesis
Enter fullscreen mode Exit fullscreen mode

Ngoài ra còn có dịch vụ thương mại được lưu trữ cho các team muốn trải nghiệm được quản lý, nhưng công cụ cốt lõi chạy local và trong CI là miễn phí.

schemathesis run và st run khác nhau thế nào?

Không khác nhau về chức năng. st là alias ngắn của schemathesis.

Hai lệnh sau tương đương:

schemathesis run ./openapi.yaml --url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode 
st run ./openapi.yaml --url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

Schemathesis có thay thế test chức năng không?

Không. Schemathesis kiểm tra API có crash không, response có đúng schema không, status code và content type có khớp contract không.

Nó không xác minh toàn bộ logic nghiệp vụ như:

  • Tính chiết khấu đúng hay sai.
  • Quyền truy cập có đúng rule nội bộ không.
  • Dữ liệu tổng hợp có đúng công thức không.

Bạn vẫn cần test chức năng dựa trên ví dụ và kiểm thử hợp đồng, có thể xây dựng và chạy trong Apidog.

Schemathesis có hỗ trợ GraphQL không?

Có. Schemathesis hỗ trợ cả OpenAPI và GraphQL. Với GraphQL, nó sinh query từ định nghĩa type trong schema và kiểm tra response theo cách tương tự như với API REST được mô tả bằng OpenAPI.

Kết luận

Schemathesis là công cụ phù hợp khi bạn muốn lấy OpenAPI hoặc GraphQL schema và stress-test API thật bằng dữ liệu sinh tự động. Nó giúp phát hiện lỗi 500, response sai schema, status code không được khai báo và các edge case mà test thủ công thường bỏ sót.

Nó không thay thế thiết kế API, mock server, tài liệu API hay test logic nghiệp vụ. Phần đó phù hợp với Apidog hơn: thiết kế schema, tạo test chức năng, mock API, chạy CI bằng apidog run, rồi thêm Schemathesis như một lớp fuzzing bổ sung.

Tải xuống Apidog để xây dựng phần thiết kế và kiểm thử chức năng của workflow, sau đó dùng Schemathesis để tìm các edge case từ cùng một đặc tả.

Top comments (0)