Nếu bạn đã sử dụng client API Insomnia, bạn sẽ có một giao diện đồ họa để gửi các yêu cầu, thiết kế thông số kỹ thuật OpenAPI và viết các bài kiểm tra. Nhưng các công cụ đồ họa chỉ dừng lại ở máy của bạn. Thời điểm bạn muốn các bài kiểm tra đó chạy trong một pipeline CI, hoặc bạn muốn kiểm tra cú pháp (lint) một thông số kỹ thuật trên mỗi pull request, bạn cần một thứ hoạt động trong terminal. Thứ đó chính là inso.
Hướng dẫn này giải thích inso là gì, cách cài đặt, các lệnh chính xác bạn sẽ sử dụng hàng ngày, cách nó tìm thấy các thông số kỹ thuật và bộ sưu tập của bạn, cũng như các giới hạn của nó. Đến cuối bài, bạn sẽ biết liệu inso CLI có phù hợp với quy trình làm việc của bạn hay không, và cần sử dụng gì nếu nó không phù hợp.
inso là gì?
inso là công cụ dòng lệnh đi kèm với Insomnia, client API mã nguồn mở hiện được duy trì bởi Kong. Nó lấy ba chức năng mà Insomnia thực hiện trong giao diện người dùng và biến chúng thành có thể kịch bản hóa: chạy các bài kiểm tra, thực thi các bộ sưu tập yêu cầu và kiểm tra cú pháp các thông số kỹ thuật API. Điều đó biến nó thành cầu nối giữa Insomnia trên máy tính để bàn của bạn và các kiểm tra tự động mà bạn muốn trong CI/CD.
Phiên bản ngắn gọn của "inso là gì": đó là cách bạn chạy công việc Insomnia mà không cần mở Insomnia. Bạn chỉ nó đến một tài liệu thiết kế hoặc một bộ sưu tập theo tên, và nó sẽ thực thi dựa trên cùng dữ liệu mà ứng dụng của bạn đã biết.
Cài đặt inso cli
Bạn có một vài cách đã được ghi lại. Hãy chọn cách phù hợp với cách bạn triển khai.
Homebrew là cách đơn giản nhất trên macOS và Linux:
brew install inso
Docker là lựa chọn sạch sẽ nhất cho các CI runner, nơi bạn không muốn quản lý một chuỗi công cụ cục bộ:
docker pull kong/inso:latest
Bạn cũng có thể tải xuống trực tiếp. Kong xuất bản các tệp lưu trữ zip cho Windows, Linux và macOS trên trang tài liệu inso CLI, rất tiện lợi khi bạn muốn một phiên bản cụ thể trong một artifact bản dựng.
Trước đây, inso cũng được phân phối trên npm dưới dạng insomnia-inso. Con đường đó vẫn tồn tại, nhưng các cách được tài liệu hóa và khuyến nghị hiện nay là Homebrew, Docker và các bản tải xuống trực tiếp. Nếu bạn đang thiết lập một cái gì đó mới, hãy ưu tiên những cách này.
Xác nhận cài đặt đã thành công:
inso --version
Các lệnh inso cốt lõi
inso có một bề mặt nhỏ, tập trung. Dưới đây là các lệnh bạn thực sự sẽ sử dụng, với các ví dụ thực tế.
inso run test
Chạy một bộ kiểm thử đơn vị bạn đã tạo trong Insomnia, chống lại một môi trường được đặt tên:
inso run test "Payments API tests" --env "Staging"
Cả bộ kiểm thử và môi trường đều được tham chiếu bằng tên, chính xác như chúng xuất hiện trong dữ liệu Insomnia của bạn. Lệnh inso run test sẽ thoát với mã lỗi khác 0 nếu bất kỳ khẳng định nào thất bại, điều này làm cho nó có thể sử dụng được như một cổng CI.
inso run collection
Chạy mọi yêu cầu trong một bộ sưu tập theo trình tự, một lần nữa chống lại một môi trường được đặt tên:
inso run collection "Checkout flow" --env "Staging"
Đây là tương đương gần nhất với "phát toàn bộ thư mục" trong giao diện người dùng. Nó hữu ích cho các bài kiểm tra khói (smoke test) nơi bạn muốn xác nhận một chuỗi các điểm cuối đều phản hồi như mong đợi.
inso lint spec
Xác thực một tài liệu thiết kế OpenAPI:
inso lint spec "Orders API"
Bên dưới, inso lint spec sử dụng Spectral, công cụ kiểm tra cú pháp OpenAPI và JSON mã nguồn mở từ Stoplight. Đây là một điểm mạnh thực sự đáng được nhắc đến rõ ràng: bạn có được khả năng kiểm tra cú pháp dựa trên quy tắc thực sự với một bộ quy tắc trưởng thành, không phải là một kiểm tra cú pháp nông cạn. Nếu nhóm của bạn quan tâm đến việc thực thi quy tắc kiểu trên các thông số kỹ thuật, lệnh này là lý do nhiều người giữ inso bên mình.
inso export spec
Xuất một tài liệu thiết kế ra một tệp trên đĩa:
inso export spec "Orders API" --output orders.yaml
Tiện lợi khi bạn muốn đưa thông số kỹ thuật cho một trình tạo khác, cam kết một snapshot hoặc giao nó cho một công cụ mong đợi một tệp YAML thuần túy.
inso script
Chạy một script được đặt tên được định nghĩa trong dữ liệu Insomnia của bạn, truyền một môi trường theo ID:
inso script deploy-smoke --env env_9f2a
Đây là lối thoát để bạn tự xâu chuỗi các bước tùy chỉnh của mình.
Cách inso tìm các thông số kỹ thuật và bộ sưu tập của bạn
Đây là phần mà mọi người hay vấp phải, vì vậy đáng để nói rõ. inso không tự lưu trữ bất cứ thứ gì. Nó đọc từ một trong hai nơi:
- Một thư mục
.insomniatrong thư mục làm việc của bạn. Đây là thứ mà Git Sync của Insomnia tạo ra, vì vậy khi bạn commit dự án API của mình vào một repo, inso có thể đọc trực tiếp từ bản checkout. Đây là mẫu bạn muốn cho CI. - Thư mục dữ liệu ứng dụng Insomnia, nếu ứng dụng được cài đặt trên máy. Điều này tiện lợi cục bộ nhưng vô dụng trên một CI runner sạch sẽ chưa bao giờ cài đặt ứng dụng.
Bạn có thể ghi đè nguồn một cách rõ ràng:
inso lint spec "Orders API" --workingDir ./api-project
# hoặc chỉ định một nguồn chính xác
inso run test "Payments API tests" --src ./api-project/.insomnia
Mô hình tư duy chính: inso tham chiếu mọi thứ bằng tên (hoặc ID), và các tên đó được phân giải chống lại bất kỳ nguồn dữ liệu nào nó tìm thấy. Nếu một tên không có trong thư mục .insomnia hoặc dữ liệu ứng dụng, inso không thể chạy nó. Không có khái niệm chỉ inso vào một tệp OpenAPI rời rạc và nói "kiểm tra cái này" trừ khi tệp đó nằm trong cấu trúc dự án Insomnia.
Một ví dụ CI tối thiểu
Đây là một job GitHub Actions kiểm tra cú pháp một spec và chạy một bộ kiểm thử trên mỗi lần push, sử dụng thư mục .insomnia được đồng bộ hóa với Git đã được commit vào repo:
name: API checks
on: [push]
jobs:
inso:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install inso
run: |
curl -sSL https://github.com/Kong/insomnia/releases/latest/download/inso-linux-x64.zip -o inso.zip
unzip inso.zip && sudo mv inso /usr/local/bin/
- name: Lint the spec
run: inso lint spec "Orders API" --workingDir .
- name: Run the test suite
run: inso run test "Payments API tests" --env "CI" --workingDir .
Vì cả hai lệnh đều thoát với mã lỗi khác 0 khi thất bại, một spec bị hỏng hoặc một khẳng định thất bại sẽ khiến job thất bại. Đó là toàn bộ mục đích của việc chuyển các kiểm tra này ra khỏi GUI.
Những hạn chế thực tế
inso làm tốt những gì nó được thiết kế, nhưng nó có những giới hạn rõ ràng.
Nó gắn liền với các nguồn dữ liệu của Insomnia. Các spec, bộ sưu tập và bộ kiểm thử của bạn phải nằm trong một dự án Insomnia, được hiển thị thông qua Git Sync hoặc ứng dụng đã cài đặt. Nếu nhóm của bạn không sử dụng Insomnia làm nguồn đáng tin cậy, inso không có gì để hoạt động.
Mọi thứ đều được tham chiếu bằng tên. Điều này dễ đọc, nhưng dễ gãy. Đổi tên một bộ kiểm thử trong UI và một job CI mã hóa cứng tên cũ sẽ bị hỏng âm thầm cho đến lần chạy tiếp theo. Tên cũng phải đủ độc đáo để phân giải rõ ràng.
Phạm vi hẹp theo thiết kế. inso chạy các bài kiểm tra, chạy các bộ sưu tập, kiểm tra cú pháp các spec, xuất và chạy các script. Nó không phải là một nền tảng thiết kế-mock-tài liệu-kiểm tra. Đối với bất cứ điều gì ngoài các động từ đó, bạn sẽ phải quay lại GUI hoặc tìm kiếm các công cụ khác.
inso so với giải pháp thay thế tích hợp
inso là một công cụ terminal mạnh mẽ khi Insomnia đã là client của bạn. Sự đánh đổi là bạn đang ghép nối các mảnh: Insomnia để thiết kế và gỡ lỗi, inso cho CI, các quy tắc Spectral để kiểm tra cú pháp, và các công cụ riêng biệt cho mock và tài liệu.
Apidog có quan điểm ngược lại. Nó đặt thiết kế, mock, tài liệu và kiểm thử vào một nền tảng, và Apidog CLI của nó chạy các kịch bản kiểm thử và bộ sưu tập của bạn từ cùng một nguồn đáng tin cậy, với kiểm thử dựa trên dữ liệu, nhiều định dạng báo cáo, và tài nguyên-và-nhánh-như-code. Đáng nói một cách công bằng ở đây: Apidog CLI không đi kèm với một công cụ kiểm tra cú pháp spec độc lập như inso làm với Spectral, vì vậy nếu việc thực thi quy tắc kiểu theo phong cách Spectral là ưu tiên của bạn, inso có một lợi thế thực sự ở đó. Nơi Apidog vượt trội là tính tích hợp. Bạn không phải gắn kết năm công cụ lại với nhau.
Nếu bạn muốn so sánh hai công cụ này trực tiếp, hãy xem Apidog CLI vs inso (Insomnia CLI), hoặc đọc chi tiết hơn trong bài viết inso (Insomnia CLI) là gì. Nếu bạn đã quyết định inso không phải là lựa chọn phù hợp, tổng hợp các lựa chọn thay thế inso tốt nhất và hướng dẫn di chuyển từ inso sang Apidog CLI sẽ hướng dẫn bạn từng bước một. Để có cái nhìn rộng hơn về các client GUI, Apidog vs Insomnia và cách sử dụng Insomnia để kiểm thử API là những điểm khởi đầu tốt.
Bạn có thể tải xuống Apidog miễn phí nếu bạn muốn xem cách tiếp cận tích hợp song song với thiết lập inso của mình.