Hướng dẫn di chuyển từ Hoppscotch CLI sang 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 terminal hoặc pipeline CI. Lệnh hopp test đọc một tệp bộ sưu tập, thực thi mọi yêu cầu, chạy các script tiền yêu cầu và script kiểm thử của bạn, và thoát với mã lỗi nếu một xác nhận thất bại. Đối với nhiều nhóm, chừng đó là đủ.

Nhưng một trình chạy chỉ là một phần nhỏ của công việc API. Đến một lúc nào đó, bạn phải xử lý đồng thời một công cụ thiết kế riêng biệt, một máy chủ giả lập, một trang tài liệu và trình chạy, mà không công cụ nào trong số chúng chia sẻ một nguồn thông tin đáng tin cậy duy nhất. Đó thường là lúc các nhóm bắt đầu tìm cách di chuyển từ Hoppscotch CLI sang Apidog CLI. Apidog tích hợp thiết kế, gỡ lỗi, giả lập, tài liệu hóa và kiểm thử vào một nền tảng duy nhất, và CLI của nó chạy phần kiểm thử trong CI. Trình chạy vẫn giữ hình dạng quen thuộc mà bạn đã biết. Điều thay đổi là mọi thứ xung quanh nó.

Tải ứng dụng

Khi bạn nên (và không nên) di chuyển

Hãy thành thật với bản thân trước. Nếu yêu cầu duy nhất của bạn là “chạy một bộ sưu tập trong CI miễn phí, tự host nếu muốn,” thì Hoppscotch CLI là một công cụ thực sự tốt. Nó là mã nguồn mở, trình chạy nhanh, và @hoppscotch/cli được phát hành dưới dạng một gói npm thông thường. Không có gì đáng xấu hổ khi bạn tiếp tục sử dụng nó.

Di chuyển khi một trong những điều sau đây bắt đầu gây khó khăn:

Bạn thiết kế API trong một công cụ, giả lập trong một công cụ khác, và viết tài liệu trong công cụ thứ ba, và việc giữ chúng đồng bộ là công việc thủ công.
Bạn muốn các lần chạy kiểm thử, máy chủ giả lập và tài liệu đã xuất bản chia sẻ một định nghĩa dự án duy nhất.
Bạn cần báo cáo phong phú hơn (báo cáo HTML cho các bên liên quan, JSON cho máy) cùng với lịch sử chạy được lưu trữ trên đám mây.
Bạn muốn coi các endpoint, schema, môi trường và nhánh như code mà CLI có thể quản lý, chứ không chỉ thực thi.

Nếu danh sách đó giống như những gì bạn làm trong tuần, thì nền tảng là lý do để bạn chuyển đổi, chứ không phải trình chạy. Dưới đây là cách thực hiện một cách gọn gàng.

Bước 1: Xuất bộ sưu tập và môi trường Hoppscotch của bạn

Mọi thứ trong Hoppscotch đều là JSON, điều này làm cho việc xuất rất dễ dàng.

Từ ứng dụng Hoppscotch (web hoặc máy tính để bàn), mở bộ sưu tập bạn chạy trong CI. Sử dụng menu của bộ sưu tập và chọn Export (Xuất), bạn sẽ nhận được một tệp .json. Làm tương tự với môi trường bạn truyền bằng -e: mở bảng môi trường và xuất nó sang một tệp JSON riêng.

Nếu bạn đã chạy CLI với các tệp cục bộ, bạn đã có chúng trên đĩa. Một bước CI điển hình của Hoppscotch trông như sau:

npm i -g @hoppscotch/cli
hopp test ./collections/checkout-api.json -e ./environments/staging.json

Giữ cả hai tệp. checkout-api.json là bộ sưu tập của bạn, staging.json là môi trường của bạn. Hai tệp này là toàn bộ dữ liệu bạn sẽ di chuyển.

Một lưu ý về các phiên bản Node khi bạn ở đây. Hoppscotch CLI hiện tại yêu cầu Node.js v22 trở lên; các nhóm đang sử dụng Node 20 vẫn ở CLI v0.26.0. Apidog CLI không ràng buộc bạn với điều đó, vì vậy việc di chuyển cũng là cơ hội để bỏ một ràng buộc về phiên bản.

Bước 2: Nhập bộ sưu tập vào Apidog

Tạo một dự án trong Apidog (hoặc mở một dự án hiện có), sau đó nhập tệp xuất từ Hoppscotch của bạn. Apidog đọc các định dạng bộ sưu tập phổ biến và OpenAPI, vì vậy bạn có thể nhập bộ sưu tập trực tiếp. Nếu API của bạn cũng có đặc tả OpenAPI, hãy nhập nó vào. Apidog xác thực đặc tả khi nhập, vì vậy các vấn đề cấu trúc sẽ được phát hiện ngay lập tức thay vì thất bại âm thầm giữa chừng.

