Hoppscotch CLI là gì

Hoppscotch là một hệ sinh thái API mã nguồn mở; bao gồm ứng dụng web, ứng dụng máy tính để bàn, CLI và một backend có thể tự host, thường được mô tả là một giải pháp thay thế mã nguồn mở cho Postman và Insomnia. Hoppscotch CLI là thành phần giúp bạn lấy các bộ sưu tập (collections) đã xây dựng trong hệ sinh thái đó và chạy chúng từ một terminal, đây chính xác là thứ bạn cần cho CI/CD.

Hướng dẫn này giải thích Hoppscotch CLI là gì, cách cài đặt nó và cách lệnh hopp test thực sự hoạt động, cùng với các cờ (flags) thực tế và một ví dụ CI đang hoạt động. Nếu bạn đang cân nhắc nó với các runner khác, bài đăng các giải pháp thay thế Hoppscotch CLI tốt nhất so sánh các lựa chọn, và Apidog CLI so với Hoppscotch CLI là cuộc đối đầu trực tiếp.

button

Hoppscotch CLI là gì

The Hoppscotch CLI được phân phối dưới dạng gói npm @hoppscotch/cli. Nhiệm vụ của nó cụ thể và hữu ích: lấy một bộ sưu tập Hoppscotch, chạy mọi yêu cầu trong đó, thực thi các script kiểm thử đính kèm với các yêu cầu đó và thoát với một mã pass/fail mà pipeline của bạn có thể đọc được.

Điều đó khiến nó trở thành một trình chạy bộ sưu tập (collection runner), cùng loại với Newman cho Postman hoặc inso cho Insomnia. Nó không thiết kế API, giả lập các endpoint, hoặc tạo tài liệu. Nó chạy các yêu cầu và kiểm tra các khẳng định (assertions). Đối với một công cụ mã nguồn mở, miễn phí mà bạn cũng có thể tự host, trọng tâm đó là mấu chốt.

Vì Hoppscotch là mã nguồn mở, bạn có thể tự chạy toàn bộ hệ thống và trỏ CLI đến phiên bản của riêng bạn. Các nhóm không muốn dữ liệu yêu cầu của họ nằm trên đám mây của nhà cung cấp thường thích điều đó. Đánh đổi là bạn phải tự chịu trách nhiệm về việc hosting.

Cài đặt Hoppscotch CLI

Cài đặt nó trên toàn cầu từ npm:

npm i -g @hoppscotch/cli

Một yêu cầu cần lưu ý: CLI hiện tại cần Node.js v22 trở lên. Nếu bạn vẫn đang sử dụng Node 20, bạn có thể giữ nguyên CLI v0.26.0, nhưng các bản phát hành mới nhất giả định v22+. Kiểm tra phiên bản của bạn trước khi tích hợp nó vào một build agent:

node --version
hopp --version

Nếu image CI của bạn sử dụng Node cũ hơn, hãy ghim runtime về v22 trong pipeline, nếu không bạn sẽ gặp lỗi cài đặt hoặc runtime trông có vẻ không liên quan đến các bài kiểm thử của bạn.

Lệnh hopp test

Mọi thứ đều chạy thông qua hopp test. Cú pháp cơ bản trỏ nó đến một tệp bộ sưu tập (collection file):

hopp test ./my-collection.json

Bạn có thể truyền một tệp môi trường (environment file) và độ trễ giữa các yêu cầu:

hopp test ./my-collection.json -e ./staging.env.json -d 500

Ở đây -e (hoặc --env) cung cấp môi trường, và -d (hoặc --delay) đợi số mili giây đã cho giữa các yêu cầu, điều này hữu ích khi bạn đang gọi một API bị giới hạn tốc độ.

Nếu các bộ sưu tập của bạn nằm trong một phiên bản Hoppscotch (trên đám mây hoặc tự host) thay vì một tệp cục bộ, bạn tham chiếu chúng bằng ID và xác thực bằng một mã thông báo truy cập cá nhân:

hopp test <collection-id> --token <access_token> --server https://hoppscotch.your-company.com

--token mang mã thông báo truy cập cá nhân của bạn, và --server trỏ đến URL tự host của bạn. Bỏ --server nếu bạn đang sử dụng Hoppscotch cloud được host.

Các lượt chạy theo dữ liệu và báo cáo

Hai cờ (flags) biến hopp test từ một lượt chạy đơn lẻ thành một thứ thân thiện với CI.

Để kiểm thử theo dữ liệu (data-driven testing), hãy cung cấp một tệp CSV và đặt số lần lặp để chạy:

hopp test ./my-collection.json --iteration-data ./users.csv --iteration-count 3

--iteration-data nhận một tệp CSV mà các cột của nó trở thành biến trong mỗi lần chạy, và --iteration-count kiểm soát số lần bộ sưu tập lặp lại. Đó là ý tưởng tương tự như -d của Newman, và nó bao gồm trường hợp phổ biến "chạy luồng đăng nhập này với 50 tài khoản".

Để báo cáo, CLI ghi ra JUnit XML, mà hầu hết các hệ thống CI có thể tiếp nhận để hiển thị kết quả kiểm thử một cách tự nhiên:

