Hầu hết các bài kiểm thử API bắt đầu từ giao diện người dùng (GUI). Bạn nhấp chuột, thêm một vài xác nhận và chạy chúng theo cách thủ công. Điều này hiệu quả cho đến khi bạn cần các bài kiểm thử tương tự chạy trên mỗi lần đẩy mã, mỗi đêm hoặc trong một pipeline nơi không có ai theo dõi. Tại thời điểm đó, bạn muốn một lệnh duy nhất mà bạn có thể gõ, viết script và đưa vào CI.
Lệnh đó chính là Apidog CLI. Hướng dẫn này sẽ đưa bạn đi từng bước kiểm thử một REST API thực tế từ đầu đến cuối ngay trên terminal của bạn: cài đặt công cụ, nhập API, thiết lập môi trường, xây dựng kịch bản kiểm thử, chạy nó với các xác nhận, cung cấp dữ liệu và thu thập báo cáo. Mỗi lệnh và đầu ra dưới đây đều đến từ một lần chạy thực tế trên Apidog CLI phiên bản 2.2.2 đối với một API công cộng trực tiếp, vì vậy bạn có thể làm theo và nhận được kết quả tương tự.
Nếu bạn muốn phiên bản trực quan của cùng nền tảng, bạn có thể tải xuống Apidog và thiết kế các bài kiểm thử trong ứng dụng trước. Nhưng mọi thứ ở đây đều diễn ra trên dòng lệnh.
Những gì bạn sẽ xây dựng
Bạn sẽ kiểm thử restful-api.dev, một REST API công cộng miễn phí với các thao tác CRUD thực tế trên tài nguyên /objects. Đến cuối cùng, bạn sẽ có:
- Một dự án Apidog được tạo từ một tệp OpenAPI
- Một kịch bản kiểm thử ba bước bao gồm tạo một đối tượng, đọc lại nó và xóa nó, với các xác nhận ở mỗi bước
- Một lần chạy dựa trên dữ liệu, lặp lại một yêu cầu cho mỗi hàng dữ liệu kiểm thử
- Các báo cáo CLI, HTML, JSON và JUnit, cùng với một báo cáo đám mây có thể chia sẻ
Luồng này có thể mở rộng cho API của riêng bạn và là nền tảng để chạy các bài kiểm thử API trong CI/CD.
Trước khi bạn bắt đầu
Bạn cần Node.js 16 trở lên và một tài khoản Apidog. Nếu bạn đang so sánh các trình chạy trước, phiên bản ngắn gọn là Apidog CLI chạy các kịch bản kiểm thử đầy đủ và quản lý tài nguyên API dưới dạng mã, điều này làm cho nó khác biệt so với Newman và Postman CLI.
Bước 1: Cài đặt và đăng nhập
Cài đặt CLI toàn cục từ npm:
npm install -g apidog-cli@latest
Xác nhận đã cài đặt:
apidog --version
# 2.2.2
Bây giờ hãy xác thực. Lấy một token từ ứng dụng Apidog dưới avatar của bạn, Cài đặt tài khoản (Account Settings), API Access Token, sau đó chạy:
apidog login --with-token <YOUR_TOKEN>
Token được lưu vào ~/.apidog/config.toml, vì vậy bạn chỉ cần thực hiện việc này một lần cho mỗi máy. Kiểm tra bạn là ai:
Mỗi lệnh trả về JSON có cấu trúc với cờ success và các agentHints hữu ích, giúp dễ dàng viết script hoặc đưa đầu ra vào jq.
Bước 2: Tạo một dự án
Chọn nhóm để tạo dự án, sau đó tạo nó:
apidog team list
apidog project create --team 329562 --name "CLI Field Test"
Bạn sẽ nhận được ID dự án mới.
Lưu nó vào một biến shell để phần còn lại của hướng dẫn này có thể sao chép-dán:
PID=1314366 # thay thế bằng id dự án của bạn
apidog project get $PID
Bước 3: Nhập REST API của bạn
Bạn có thể tạo các điểm cuối theo cách thủ công, nhưng nhập một tệp OpenAPI sẽ nhanh hơn và phản ánh cách các dự án thực tế bắt đầu. Đây là một spec nhỏ mô tả các điểm cuối CRUD của /objects (lưu nó dưới dạng objects-api.openapi.json):
{
"openapi": "3.0.3",
"info": { "title": "Objects API", "version": "1.0.0" },
"servers": [{ "url": "https://api.restful-api.dev" }],
"paths": {
"/objects": {
"get": { "summary": "List objects" },
"post": { "summary": "Create object" }
},
"/objects/{id}": {
"get": { "summary": "Get object by id" },
"put": { "summary": "Update object" },
"delete": { "summary": "Delete object" }
}
}
}
Nhập nó:
apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5 (5 điểm cuối được tạo, 0 lỗi)
Trình nhập cũng đọc openapi, postman, har, insomnia, jmeter và nhiều định dạng khác. Liệt kê những gì đã được nhập:
apidog endpoint list --project $PID
# 37921721 get /objects
# 37921722 post /objects
# 37921723 get /objects/{id}
# 37921724 put /objects/{id}
# 37921725 delete /objects/{id}
Bước 4: Thiết lập môi trường
Môi trường chứa URL cơ sở và bất kỳ biến nào mà các bài kiểm thử của bạn sử dụng lại. Tạo một môi trường và lưu ID của nó:
apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917 # thay thế bằng id môi trường của bạn
Bạn sẽ truyền -e $ENV vào lệnh chạy sau này để bài kiểm thử biết nơi gửi yêu cầu.
Bước 5: Vượt qua cổng ghi tự động hóa
Đây là điều đầu tiên có thể khiến mọi người bối rối. Các kịch bản kiểm thử và dữ liệu kiểm thử là tài nguyên tự động hóa, và việc ghi chúng vào nhánh chính của bạn từ một công cụ bên ngoài bị chặn theo mặc định:
apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "Automation caller branch required" }
Đây là một rào cản bảo vệ, không phải là một lỗi. Bạn có hai cách để vượt qua nó:
- Bật quyền chỉnh sửa trực tiếp trong ứng dụng Apidog trên máy tính để bàn dưới Project Settings, Feature Settings, AI Feature Settings, External AI Edit Permissions.
- Làm việc trên một nhánh AI, điều này giúp các thay đổi tự động hóa được cô lập cho đến khi bạn chọn hợp nhất. Đường dẫn này hoàn toàn nằm trên dòng lệnh, vì vậy chúng ta sẽ sử dụng nó.
Tạo nhánh từ main:
apidog branch create --project $PID --type ai \
--name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"
Mẫu đặt tên ai/YYYYMMDD-from-<source>-<feature> là quy ước mà CLI mong đợi. Lưu ý rằng import, environment create và chỉnh sửa điểm cuối không bị chặn; chỉ có các tài nguyên tự động hóa mới bị chặn.
Bước 6: Xây dựng một kịch bản kiểm thử
Một kịch bản là một luồng các yêu cầu được sắp xếp với các xác nhận ở giữa chúng. Bạn tạo khung trước, sau đó thêm các bước. Tạo nó trên nhánh AI của bạn:
apidog test-scenario create --project $PID --branch "$BR" \
--name "Object CRUD lifecycle" \
--description "Create, read, then delete an object and assert each step" \
--folder-id 0 --priority 1
SID=1836498 # id kịch bản trả về
Các bước được thêm vào thông qua update bằng một tệp JSON. Quy tắc vàng với bất kỳ thao tác ghi JSON nào là phải xác thực trước khi gửi, để bạn không bao giờ đẩy một payload bị định dạng sai:
apidog cli-schema get test-scenario-update # xem cấu trúc chính xác
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "data file is valid"
Mỗi bước là một yêu cầu cộng với một script nhỏ xác nhận phản hồi và truyền dữ liệu cho các bước tiếp theo. Đây là cấu trúc của bước tạo, trong đó gửi một đối tượng mới và lưu id của nó cho các bước sau:
{
"type": "customHttp",
"name": "Create object",
"customHttpRequest": {
"path": "https://api.restful-api.dev/objects",
"method": "post",
"requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Field Test\",\"data\":{\"price\":42}}" },
"postProcessors": [{
"type": "customScript",
"data": "pm.test('create returns 200', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
"enable": true
}],
"projectId": 1314366
}
}
Các bước tiếp theo sử dụng lại {{objId}} trong URL để tìm nạp và sau đó xóa cùng một đối tượng. Áp dụng tệp ba bước đầy đủ:
apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "success": true
Bạn không cần phải tạo kịch bản dưới dạng JSON. Xây dựng chúng trực quan trong Apidog và chạy chúng từ CLI cũng hoàn toàn hợp lệ. Đường dẫn JSON quan trọng khi bạn muốn các bài kiểm thử của mình được kiểm soát phiên bản và xem xét như bất kỳ mã nào khác.
Bước 7: Chạy nó từ dòng lệnh
Đây là thành quả. Chạy kịch bản với bộ báo cáo CLI:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli
❏ Object CRUD lifecycle
↳ Create object POST .../objects [200 OK]
✓ create returns 200 ✓ response has an id ✓ name was echoed back
↳ Get the created object GET .../objects/ff80...3de [200 OK]
✓ get returns 200 ✓ id matches the created object ✓ price persisted in data
↳ Delete the object DELETE .../objects/ff80...3de [200 OK]
✓ delete returns 200
Http Requests 3 / 0 failed
Assertions 7 / 0 failed
Ba yêu cầu, bảy xác nhận, không có lỗi nào, và id được tạo đã truyền từ bước đầu tiên sang hai bước tiếp theo. Đó là một bài kiểm thử API hoàn chỉnh chạy mà không cần một cú nhấp chuột nào.
Muốn tệp thay vì đầu ra console? Yêu cầu một vài trình báo cáo cùng lúc và trỏ chúng đến một thư mục:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
-r cli,html,json,junit --out-dir ./reports --out-file "crud-report"
ls ./reports
# crud-report.html crud-report.json crud-report.xml
JUnit XML là thứ mà máy chủ CI của bạn đọc để hiển thị trạng thái pass/fail cho mỗi bản dựng. Báo cáo HTML là thứ bạn chia sẻ với đồng đội.
Bước 8: Chạy cùng một bài kiểm thử với nhiều đầu vào
Các bộ kiểm thử thực tế bao gồm nhiều trường hợp hơn. Các lần chạy dựa trên dữ liệu lặp lại một kịch bản một lần cho mỗi hàng dữ liệu, vì vậy bạn kiểm thử mười đầu vào mà không cần viết mười kịch bản. Đây là cùng một ý tưởng như kiểm thử API tham số hóa từ CSV và JSON.
Đặt các hàng của bạn vào một tệp:
[
{ "name": "Pixel 8 Pro", "price": 999 },
{ "name": "iPhone 15", "price": 899 },
{ "name": "Galaxy S24", "price": 799 }
]
Tham chiếu dữ liệu với -d, và để kịch bản đọc {{name}} và {{price}} từ mỗi hàng:
apidog run -t $DID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli
Iteration 1/3 … ✓ row created (200) ✓ name matches the data row
Iteration 2/3 … ✓ row created (200) ✓ name matches the data row
Iteration 3/3 … ✓ row created (200) ✓ name matches the data row
Iterations 3 / 0 failed Assertions 6 / 0 failed
Ba hàng đầu vào, ba lần lặp đầu ra. Thay thế tệp bằng CSV và không có gì thay đổi.
Bước 9: Thu thập báo cáo
Các lần chạy cục bộ ghi tệp. Để nhận một báo cáo mà cả nhóm của bạn có thể mở trong trình duyệt, hãy thêm --upload-report:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# Dữ liệu chạy Apidog CLI đã được tải lên đám mây thành công.
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398
Một lưu ý đáng biết: một báo cáo đám mây được gắn thẻ với nhánh mà nó đã chạy. Vì lần chạy này diễn ra trên nhánh AI của bạn, một lệnh apidog test-report list --project $PID đơn giản (nhắm mục tiêu main) sẽ không hiển thị nó. Thay vào đó, hãy tìm nạp nó bằng ID từ liên kết tải lên:
apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json
Bước 10: Xuất API của bạn dưới dạng tài liệu hoặc spec
CLI cũng đẩy dữ liệu ra ngoài. Xuất dự án dưới dạng tệp OpenAPI, Markdown hoặc tài liệu HTML:
apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html
Điều này rất tiện lợi để cam kết một spec mới trên mỗi thay đổi hoặc xuất bản tài liệu tĩnh từ một pipeline.
Bước 11: Tích hợp nó vào CI/CD
Mọi thứ bạn đã chạy thủ công trở thành ba dòng trong một pipeline. Cốt lõi là cài đặt, sau đó chạy với trình báo cáo JUnit để máy chủ CI có thể đọc kết quả:
- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports
Lưu token dưới dạng một bí mật và làm cho bản dựng thất bại khi một bài kiểm thử thất bại (CLI trả về mã thoát khác 0 khi có lỗi). Để có một quy trình làm việc đầy đủ, có thể sao chép-dán, xem hướng dẫn về chạy các bài kiểm thử Apidog CLI trong GitHub Actions, hoặc duyệt các công cụ tự động hóa kiểm thử API phù hợp với một pipeline.
Tổng kết
Bạn đã đi từ một terminal trống đến một bài kiểm thử API hoạt động, dựa trên dữ liệu với các báo cáo có thể chia sẻ, và bạn không hề rời khỏi dòng lệnh. Quy trình luôn giống nhau: nhập hoặc thiết kế API của bạn, tạo một môi trường, xây dựng một kịch bản với các xác nhận, sau đó chạy nó với apidog run. Khi lệnh đó hoạt động cục bộ, việc đưa nó vào CI chỉ là một thay đổi ba dòng.
Áp dụng các bước tương tự cho API của riêng bạn, cam kết các tệp kịch bản cùng với mã của bạn và các bài kiểm thử của bạn sẽ chạy ở bất cứ đâu có shell. Tải xuống Apidog để bắt đầu và giữ các phương án thay thế curl cho kiểm thử REST API tiện dụng cho các kiểm tra nhanh một lần mà CLI có thể quá mức cần thiết.