Ánh xạ môi trường Hoppscotch của bạn vào một môi trường Apidog với cùng tên biến. Nếu staging.json đã định nghĩa base_url và api_token, hãy tạo lại các khóa đó trong môi trường Apidog tương ứng. Việc giữ tên giống hệt nhau có nghĩa là các script kiểm thử và URL yêu cầu của bạn không cần chỉnh sửa.

Đây cũng là lúc phía nền tảng bắt đầu phát huy tác dụng. Các endpoint bạn đã nhập giờ đây là các đối tượng thiết kế. Bạn có thể đính kèm các schema, tạo một máy chủ giả lập từ chúng và xuất bản tài liệu từ cùng các định nghĩa mà bạn sử dụng để kiểm thử. Hướng dẫn đầy đủ về Apidog CLI bao gồm toàn bộ bề mặt khi bạn đã thiết lập, và hướng dẫn cài đặt xử lý trình chạy nhị phân.

Bước 3: Ánh xạ `hopp test` sang `apidog run`

Mô hình tư duy được chuyển giao trực tiếp. Nơi Hoppscotch chạy một tệp bộ sưu tập, Apidog chạy một kịch bản kiểm thử hoặc bộ sưu tập từ dự án của bạn. Cùng một công việc, nguồn thông tin đáng tin cậy khác nhau.

# Hoppscotch
hopp test ./collections/checkout-api.json -e ./environments/staging.json

# Apidog
apidog run --access-token $APIDOG_TOKEN -e "Staging"

Cả hai lệnh đều thực thi mọi yêu cầu theo thứ tự, chạy các script tiền yêu cầu, chạy các xác nhận kiểm thử của bạn và trả về mã thoát khác 0 nếu có bất kỳ điều gì thất bại. Quy ước mã thoát đó là phần mà CI phụ thuộc vào, và nó được giữ nguyên, vì vậy logic pass/fail của pipeline của bạn không thay đổi.

Xác thực khác biệt một cách hữu ích. Hoppscotch truyền mã thông báo truy cập cá nhân bằng --token cho các bộ sưu tập trên đám mây hoặc tự host. Apidog xác thực bằng thông tin đăng nhập hoặc mã thông báo truy cập, điều này sau đó cho phép CLI truy cập các tài nguyên trong dự án của bạn thay vì một tệp xuất duy nhất. Nếu bạn đã từng gặp khó khăn với việc xử lý mã thông báo, hướng dẫn xác thực sẽ trình bày các tùy chọn.

Bước 4: Chuyển đổi các lần chạy theo hướng dữ liệu

Cả hai công cụ đều thực hiện kiểm thử theo hướng dữ liệu, vì vậy việc lặp lại một tệp CSV chứa dữ liệu đầu vào vẫn được duy trì khi chuyển đổi.

Trong Hoppscotch, bạn truyền dữ liệu lặp và số lượng:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --iteration-count 50 \
  --iteration-data ./data/orders.csv

Trong Apidog, trình chạy nhận một tập dữ liệu với -d. Nó chấp nhận CSV và JSON, vì vậy cùng tệp orders.csv sẽ hoạt động sau khi nhập:

apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -d ./data/orders.csv

Hàng tiêu đề CSV của bạn trở thành tên biến mà bạn tham chiếu trong các yêu cầu và xác nhận, cùng một mẫu mà Hoppscotch sử dụng, vì vậy các phần thân kiểm thử không cần viết lại. Nếu bạn mới làm quen với cách tiếp cận này của Apidog, hướng dẫn kiểm thử theo hướng dữ liệu sẽ chỉ cho bạn cách liên kết các cột với các biến và chạy một hàng cho mỗi lần lặp.

Bước 5: Chuyển đổi các trình báo cáo của bạn

Báo cáo là nơi nền tảng thể hiện ưu thế, và việc chuyển đổi rất đơn giản.

Hoppscotch xuất ra một tệp JUnit XML chỉ với một cờ, mà hầu hết các hệ thống CI phân tích để hiển thị các bảng kiểm thử:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --reporter-junit ./reports/results.xml

Apidog cung cấp cho bạn nhiều lựa chọn trình báo cáo: một bản tóm tắt CLI dễ đọc, một báo cáo HTML bạn có thể gửi cho các bên liên quan, và một báo cáo JSON cho máy móc. Bạn cũng có thể đẩy kết quả lên đám mây để có lịch sử chạy có thể chia sẻ.