hopp test ./my-collection.json --reporter-junit ./report.xml

JUnit là định dạng báo cáo có cấu trúc duy nhất mà CLI tạo ra. Nếu bạn cần các tạo phẩm HTML hoặc các báo cáo có thể liên kết, được host, đó là một khoảng trống đáng để biết trước khi bạn cam kết. Các công cụ như Apidog CLI xuất ra báo cáo CLI, HTML và JSON để so sánh.

Những gì thực sự được thực thi trong một lượt chạy

Khi bạn chạy hopp test, CLI sẽ duyệt qua bộ sưu tập theo thứ tự và, đối với mỗi yêu cầu:

chạy script tiền yêu cầu (pre-request script),
gửi yêu cầu,
chạy script kiểm thử và đánh giá từng khẳng định (assertion).

Các script kiểm thử sử dụng API script của Hoppscotch: pw.test() định nghĩa một khối kiểm thử và pw.expect() tạo ra các khẳng định bên trong đó. Một ví dụ nhỏ đính kèm vào một yêu cầu trông như thế này:

pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});

Nếu bất kỳ khẳng định nào thất bại, lệnh sẽ thoát với mã khác 0. Nếu mọi thứ đều thành công, nó sẽ thoát với mã 0. Hành vi mã thoát đó là toàn bộ hợp đồng với CI: mã thoát khác 0 làm lỗi bản dựng, đó chính xác là điều bạn muốn.

Một ví dụ về GitHub Actions

Tích hợp hopp test vào CI rất đơn giản. Quy trình làm việc này cài đặt CLI trên một runner Node 22 và chạy một bộ sưu tập trên mỗi lần push:

name: API tests
on: [push]
jobs:
  hopp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm i -g @hoppscotch/cli
      - run: hopp test ./collection.json -e ./ci.env.json --reporter-junit ./report.xml

Bước setup-node ghim phiên bản v22 là phần mà mọi người thường quên. Nếu không có nó, Node mặc định của runner có thể quá cũ so với CLI hiện tại.

Những hạn chế cần lưu ý

Hoppscotch CLI làm tốt công việc của mình và minh bạch về phạm vi của nó:

Nó là một trình chạy bộ sưu tập (collection runner), không phải một nền tảng. Không có thiết kế, giả lập, hoặc tài liệu. Bạn phải tự mang những thứ đó từ nơi khác đến.
Bạn tự xuất hoặc host các bộ sưu tập. CLI chạy một tệp bộ sưu tập hoặc lấy một tệp từ một phiên bản mà bạn trỏ nó đến.
JUnit là báo cáo có cấu trúc duy nhất. Không có báo cáo HTML tích hợp sẵn hoặc báo cáo được host.
Node v22+. Một yêu cầu bắt buộc đối với các bản phát hành hiện tại.

Không có điều nào trong số đó là một sự phê phán; đó là cái giá của một công cụ mã nguồn mở, miễn phí và nhỏ gọn. Nếu nhu cầu của bạn vượt ra ngoài "chạy một bộ sưu tập trong CI" sang thiết kế, giả lập, các lượt chạy theo dữ liệu với báo cáo phong phú hơn, và quản lý tài nguyên API dưới dạng mã, thì đó là lúc một nền tảng tích hợp phát huy tác dụng. Apidog bao gồm toàn bộ vòng đời API, và hướng dẫn đầy đủ về Apidog CLI cho thấy phía terminal. Bạn có thể tải xuống Apidog và nhập một bộ sưu tập Hoppscotch để so sánh trực tiếp, hoặc đọc hướng dẫn di chuyển.

Câu hỏi thường gặp

Hoppscotch CLI có miễn phí không? Có. Nó là mã nguồn mở thuộc dự án Hoppscotch, và bạn có thể tự host toàn bộ hệ sinh thái. Xem tài liệu CLI chính thức và kho lưu trữ GitHub.

Sự khác biệt giữa hopp test và Newman là gì? Cả hai đều là trình chạy bộ sưu tập (collection runner) với các lần lặp theo dữ liệu. Newman chạy các bộ sưu tập Postman; hopp test chạy các bộ sưu tập Hoppscotch. Các khái niệm tương đồng chặt chẽ, bao gồm dữ liệu lặp CSV và pass/fail dựa trên mã thoát.

Hoppscotch CLI có thể chạy các bộ sưu tập từ một máy chủ tự host không? Có. Sử dụng hopp test <collection-id> --token <access_token> --server <your-url> để kéo và chạy một bộ sưu tập từ phiên bản của riêng bạn.

Nó có tạo báo cáo HTML không? Không trực tiếp. Nó ghi JUnit XML thông qua --reporter-junit. Để có báo cáo CLI, HTML và JSON cùng nhau, hãy so sánh với báo cáo kiểm thử Apidog CLI.

Hoppscotch CLI là một cách sạch sẽ, miễn phí để chạy các bộ sưu tập API trong CI, đặc biệt nếu bạn đã sử dụng Hoppscotch hoặc tự host nó. Hãy nắm rõ phạm vi của nó, ghim Node v22 và dựa vào đầu ra JUnit, và nó sẽ làm tốt công việc của mình.

button