Nếu bạn giữ một tệp OpenAPI nhưng dịch vụ đang chạy của bạn dần dần khác biệt so với nó, Specmatic được xây dựng chính xác để giải quyết khoảng cách đó. Nó coi đặc tả của bạn như một hợp đồng có thể thực thi, sau đó kiểm tra một dịch vụ thực tế dựa trên nó và chạy cùng một đặc tả như một stub thông minh. Hướng dẫn này giải thích Specmatic làm gì, cách kiểm thử hợp đồng khác với kiểm thử dựa trên ví dụ, và vị trí của công cụ này, kèm theo một lưu ý về cách nó so sánh với một cách tiếp cận nền tảng rộng hơn như kiểm thử hợp đồng API của Apidog. Đối với định dạng đặc tả bên dưới tất cả, OpenAPI Specification là nguồn sự thật mà Specmatic đọc từ đó.
Specmatic là gì
Specmatic là một công cụ mã nguồn mở cho phát triển dựa trên hợp đồng. Ý tưởng cốt lõi rất đơn giản: đặc tả API của bạn là hợp đồng, và Specmatic biến hợp đồng đó thành có thể thực thi. Chỉ cần chỉ định một tệp OpenAPI và nó có thể thực hiện hai công việc bổ trợ cho nhau.
- Chạy đặc tả như các bài kiểm thử đối với một dịch vụ đang hoạt động, kiểm tra xem dịch vụ có tuân thủ mọi đường dẫn, mã trạng thái và schema mà đặc tả đã hứa hay không.
- Chạy đặc tả như một máy chủ stub, để người tiêu dùng có thể phát triển dựa trên một mock phản hồi chính xác như hợp đồng đã nêu.
Cả hai công việc đều đọc cùng một tệp. Không có "định nghĩa kiểm thử" và "đặc tả" riêng biệt để giữ đồng bộ, đây chính là điểm mấu chốt. Specmatic cũng vượt ra ngoài OpenAPI. Phiên bản 2.0 đã thêm GraphQL và gRPC, và nó hỗ trợ AsyncAPI cho các hợp đồng sự kiện kiểu Kafka, cộng với các định dạng như WSDL và Avro. Tuy nhiên, đối với hầu hết các nhóm, điểm khởi đầu là một tệp YAML hoặc JSON OpenAPI đơn giản.
Bạn chạy nó từ dòng lệnh hoặc một hình ảnh Docker, vì vậy nó dễ dàng tích hợp vào CI mà không cần nhiều thiết lập. Công ty đứng sau nó cung cấp các tiện ích bổ sung thương mại, nhưng công cụ hợp đồng cốt lõi thì miễn phí và mã nguồn mở.
Kiểm thử hợp đồng so với kiểm thử dựa trên ví dụ
Đây là sự khác biệt gây nhầm lẫn cho hầu hết mọi người, vì vậy cần phải làm rõ.
Kiểm thử dựa trên ví dụ là điều bạn làm trong hầu hết các client API. Bạn viết một yêu cầu, bạn khẳng định phản hồi bạn nhận được, có thể bạn kiểm tra mã trạng thái và một hoặc hai trường. Mỗi bài kiểm thử là một ví dụ được viết thủ công. Nếu đặc tả của bạn có 40 endpoint, bạn sẽ viết và duy trì rất nhiều ví dụ, và các thiếu sót rất dễ bị bỏ qua.
Kiểm thử hợp đồng đảo ngược mô hình. Thay vì khẳng định trên các ví dụ cụ thể, bạn khẳng định rằng dịch vụ khớp với hợp đồng. Specmatic đọc schema và tạo các bài kiểm thử từ đó. Nó kiểm tra xem các phản hồi có tuân thủ các kiểu đã khai báo, các trường bắt buộc có tồn tại hay không, các mã trạng thái có khớp nhau hay không, và dịch vụ có từ chối các yêu cầu không đúng định dạng theo cách mà đặc tả ngụ ý hay không. Bạn không viết từng khẳng định một. Đặc tả chính là khẳng định.
| Khía cạnh | Kiểm thử dựa trên ví dụ | Kiểm thử hợp đồng với Specmatic |
|---|---|---|
| Nguồn sự thật | Các trường hợp kiểm thử viết tay | Chính đặc tả OpenAPI |
| Những gì bạn duy trì | Mỗi yêu cầu và khẳng định | Đặc tả, thứ bạn luôn giữ |
| Độ bao phủ | Chỉ những gì bạn nhớ để viết | Mọi hoạt động mà đặc tả khai báo |
| Phát hiện độ lệch | Thủ công | Tự động khi đặc tả thay đổi |
| Lỗi điển hình | Một ví dụ cụ thể bị lỗi | Dịch vụ không còn khớp với hợp đồng |
Có một khía cạnh thứ hai đáng để gọi tên. Kiểm thử hợp đồng có nhiều loại, và Specmatic nằm trong một loại cụ thể. Kiểm thử hợp đồng hướng người tiêu dùng kiểu Pact yêu cầu người tiêu dùng công bố các kỳ vọng của họ lên một broker, và nhà cung cấp xác minh dựa trên những kỳ vọng đó. Thay vào đó, Specmatic thực hiện kiểm thử hướng hợp đồng: đặc tả là hợp đồng duy nhất mà cả hai bên đồng ý, và Specmatic xác thực nhà cung cấp dựa trên nó và tạo stub nhà cung cấp cho người tiêu dùng. Nó không phải là một Pact broker, và nó không quản lý các pact do người tiêu dùng công bố. Nếu bạn muốn bức tranh rộng hơn, hãy xem tổng quan này về các công cụ kiểm thử hợp đồng và mock API.
Specmatic hoạt động như thế nào
Bạn có thể cài đặt CLI trực tiếp hoặc tải hình ảnh Docker. Docker là lựa chọn phổ biến trong CI vì nó tránh việc thiết lập môi trường chạy cục bộ.
Chạy kiểm thử hợp đồng
Lệnh kiểm thử chỉ định Specmatic đến một đặc tả và một dịch vụ đang chạy. Một lần chạy cục bộ tối thiểu trông như thế này.
# Native CLI
specmatic test api.yaml --testBaseURL=http://localhost:8080
# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
Specmatic đọc api.yaml, tạo các yêu cầu cho các hoạt động mà nó mô tả, gửi chúng đến URL cơ sở và xác thực mọi phản hồi dựa trên schema. Một bài kiểm thử thất bại có nghĩa là dịch vụ và hợp đồng không khớp nhau. Bạn sửa một trong hai. Đó là quy trình.
Chạy đặc tả như một stub
Máy chủ stub là một nửa còn lại. Khởi động nó và Specmatic sẽ cung cấp các phản hồi khớp với hợp đồng, để một giao diện người dùng hoặc một dịch vụ hạ nguồn có thể xây dựng dựa trên nó trước khi backend thực sự tồn tại.
specmatic stub api.yaml --port=9000
Theo mặc định, nó tạo ra các phản hồi hợp lệ theo schema một cách linh hoạt. Bạn cũng có thể lưu các ví dụ cụ thể trong một thư mục _examples bên cạnh đặc tả, và stub sẽ trả về những ví dụ đó khi một yêu cầu khớp. Điều này cung cấp cho bạn dữ liệu thực tế, có thể kiểm soát mà không cần thiết lập một backend thực sự. Nếu bạn đang so sánh các tùy chọn stub và mock giữa các công cụ, bản tổng hợp về kiểm thử hợp đồng và máy chủ mock đặt Specmatic vào đúng ngữ cảnh.
Specmatic cũng có thể giúp bạn tạo đặc tả ngay từ đầu. Nó có thể hoạt động như một proxy trước một dịch vụ hiện có, ghi lại lưu lượng truy cập thực tế và tạo tài liệu OpenAPI cùng các tệp ví dụ từ những gì nó thấy. Điều này hữu ích khi bạn có một dịch vụ nhưng chưa có đặc tả chính thức.
Mô hình đặc tả-như-hợp-đồng và stub
Đây là lý do tại sao việc chạy một tệp vừa là kiểm thử vừa là stub lại quan trọng. Khi đặc tả là hợp đồng, phía kiểm thử và phía stub không bao giờ có thể không khớp, bởi vì chúng đọc cùng một tài liệu.
- Nhóm nhà cung cấp chạy
specmatic testtrong CI. Nếu họ thay đổi API mà không cập nhật đặc tả, các bài kiểm thử hợp đồng sẽ thất bại. - Nhóm người tiêu dùng chạy
specmatic stubcục bộ. Họ phát triển dựa trên các phản hồi được đảm bảo khớp với cùng một hợp đồng.
Vì vậy, đặc tả trở thành một thỏa thuận sống động, chứ không phải là một tài liệu lỗi thời mà không ai tin tưởng. Đây là sự khác biệt giữa một stub và một mock phong phú hơn, và điều đáng để hiểu các ý tưởng cơ bản trong stubbing API so với mocking trước khi bạn thiết kế một quy trình làm việc xung quanh nó.
Specmatic cũng bổ sung kiểm tra khả năng tương thích ngược. Lệnh backward-compatibility-check khởi động một stub từ phiên bản mới của đặc tả, tạo các bài kiểm thử từ phiên bản trước đó và chạy chúng đối với stub mới. Nếu điều gì đó trước đây hoạt động mà bây giờ không còn nữa, bạn sẽ biết trước khi triển khai. Đó là một hàng rào bảo vệ mạnh mẽ cho các microservice triển khai độc lập, và đó là một dạng của ý tưởng rộng hơn được đề cập trong kiểm thử hợp đồng hai chiều.
Specmatic phù hợp ở đâu
Specmatic chứng tỏ giá trị của nó khi những điều sau đây đúng với nhóm của bạn:
- Đặc tả OpenAPI (hoặc AsyncAPI, GraphQL, gRPC) của bạn là có thật và tương đối hoàn chỉnh.
- Bạn có các nhóm nhà cung cấp và người tiêu dùng riêng biệt hoặc các dịch vụ cần giữ đồng bộ.
- Bạn muốn việc đặc tả bị lệch sẽ tự động làm thất bại một bản dựng, chứ không phải bị phát hiện trong quá trình xem xét.
- Bạn cảm thấy thoải mái với quy trình làm việc ưu tiên CLI và CI.
Nó ít phù hợp hơn nếu bạn không giữ một đặc tả, nếu bạn muốn một không gian làm việc trực quan để thiết kế và khám phá API, hoặc nếu bạn muốn một công cụ duy nhất để xử lý gỡ lỗi tạm thời, tài liệu và cộng tác nhóm. Specmatic tập trung vào công cụ hợp đồng, và nó thực hiện công việc đó rất tốt.
Sự tập trung đó cũng là nơi một nền tảng như Apidog có hình dạng khác. Apidog cũng hướng schema theo cách tương tự: nó đọc đặc tả OpenAPI của bạn, xác thực phản hồi dựa trên schema và khởi động một máy chủ mock từ schema OpenAPI của bạn mà không cần code. Sự khác biệt trung thực là phạm vi. Specmatic là một công cụ hợp đồng sắc bén, native CLI. Apidog gói gọn thiết kế, kiểm thử, mocking và tài liệu vào một không gian làm việc duy nhất với trình chỉnh sửa trực quan, vì vậy đặc tả, các bài kiểm thử và mock cùng tồn tại và giữ đồng bộ khi bạn làm việc. Apidog cũng không phải là một Pact broker hướng người tiêu dùng kiểu Pact, vì vậy nếu nhóm của bạn đặc biệt cần một pact broker, thì cả hai công cụ này đều không phải là nó.
Nếu bạn muốn tạo các bài kiểm thử có thể chạy trực tiếp từ một đặc tả bên trong loại không gian làm việc đó, hãy xem cách Apidog xử lý tạo bộ sưu tập kiểm thử API từ các đặc tả OpenAPI.
Các câu hỏi thường gặp
Specmatic có miễn phí không?
Có. Công cụ hợp đồng cốt lõi là mã nguồn mở và miễn phí sử dụng từ CLI hoặc Docker. Có các dịch vụ thương mại xung quanh nó, nhưng bạn có thể chạy các bài kiểm thử hợp đồng và máy chủ stub từ các đặc tả OpenAPI mà không phải trả phí. Kiểm tra trang web chính thức và GitHub để biết chi tiết hiện tại về các gói trả phí.
Specmatic có chỉ hoạt động với OpenAPI không?
Không. OpenAPI là điểm khởi đầu phổ biến nhất, nhưng Specmatic cũng hỗ trợ AsyncAPI cho các hợp đồng hướng sự kiện, cộng với GraphQL và gRPC kể từ phiên bản 2.0, cùng với các định dạng như WSDL và Avro. Mô hình giống nhau trên tất cả chúng: đặc tả là hợp đồng có thể thực thi. Nếu bạn mới làm quen với định dạng này, hãy bắt đầu với hướng dẫn OpenAPI Specification này.
Specmatic có giống như Pact không?
Không hẳn. Pact là hướng người tiêu dùng: người tiêu dùng công bố các kỳ vọng lên một broker và nhà cung cấp xác minh dựa trên chúng. Specmatic là hướng hợp đồng: đặc tả là hợp đồng chia sẻ duy nhất, và Specmatic xác thực nhà cung cấp dựa trên nó trong khi tạo stub nhà cung cấp cho người tiêu dùng. Cả hai đều giảm thiểu các bất ngờ khi tích hợp, nhưng chúng tổ chức hợp đồng theo những cách khác nhau.
Specmatic có thể tạo đặc tả OpenAPI cho tôi không?
Có. Specmatic có thể chạy như một proxy trước một dịch vụ hiện có, ghi lại lưu lượng yêu cầu và phản hồi thực tế, và tạo tài liệu OpenAPI cùng các tệp ví dụ từ đó. Điều này hữu ích khi bạn có một dịch vụ đang hoạt động nhưng chưa có đặc tả chính thức để kiểm thử.
Kết luận
Specmatic giải quyết một vấn đề cụ thể, có thật: giữ cho một dịch vụ đang chạy trung thực với đặc tả OpenAPI mà nó phải tuân theo. Bằng cách làm cho đặc tả có thể thực thi, nó cung cấp cho bạn các bài kiểm thử hợp đồng và một stub phù hợp từ một tệp duy nhất, cùng với các kiểm tra khả năng tương thích ngược. Nếu bạn làm việc chủ yếu với terminal và CI và bạn duy trì một đặc tả vững chắc, nó là một lựa chọn hoàn hảo.
Nếu bạn muốn có hợp đồng, các bài kiểm thử, mock và tài liệu trong một không gian làm việc trực quan đọc cùng một tệp OpenAPI, hãy thử Apidog. Nó xác thực phản hồi dựa trên schema của bạn, mock các endpoint mà không cần code và biến các đặc tả thành bộ sưu tập kiểm thử có thể chạy. Tải xuống Apidog để chỉ nó đến đặc tả của bạn và xem toàn bộ quy trình từ thiết kế đến kiểm thử ở một nơi.