# Báo cáo HTML dễ đọc
apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report

Nếu bảng điều khiển CI của bạn đặc biệt mong đợi JUnit XML, hãy ghi nhớ việc tích hợp đó trong quá trình chuyển đổi, vì Apidog chủ yếu dựa vào các trình báo cáo CLI/HTML/JSON của nó cùng với các báo cáo trên đám mây thay vì một cờ JUnit. Đối với hầu hết các nhóm, báo cáo HTML cùng với lịch sử đám mây được tải lên là một bước tiến so với một tệp XML thô mà không ai mở. Hướng dẫn báo cáo kiểm thử phân tích từng định dạng và khi nào nên sử dụng chúng.

Trước và sau: Ánh xạ lệnh

Nhiệm vụ	Hoppscotch CLI	Apidog CLI
Cài đặt	`npm i -g @hoppscotch/cli`	Theo hướng dẫn cài đặt
Chạy bộ sưu tập	`hopp test collection.json`	`apidog run`
Chọn môi trường	`-e env.json`	`-e "Staging"`
Mã thông báo xác thực	`--token <pat>`	đăng nhập / `--access-token`
Mục tiêu tự host / đám mây	`--server <url>`	dự án + mã thông báo truy cập
Đầu vào theo hướng dữ liệu	`--iteration-data orders.csv`	`-d orders.csv`
Lặp lại các lần chạy	`--iteration-count 50`	tập dữ liệu lặp
Thêm độ trễ giữa các yêu cầu	`-d <ms>`	cài đặt từng kịch bản
Báo cáo JUnit	`--reporter-junit results.xml`	`-r json` (hoặc CLI / HTML)
Lịch sử chạy trên đám mây	không được tích hợp	`--upload-report`

Hãy chú ý đến cờ -d trong bảng đó. Trong Hoppscotch -d là độ trễ tính bằng mili giây; trong Apidog -d là tập dữ liệu cho các lần chạy theo hướng dữ liệu. Cùng một chữ cái, công việc khác nhau. Đây là một điểm khó khăn thường làm mọi người vấp váp khi chuyển đổi từ Hoppscotch sang Apidog.

Bước 6: Tích hợp vào GitHub Actions

Bước cuối cùng, và mục tiêu là có một bản dựng xanh hoàn chỉnh. Trước tiên, hãy thiết lập công việc Apidog song song với công việc Hoppscotch cũ, xác nhận nó thành công, sau đó xóa bước cũ. Đừng bao giờ chuyển đổi một cách mù quáng.

name: API tests
on: [push, pull_request]

jobs:
  apidog-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API tests
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          apidog run \
            --access-token "$APIDOG_TOKEN" \
            -e "Staging" \
            -d ./data/orders.csv \
            -r html \
            --upload-report

Lưu mã thông báo truy cập của bạn dưới dạng bí mật kho lưu trữ, không bao giờ trong tệp YAML. Bởi vì CLI trả về mã thoát khác 0 khi có bất kỳ xác nhận nào thất bại, công việc sẽ thất bại chính xác khi các bài kiểm thử của bạn thất bại, đây là hành vi mà nhóm của bạn đã tin tưởng từ Hoppscotch. Hướng dẫn GitHub Actions bao gồm việc lưu bộ nhớ đệm và chạy ma trận, và hướng dẫn pipeline CI/CD rộng hơn xử lý GitLab, Jenkins và các hệ thống khác.

Khi công việc Apidog đã chạy xanh vài lần, hãy xóa bước Hoppscotch và lệnh cài đặt npm của nó. Việc di chuyển hoàn tất, bản dựng không bao giờ gặp lỗi.

Một lời công bằng về Hoppscotch

Tất cả những điều này không phải là một lời chỉ trích Hoppscotch. Trình chạy CLI của nó nhanh và miễn phí, dự án hoàn toàn là mã nguồn mở, và bạn có thể tự host toàn bộ hệ thống. Nếu bạn muốn một trình chạy gọn nhẹ và không gì hơn, nó xứng đáng với vị trí của mình. Lý do để chuyển đổi là phạm vi: khi thiết kế, giả lập, tài liệu và kiểm thử đều cần chia sẻ một định nghĩa duy nhất, một trình chạy độc lập không thể cung cấp điều đó, và một nền tảng tích hợp thì có thể. So sánh trực tiếp hai trình chạy trong Apidog CLI so với Hoppscotch CLI, và nếu bạn đang cân nhắc các ứng dụng thay vì các CLI, thì Postman so với Hoppscotch và tổng hợp các lựa chọn thay thế Hoppscotch sẽ bổ sung thêm ngữ cảnh.