Nếu bạn chạy các bài kiểm tra API từ inso, CLI Insomnia của Kong, và bạn đang nghĩ đến một sự thay đổi, hướng dẫn này sẽ chỉ cho bạn từng bước. Bạn sẽ thấy cách xuất các thông số kỹ thuật và bộ kiểm thử của mình ra khỏi Insomnia, đưa chúng vào Apidog và viết lại các lệnh inso run của bạn thành các lệnh apidog run. Có một bảng lệnh trước/sau để bạn có thể ánh xạ các tập lệnh CI hiện có của mình từng dòng một.
nút
Tại sao các nhóm chuyển từ inso sang Apidog CLI
inso là một công cụ vững chắc. Nó mang khả năng thực thi yêu cầu, linting Spectral và kiểm thử đơn vị vào terminal, và nó đọc từ thư mục .insomnia được tạo bởi Git Sync của Insomnia. Nếu quy trình làm việc đó phù hợp với bạn, không có quy tắc nào nói rằng bạn phải rời đi.
Sự khó khăn thường bắt đầu với ứng dụng Insomnia, chứ không phải CLI. Hai điều thúc đẩy hầu hết các tìm kiếm di chuyển:
- Yêu cầu tài khoản đám mây. Insomnia 8, phát hành vào năm 2023, đã giới thiệu một tài khoản đám mây/đăng nhập bắt buộc khiến nhiều nhóm bất ngờ. Rất nhiều nhà phát triển muốn một client ưu tiên cục bộ nhưng lại gặp phải bức tường đăng nhập.
- Mất dữ liệu và khó khăn khi di chuyển. Một số người dùng đã gặp phải sự cố mất dữ liệu và di chuyển trong quá trình chuyển đổi đó. Nếu bạn đã trải qua một lần, bạn đã biết chi phí của nó. Nếu bạn đang phục hồi từ một sự cố như vậy ngay bây giờ, các hướng dẫn này sẽ giúp ích: khôi phục và xuất dữ liệu Insomnia và hướng dẫn sâu hơn khôi phục và di chuyển dữ liệu Insomnia 8 bị mất.
Lý do khác là sự hợp nhất. Với inso, CLI là một phần của một ngăn xếp: Insomnia cho các yêu cầu, Spectral cho linting, các công cụ riêng biệt cho mock và docs. Apidog gộp thiết kế, gỡ lỗi, kiểm thử, mock và tài liệu vào một nền tảng duy nhất, và CLI chạy phần kiểm thử của nền tảng đó. Ít thành phần hơn, một nguồn thông tin duy nhất.
Nếu bạn muốn biết bối cảnh rộng hơn trước khi cam kết, Apidog vs Insomnia và lựa chọn giữa Insomnia và Apidog trình bày các đánh đổi cho các ứng dụng đầy đủ, không phải CLIs.
Trước khi bắt đầu: những gì di chuyển và những gì không
Thiết lập kỳ vọng ngay từ đầu để không có gì làm bạn ngạc nhiên giữa quá trình di chuyển.
| Tài sản trong Insomnia | Chuyển sang Apidog? | Cách thức |
|---|---|---|
| Tài liệu OpenAPI / thiết kế | Có | Xuất sang YAML/JSON, nhập vào Apidog |
| Bộ sưu tập yêu cầu | Có | Xuất, sau đó nhập |
| Môi trường và biến | Có | Được tạo lại thành môi trường Apidog |
Bộ kiểm thử đơn vị (inso run test) |
Một phần | Xây dựng lại thành các kịch bản kiểm thử Apidog |
Cấu hình lint Spectral (inso lint spec) |
Không 1:1 | Xem ghi chú trung thực bên dưới |
Ghi chú trung thực: inso lint spec chạy Spectral, linter OpenAPI của Stoplight, và đó là một điểm mạnh thực sự. Apidog CLI không đi kèm một linter spec độc lập, hướng dẫn kiểu, lệnh tách, gộp, hoặc đóng gói. Apidog xác thực spec của bạn khi bạn nhập nó, vì vậy các vấn đề cấu trúc sẽ xuất hiện tại thời điểm nhập, nhưng nếu pipeline của bạn phụ thuộc vào các bộ quy tắc Spectral tùy chỉnh làm cổng, hãy giữ Spectral trong CI của bạn cùng với Apidog. Đừng mong đợi apidog lint. Nó không có ở đó, và giả vờ có sẽ chỉ khiến bạn gặp rắc rối sau này.
Bước 1: xuất các spec và kiểm thử của bạn từ Insomnia
inso có thể ghi tài liệu thiết kế của bạn trực tiếp vào một tệp. Spec được tham chiếu bằng tên, cùng tên bạn thấy trong ứng dụng Insomnia:
# Xuất tài liệu thiết kế OpenAPI sang tệp YAML
inso export spec "My API Design" --output my-api.yaml
Nếu inso không thể tìm thấy dữ liệu của bạn, hãy chỉ nó đến đúng nguồn. Theo mặc định, nó đọc từ thư mục .insomnia trong thư mục làm việc hoặc thư mục dữ liệu ứng dụng Insomnia. Ghi đè bằng --workingDir hoặc --src:
inso export spec "My API Design" --workingDir ./design --output my-api.yaml
Đối với các bộ sưu tập yêu cầu và bất kỳ thứ gì inso không xuất sạch sẽ, hãy sử dụng chính ứng dụng Insomnia: mở ứng dụng, chọn không gian làm việc của bạn và sử dụng Export để tạo tệp OpenAPI hoặc Insomnia v4. Giữ cả tài liệu thiết kế và xuất bộ sưu tập. Bạn sẽ nhập chúng riêng biệt.
Nếu bạn đang trong quá trình khôi phục và ứng dụng không hợp tác, hướng dẫn xuất và khôi phục sẽ đề cập đến việc lấy dữ liệu ra khi Git Sync hoặc tài khoản đám mây gây khó dễ cho bạn.
Bước 2: nhập vào Apidog
Mở Apidog, tạo một dự án và nhập tệp YAML hoặc JSON mà bạn vừa xuất. Apidog đọc OpenAPI nguyên bản, vì vậy các điểm cuối, lược đồ và dữ liệu ví dụ của bạn sẽ trở thành các tài nguyên có cấu trúc mà bạn có thể chỉnh sửa, tạo mock và kiểm thử.
Bạn cũng có thể nhập từ CLI như một phần của thiết lập tự động, điều này tiện lợi khi bạn đang tạo tập lệnh cho một nhóm chứ không phải nhấp qua giao diện người dùng. Apidog nhập OpenAPI và quản lý các điểm cuối, lược đồ, môi trường, nhánh và yêu cầu hợp nhất dưới dạng mã từ terminal, xác thực thông qua đăng nhập hoặc mã thông báo truy cập. Nếu bạn đang thiết lập CLI lần đầu, hướng dẫn cài đặt Apidog CLI và hướng dẫn CLI đầy đủ đề cập đến thiết lập và luồng xác thực.
Khi nhập, Apidog xác thực spec. Nếu OpenAPI của bạn có các vấn đề cấu trúc, bạn sẽ biết ngay bây giờ chứ không phải lúc chạy. Đây là điểm tương tự gần nhất với inso lint spec, với một sự khác biệt đáng lặp lại: đó là xác thực, không phải một bộ quy tắc Spectral có thể cấu hình được.
Bước 3: ánh xạ các lệnh của bạn (phần bạn đến vì nó)
Đây là phần chính của quá trình di chuyển. Đây là cách các lệnh inso được chuyển đổi sang apidog run.
| Bạn muốn làm gì | Lệnh inso | Tương đương Apidog CLI |
|---|---|---|
| Chạy một bộ kiểm thử đơn vị | inso run test "Smoke Suite" --env "Staging" |
apidog run --test-scenario "Smoke Suite" -e staging |
| Chạy một bộ sưu tập | inso run collection "Checkout Flow" --env "Staging" |
apidog run "Checkout Flow" -e staging |
| Chạy một script được đặt tên | inso script ci-smoke --env <env-id> |
apidog run -e <env-id> (được nối vào script CI của bạn) |
| Lint một spec OpenAPI | inso lint spec "My API Design" |
Không 1:1; Apidog xác thực khi nhập |
| Xuất một spec ra tệp | inso export spec "My API Design" --output api.yaml |
Được xử lý bởi chức năng nhập/xuất của Apidog, không phải là bước chạy |
Một vài ghi chú về ánh xạ:
- Môi trường.
insosử dụng--env "tên". Apidog sử dụng-e(--env). Cả hai đều chọn URL cơ sở và các biến của môi trường nào sẽ áp dụng. Trước tiên hãy tạo lại môi trường Insomnia của bạn thành môi trường Apidog, sau đó tham chiếu chúng bằng tên hoặc ID. - Bộ kiểm thử trở thành kịch bản kiểm thử. Trong khi
inso run testchạy một bộ kiểm thử đơn vị Insomnia, Apidog chạy các kịch bản kiểm thử. Khái niệm này ánh xạ rõ ràng: các yêu cầu được sắp xếp với các xác nhận. Bạn sẽ xây dựng lại bộ kiểm thử một lần trong Apidog, sau đó nó sẽ chạy trên mỗi lệnhapidog run. inso scriptlà gián tiếp. Nếu bạn gói các lệnh đằng sau các script được đặt tên, chỉ cần gọiapidog runtrực tiếp trong bước CI của bạn, hoặc gói nó trong script npm/make của riêng bạn.
Để so sánh từng lệnh một sâu hơn, Apidog CLI vs inso (Insomnia CLI) đi chi tiết từng cờ. Nếu bạn đã từng dùng Newman hoặc Postman CLI trước đây, Apidog CLI vs Newman và Apidog CLI vs Postman CLI cũng đề cập đến chúng.
Bước 4: di chuyển các công cụ báo cáo của bạn
inso dựa vào đầu ra kiểm thử và báo cáo kiểu JUnit cho CI. Apidog cung cấp cho bạn các công cụ báo cáo ở định dạng CLI, HTML và JSON, vì vậy bản dựng của bạn có thể in kết quả dễ đọc cho console và xuất một tạo tác có thể đọc bằng máy cùng lúc:
# Chạy một kịch bản và xuất cả tóm tắt CLI và báo cáo HTML
apidog run --test-scenario "Smoke Suite" -e staging -r cli,html
Chọn json khi một công cụ hạ nguồn cần phân tích kết quả, html khi người dùng xem xét bản dựng và cli cho luồng console trực tiếp. Bạn cũng có thể đẩy kết quả lên các báo cáo kiểm thử đám mây của Apidog bằng --upload-report để toàn bộ nhóm thấy được lượt chạy mà không cần đào sâu nhật ký CI. Hướng dẫn báo cáo kiểm thử trình bày chi tiết các định dạng.
Bước 5: mang các bài kiểm thử hướng dữ liệu sang
Nếu bộ Insomnia của bạn lặp qua dữ liệu, Apidog hỗ trợ kiểm thử hướng dữ liệu nguyên bản. Cung cấp bộ dữ liệu CSV hoặc JSON với -d và kịch bản sẽ chạy một lần cho mỗi hàng:
apidog run --test-scenario "Login Matrix" -e staging -d ./users.csv -r cli,json
Đây là một điểm mà Apidog có xu hướng cảm thấy ít bị gắn chặt hơn so với việc xâu chuỗi dữ liệu bên ngoài qua inso. Hướng dẫn kiểm thử hướng dữ liệu chỉ ra các định dạng bộ dữ liệu và liên kết biến.
Bước 6: kết nối nó vào CI
Bước cuối cùng là hoán đổi lệnh trong pipeline của bạn. GitHub Actions hoặc bước GitLab cũ của bạn có lẽ trông như thế này:
# Trước: inso trong CI
inso run test "Smoke Suite" --env "CI" --reporter junit
Tương đương với Apidog:
# Sau: Apidog CLI trong CI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json --upload-report
Xác thực trình chạy bằng một mã thông báo truy cập được lưu trữ dưới dạng bí mật CI, giống như cách bạn xử lý bất kỳ bước có thông tin đăng nhập nào. Hướng dẫn pipeline CI/CD và hướng dẫn GitHub Actions có các tệp workflow có thể sao chép. Để biết chi tiết về mã thông báo và đăng nhập, hãy xem xác thực Apidog CLI.
Nếu bạn giữ Spectral để linting (được khuyến nghị nếu bạn có các quy tắc tùy chỉnh), pipeline của bạn hiện có hai cổng: Spectral lint spec, Apidog chạy các kiểm thử. Đó là một trạng thái cuối cùng hoàn toàn hợp lý, và nó trung thực về những gì mỗi công cụ làm tốt nhất.
Giữ Spectral trong vòng lặp
Để rõ ràng về một điều không thể chuyển: nếu linting là một phần trong hợp đồng của bạn, đừng bỏ nó. Spectral là mã nguồn mở và chạy tốt bên ngoài Insomnia. Một CI lai điển hình trông như thế này:
# Lint với Spectral (được giữ lại từ thiết lập inso của bạn)
npx @stoplight/spectral-cli lint my-api.yaml
# Kiểm thử với Apidog CLI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json
Bạn không mất gì về phía linting và có được nền tảng thiết kế-mock-test-docs tích hợp của Apidog cho mọi thứ khác. Đó là sự đánh đổi chính xác, và nó tốt cho hầu hết các nhóm.
inso vs Apidog CLI: Tổng quan nhanh
| Khả năng | inso (Insomnia CLI) | Apidog CLI |
|---|---|---|
| Chạy bộ sưu tập / bộ kiểm thử | Có | Có |
| Môi trường | --env |
-e / --env |
| Linting OpenAPI | Có (Spectral) | Không có lệnh độc lập (xác thực khi nhập) |
| Kiểm thử hướng dữ liệu | Hạn chế | Có (-d, CSV/JSON) |
| Định dạng báo cáo | CLI, JUnit | CLI, HTML, JSON, tải lên đám mây |
| Resource-as-code | Đọc thư mục .insomnia |
Điểm cuối, lược đồ, nhánh, yêu cầu hợp nhất |
| Là một phần của nền tảng hợp nhất | Insomnia + công cụ bên ngoài | Một nền tảng (thiết kế, mock, docs, kiểm thử) |
| Yêu cầu tài khoản đám mây cho ứng dụng | Có (Insomnia 8+) | Tài khoản Apidog, thân thiện với cục bộ |
Câu hỏi thường gặp
Liệu spec OpenAPI của Insomnia của tôi có nhập vào Apidog mà không cần chỉnh sửa không? Thường là có. Apidog đọc OpenAPI nguyên bản và xác thực khi nhập. Nếu xác thực báo lỗi, đó thường là một vấn đề cấu trúc thực sự trong spec, và việc khắc phục nó một lần sẽ mang lại lợi ích cho mọi công cụ hạ nguồn.
Apidog CLI có lệnh lint giống như inso lint spec không? Không. Apidog xác thực các spec khi nhập, nhưng không có linter CLI độc lập hoặc lệnh hướng dẫn kiểu. Nếu bạn dựa vào các bộ quy tắc Spectral tùy chỉnh, hãy giữ Spectral trong pipeline của bạn bên cạnh apidog run. Để so sánh song song, hãy xem Apidog CLI vs Redocly CLI, vì Redocly CLI có bao gồm một linter.
Tôi có thể chạy Apidog CLI trong CI giống như cách tôi đã chạy inso không? Có. Hoán đổi lệnh, xác thực bằng mã thông báo truy cập từ một bí mật CI và chọn các công cụ báo cáo của bạn. Hướng dẫn CI/CD có các ví dụ workflow đầy đủ.
Điều gì xảy ra với các bộ kiểm thử đơn vị Insomnia của tôi? Bạn xây dựng lại chúng thành các kịch bản kiểm thử Apidog. Cấu trúc được giữ nguyên trực tiếp: các yêu cầu được sắp xếp cộng với các xác nhận. Đây là một lần xây dựng lại duy nhất, sau đó chúng sẽ chạy trên mỗi lệnh apidog run.
Tôi đang di chuyển khỏi Insomnia do sự cố mất dữ liệu. Tôi nên bắt đầu từ đâu? Trước tiên, hãy khôi phục dữ liệu của bạn bằng cách sử dụng hướng dẫn khôi phục và xuất, sau đó làm theo Bước 2 ở trên để nhập dữ liệu đã xuất đã làm sạch vào Apidog.
Tổng kết
Di chuyển từ inso sang Apidog CLI chủ yếu là một công việc dịch thuật: xuất các spec và bộ kiểm thử của bạn, nhập chúng vào Apidog, viết lại inso run test và inso run collection thành apidog run, chuyển --env thành -e, và trỏ các công cụ báo cáo của bạn đến đầu ra CLI/HTML/JSON của Apidog. Hãy giữ Spectral nếu bạn thực hiện linting, vì Apidog xác thực khi nhập nhưng không thay thế bộ quy tắc tùy chỉnh.
Lợi ích là một nền tảng duy nhất thay vì một ngăn xếp mà bạn phải tiếp tục ghép nối. Sẵn sàng thử chưa? Tải xuống Apidog và chạy lệnh apidog run đầu tiên của bạn với spec mà bạn vừa xuất.
nút