Dredd giải quyết một vấn đề thực sự, và nó giải quyết một cách gọn gàng. Bạn hướng nó đến một mô tả API, một tài liệu OpenAPI hoặc một tệp API Blueprint, và đến một máy chủ đang chạy. Nó đọc mọi ví dụ trong mô tả, gửi yêu cầu phù hợp đến phần backend đang hoạt động, và kiểm tra xem phản hồi thực tế có khớp với những gì đặc tả đã cam kết hay không. Nếu đặc tả của bạn nói rằng GET /orders/{id} trả về 200 với trường id và status, Dredd xác nhận rằng dịch vụ đang chạy thực sự làm được điều đó. Đặc tả không còn là tài liệu dần bị lỗi thời một cách lặng lẽ nữa mà trở thành một bài kiểm tra báo lỗi rõ ràng.
Ý tưởng đó, xác thực việc triển khai dựa trên mô tả API, là một ý tưởng đúng đắn. Sự sai lệch giữa những gì một đặc tả nói và những gì một dịch vụ thực hiện là một trong những lỗi ẩn tốn kém nhất trong công việc API. Một nhóm frontend lập trình theo hợp đồng được ghi lại, phần backend thay đổi tên một trường, không ai cập nhật tài liệu, và lỗi xuất hiện trong môi trường sản xuất. Dredd bắt chính xác loại lỗi này, và trong nhiều năm, nó đã là công cụ mã nguồn mở được ưa chuộng để thực hiện việc này từ dòng lệnh.
Sự khó khăn nằm ở việc thiết lập và bảo trì, không phải ở khái niệm. Dredd là một CLI của Node.js yêu cầu tệp cấu hình riêng, một tệp hooks bằng ngôn ngữ bạn chọn cho bất kỳ trường hợp nào ngoài những trường hợp đơn giản, và một artifact đặc tả riêng biệt mà bạn phải tự duy trì cùng với mọi thứ khác. Nếu bạn muốn kết quả tương tự mà Dredd mang lại, một cổng CI sẽ thất bại khi triển khai của bạn không còn khớp với hợp đồng OpenAPI của nó, mà không cần phải dựng một chuỗi công cụ hooks và không cần giữ đặc tả như một tệp thứ ba bị ngắt kết nối, thì Apidog được xây dựng cho quy trình làm việc đó. Nó giữ đặc tả, các bài kiểm tra và việc xác thực trong một dự án, và chạy toàn bộ mọi thứ một cách không giao diện từ một CLI của npm. Hướng dẫn này nói rõ về những gì Dredd làm tốt và những điểm mà phương pháp tích hợp chiếm ưu thế.
nút
Những điều Dredd làm tốt
Đầu tiên, hãy ghi nhận Dredd xứng đáng, bởi vì nó đã tạo dựng được danh tiếng.
Nó kiểm tra việc triển khai thực tế, không phải một bản mô phỏng. Đây là cốt lõi của vấn đề. Rất nhiều công cụ xác thực rằng tệp OpenAPI của bạn được định dạng tốt hoặc rằng một máy chủ giả lập hoạt động đúng. Dredd làm một việc khó hơn: nó truy cập vào phần backend đang chạy thực tế và kiểm tra các byte thực tế trả về so với các ví dụ đã được ghi lại. Một lần chạy Dredd thành công có nghĩa là dịch vụ đã triển khai và đặc tả của bạn đồng nhất ngay lập tức, không phải chỉ trên lý thuyết.
Nó hỗ trợ cả API Blueprint và OpenAPI. Dredd phát triển cùng với API Blueprint, định dạng mô tả dựa trên markdown, và sau đó bổ sung hỗ trợ OpenAPI 2 và 3. Nếu bạn có một tệp Blueprint cũ hoặc tài liệu Swagger, Dredd có thể đọc nó mà không cần bước chuyển đổi.
Hooks không phụ thuộc ngôn ngữ. Khi vòng lặp yêu cầu và so sánh mặc định không đủ, bạn cần mã thông báo xác thực, bạn cần gieo dữ liệu vào cơ sở dữ liệu trước khi kiểm tra, bạn cần bỏ qua một giao dịch, Dredd cho phép bạn viết các hooks. Trình xử lý hook chạy trong Node theo mặc định, nhưng Dredd hỗ trợ giao thức cho hooks trong Python, Ruby, Go, PHP, Rust, và nhiều ngôn ngữ khác. Nhóm của bạn viết logic thiết lập bằng ngôn ngữ mà họ đã biết.
Nó là mã nguồn mở và thân thiện với CI. Dredd được cài đặt bằng npm install -g dredd, chạy như một lệnh duy nhất và thoát với mã lỗi khác 0 khi xác thực thất bại, do đó bất kỳ hệ thống CI nào cũng có thể chặn một bản dựng dựa vào nó. Không có tài khoản SaaS, không có giá theo người dùng, không cần ký kết gì cả. Đối với một nhóm muốn kiểm tra hợp đồng có thể tự lưu trữ, có thể viết script, điều này rất quan trọng.
Không có gì trong số đó là thừa thãi. Dredd là một công cụ vững chắc với một nhiệm vụ rõ ràng. Câu hỏi là liệu mô hình của nó, ba artifact riêng biệt và một tệp hooks, có phù hợp với cách bạn thực sự muốn làm việc hay không.
Những điểm khó khăn
Ba chi phí đi kèm với mô hình Dredd, và mức độ ảnh hưởng của chúng phụ thuộc vào thiết lập của bạn.
Đặc tả là một artifact thứ ba mà bạn duy trì thủ công. Dredd xác thực việc triển khai dựa trên một tệp mô tả, điều này hoàn toàn đúng, nhưng mô tả đó thường nằm tách biệt với nơi bạn thiết kế và kiểm thử API. Bạn tự chỉnh sửa một tệp openapi.yaml, bạn giữ các kịch bản kiểm thử của mình ở một nơi khác, và bạn lại giữ dịch vụ đang chạy ở một nơi khác nữa. Dredd kiểm tra hai trong ba yếu tố đó đối chiếu với nhau. Việc giữ đặc tả chính xác vẫn là một công việc thủ công, và một đặc tả đã dần lệch khỏi thực tế sẽ tạo ra một lần chạy Dredd "xanh" nhưng sai.
Hooks là mã bạn tự viết và duy trì. Ngay khi API của bạn cần xác thực, sắp xếp hoặc dữ liệu kiểm thử, vòng lặp dựa trên ví dụ không còn đủ nữa. Bạn viết một tệp hooks.js (hoặc một tệp tương đương bằng Python hoặc Ruby), liên kết nó thông qua dredd.yml, và giờ đây bạn sở hữu một codebase thứ hai mà công việc duy nhất của nó là làm cho codebase đầu tiên có thể kiểm thử được. Đối với một API chỉ đọc đơn giản, Dredd gần như không cần cấu hình. Đối với một API thực sự với đăng nhập và các endpoint có trạng thái, tệp hooks sẽ lớn dần, và nó là một loại mã kết nối khác.
Phạm vi kiểm thử dựa trên ví dụ có lỗ hổng. Dredd kiểm tra các ví dụ có trong mô tả của bạn. Nếu một endpoint có một phản hồi ví dụ được ghi lại, đó là những gì được kiểm tra. Các trường hợp biên, đường dẫn lỗi và các quy tắc xác thực không được nêu rõ thành ví dụ trong đặc tả sẽ không được thực thi trừ khi bạn thêm chúng, bằng cách mở rộng đặc tả hoặc viết thêm hooks. Phạm vi kiểm thử chỉ tốt bằng các ví dụ bạn duy trì, không hơn.
Phương pháp tích hợp: đặc tả và kiểm thử trong một dự án
Đây là sự khác biệt mà Apidog tạo ra. Định nghĩa API không phải là một tệp thứ ba mà bạn phải đồng bộ thủ công; nó là nguồn chân lý tồn tại trong cùng một dự án với các bài kiểm thử thực thi nó và quá trình xác thực kiểm soát bản dựng của bạn. Thay đổi schema, và các bài kiểm thử sẽ thấy hình dạng mới. Không có tệp openapi.yaml riêng biệt nào trôi nổi trong một góc của kho lưu trữ, và không có tệp hooks nào đứng giữa đặc tả và một bài kiểm thử hoạt động.
Bạn thiết kế hoặc nhập API một lần. Apidog đọc OpenAPI 2 và 3, nhập tài liệu Swagger, và kéo vào Postman collections chỉ bằng một cú nhấp chuột. Các endpoint, schema yêu cầu, schema phản hồi và các phản hồi ví dụ đều nằm trong một dự án. Nếu bạn đã quen với việc phát triển ưu tiên đặc tả, đây là cùng một nguyên tắc mà Dredd khuyến khích, chỉ khác là đặc tả không phải là một tệp rời rạc. Phiên bản sâu hơn của quy trình làm việc đó nằm trong phát triển API ưu tiên đặc tả, và nếu bạn muốn xác thực tài liệu đặc tả trước khi bất kỳ bài kiểm thử nào chạy, xác thực các đặc tả OpenAPI bao gồm bước đó.
Bạn xây dựng việc xác thực dựa trên các schema thực tế đó. Khi một kịch bản kiểm thử gọi GET /orders/{id}, bạn khẳng định phản hồi dựa trên schema mà Apidog đã lưu giữ cho endpoint đó, chứ không phải dựa trên một ví dụ sao chép thủ công. Đó là kiểm tra đặc tả so với triển khai mà Dredd thực hiện, với một điểm khác biệt: đặc tả được kiểm tra là cùng một đối tượng mà bạn đã thiết kế API từ đó, vì vậy nó không thể âm thầm lệch khỏi bộ kiểm thử của bạn. Đây là kiểm thử hợp đồng mà không cần một artifact thứ ba, và nếu bạn muốn có cái nhìn rộng hơn về nguyên tắc này, kiểm thử hợp đồng API và kiểm thử hợp đồng hai chiều đều đi sâu hơn.
Việc thiết lập mà Dredd xử lý bằng một tệp hooks, mã thông báo xác thực, sắp xếp, gieo dữ liệu, bạn xử lý bằng các script trước và sau yêu cầu trong JavaScript, điều mà hầu hết các nhà phát triển web đã viết. Không có codebase hooks riêng biệt nào được kết nối thông qua một tệp cấu hình. Logic nằm ngay cạnh bài kiểm thử mà nó hỗ trợ.
Cài đặt và chạy Apidog CLI
Runner được phát hành trên npm dưới tên apidog-cli. Nếu bạn có Node.js, bạn đã có mọi thứ mình cần:
npm install -g apidog-cli
Tệp thực thi là apidog, vì vậy mỗi lần chạy bắt đầu bằng apidog run. Để chạy một kịch bản kiểm thử, bạn truyền một mã thông báo truy cập, ID kịch bản và ID môi trường:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Bạn không cần nhập các ID đó bằng tay. Mở kịch bản kiểm thử trong Apidog, chuyển đến tab CI/CD của nó, chọn tùy chọn dòng lệnh và tạo một mã thông báo truy cập. Apidog sẽ xây dựng lệnh apidog run hoàn chỉnh cho bạn với các ID kịch bản và môi trường đã được điền sẵn. Sao chép nó một lần và tham số hóa mã thông báo từ đó. Hãy xử lý mã thông báo truy cập như một mật khẩu: lưu trữ nó như một bí mật trong hệ thống CI của bạn và tham chiếu nó dưới dạng $APIDOG_ACCESS_TOKEN, giống như mọi ví dụ ở đây.
Để chạy nhiều hơn một kịch bản, hãy hướng runner đến một thư mục hoặc một bộ kiểm thử thay vì một ID duy nhất, và chọn các bộ báo cáo của bạn:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -e 1629989 -r html,junit --out-dir ./test-reports
Cờ -r đó chọn các bộ báo cáo. Apidog hỗ trợ cli cho đầu ra terminal dễ đọc, html cho một báo cáo độc lập mà bạn lưu trữ như một artifact của bản dựng, junit cho XML mà hầu hết các bảng điều khiển CI phân tích thành một cây pass/fail, và json cho các kết quả cấu trúc thô. Nếu bạn muốn tìm hiểu sâu hơn về runner, hãy chạy apidog run --help để xem danh sách cờ đầy đủ.
So sánh
| Dredd | Apidog | |
|---|---|---|
| Ý tưởng cốt lõi | Xác thực việc triển khai dựa trên mô tả API | Xác thực việc triển khai dựa trên đặc tả mà nó được thiết kế từ đó |
| Môi trường chạy | Node.js (npm install -g dredd) |
Node.js (npm install -g apidog-cli) |
| Định dạng đặc tả | API Blueprint, OpenAPI 2/3 | OpenAPI 2/3, nhập Swagger, nhập Postman |
| Vị trí đặc tả | Tệp riêng biệt, duy trì thủ công | Cùng dự án mà các bài kiểm thử chạy đối với |
| Logic thiết lập | Tệp Hooks (hooks.js, cộng với Python/Ruby/Go/v.v.) |
JavaScript trước/sau yêu cầu, trong kiểm thử |
| Viết kiểm thử | Các ví dụ trong mô tả | Trình chỉnh sửa trực quan dựa trên các schema thực tế |
| Phạm vi bao phủ | Tốt bằng các ví dụ trong đặc tả | Khẳng định schema cộng với các kịch bản tùy chỉnh |
| Bộ báo cáo | Tích hợp sẵn cộng với các tiện ích bổ sung | cli, html, json, junit |
| Lưu trữ | Tự lưu trữ, mã nguồn mở | Dự án được lưu trữ, CLI chạy ở bất kỳ đâu |
Hãy đọc bảng đó một cách chân thật. Nếu bạn muốn một công cụ hoàn toàn tự lưu trữ, mã nguồn mở, không cần tài khoản và nhóm của bạn cảm thấy thoải mái với việc duy trì tệp hooks, thì mô hình của Dredd là một lựa chọn phù hợp và việc chuyển đổi chỉ vì mục đích chuyển đổi sẽ không mang lại lợi ích gì. Trường hợp cho phương pháp tích hợp là cụ thể: bạn đã chán việc đặc tả là một tệp thứ ba bị lệch, bạn không muốn sở hữu một codebase hooks, hoặc bạn muốn cùng một dự án xử lý thiết kế, kiểm thử và kiểm tra hợp đồng cùng nhau.
Kết nối vào CI
Apidog CLI thoát với mã 0 khi thành công và khác 0 khi thất bại, vì vậy bất kỳ hệ thống CI nào cũng có thể chặn một bản dựng dựa vào nó, giống hệt như Dredd. Một tác vụ GitHub Actions tối thiểu cần Node và một bước chạy:
name: api-contract-check
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install -g apidog-cli
- run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Đó là toàn bộ pipeline. Một tác vụ Dredd cũng tương tự, cài đặt CLI, chạy một lệnh, nhưng bạn cũng phải trỏ nó đến tệp đặc tả và tệp hooks của mình, và bạn phải giữ cả hai luôn cập nhật. Việc xác thực chạy theo cùng một cách; sự khác biệt là số lượng artifact bạn phải duy trì để đạt được điều đó.
Nếu lý do bạn tìm đến Dredd thực sự là để giữ cho đặc tả và dịch vụ trung thực với nhau, thì logic tương tự cũng xuất hiện ở các công cụ khác. Các nhóm gặp phải vấn đề Swagger và Postman lệch pha, mà kiểm thử dựa trên OpenAPI chống lại sự lệch pha của Swagger và Postman đã đề cập, và các cửa hàng Java gặp phải vấn đề này với Rest Assured, nơi câu chuyện thay thế tương tự: một công cụ mạnh mẽ mà mô hình của nó thêm một lớp bạn có thể không muốn. Bạn cũng có thể điều khiển Apidog từ trình chỉnh sửa của mình bằng tiện ích mở rộng VS Code nếu bạn không muốn rời khỏi IDE của mình.
Câu hỏi thường gặp
Apidog có phải là một sự thay thế trực tiếp cho thiết lập Dredd không? Không, và nó cũng không giả vờ là như vậy. Không có bộ chuyển đổi nào đọc tệp dredd.yml và hooks.js của bạn rồi xuất ra các kịch bản Apidog. Bạn nhập đặc tả OpenAPI của mình và xây dựng lại quá trình xác thực trong trình chỉnh sửa trực quan. Lợi ích là bạn ngừng duy trì tệp hooks và một đặc tả rời rạc; chi phí là một lần xây dựng lại. Nếu bạn có một bộ Dredd lớn và trưởng thành đang hoạt động, việc xây dựng lại đó là một quyết định thực sự, không phải là một món quà miễn phí.
Apidog có xác thực việc triển khai trực tiếp, giống như Dredd không? Có. CLI gửi các yêu cầu thực tế đến dịch vụ đang chạy của bạn và khẳng định các phản hồi thực tế so với các schema trong dự án của bạn. Đó là cùng một kiểm tra đặc tả so với triển khai mà Dredd thực hiện. Sự khác biệt là schema được kiểm tra là schema mà bạn đã thiết kế API từ đó, vì vậy nó không lệch khỏi các bài kiểm thử của bạn.
Tôi vẫn có thể xử lý xác thực và thiết lập kiểm thử theo cách mà Dredd hooks cho phép không? Có. Apidog hỗ trợ các script trước và sau yêu cầu bằng JavaScript, vì vậy bạn có thể lấy mã thông báo xác thực, gieo dữ liệu, chuyển đổi payload, hoặc xây dựng các khẳng định động trong mã. Logic nằm trong kịch bản mà nó hỗ trợ, chứ không phải trong một tệp hooks riêng biệt được kết nối thông qua cấu hình.
Dredd có làm được điều gì mà Apidog không làm được không? Có một vài điều. Dredd hoàn toàn tự lưu trữ và mã nguồn mở không cần tài khoản, và nó đọc API Blueprint, định dạng mô tả markdown cũ hơn, một cách tự nhiên. Nếu một công cụ không tài khoản, hoàn toàn cục bộ hoặc một tệp Blueprint cũ là trọng tâm trong thiết lập của bạn, hãy cân nhắc kỹ lưỡng trước khi chuyển đổi.
Apidog đọc định dạng nào? OpenAPI 2 và 3, tài liệu Swagger và Postman collections, tất cả đều có thể nhập vào một dự án. Nếu bạn muốn hiểu sự khác biệt về định dạng trước, Swagger so với OpenAPI và Tổng quan về đặc tả OpenAPI đều trình bày rõ ràng.
Điểm mấu chốt
Dredd đã nắm bắt đúng ý tưởng cốt lõi: mô tả API của bạn nên là thứ bạn dùng để kiểm tra dịch vụ đang chạy, chứ không phải là một tài liệu bị lệch pha. Nếu bạn muốn một CLI tự lưu trữ, mã nguồn mở và bạn hài lòng với việc duy trì tệp đặc tả và tệp hooks, thì Dredd là một lựa chọn hợp lý và bạn nên tiếp tục sử dụng nó.
Phương pháp tích hợp dành cho trường hợp bạn muốn loại bỏ việc bảo trì đó. Apidog giữ đặc tả, các bài kiểm thử và việc xác thực trong một dự án, vì vậy hợp đồng bạn kiểm tra là cùng một hợp đồng mà bạn đã thiết kế từ đó, và nó chạy toàn bộ mọi thứ từ apidog run mà không cần phải sở hữu một codebase hooks nào. Tải Apidog và nhập tệp OpenAPI hiện có của bạn để xem kiểm tra đặc tả so với triển khai chạy từ một lệnh duy nhất.
nút