Bạn đã sao chép một lệnh từ tab CI/CD, dán nó vào một pipeline, và nó đã hoạt động. Sau đó, một đồng nghiệp hỏi tại sao bản build vẫn báo thành công trong khi một bài kiểm tra rõ ràng đã thất bại, hoặc liệu bạn có thể trỏ cùng một lần chạy tới môi trường staging thay vì production, hoặc làm thế nào để nhận được một báo cáo mà bảng điều khiển CI của bạn thực sự sẽ phân tích cú pháp. Đột nhiên, một dòng lệnh không còn đủ nữa. Bạn cần biết mọi phần của nó hoạt động như thế nào.
apidog run là lệnh duy nhất cốt lõi của trình chạy dòng lệnh Apidog. Nó thực thi các kịch bản kiểm thử API bạn đã xây dựng trong Apidog một cách không có giao diện người dùng, từ một terminal, không có GUI và không cần người dùng nhấp chuột. Mọi thứ mà trình chạy có thể làm, nó đều thực hiện thông qua các cờ (flags) trên lệnh này: kịch bản nào để chạy, môi trường nào để truy cập, lặp lại bao nhiêu lần, báo cáo nào để xuất, và điều gì được tính là một lỗi. Nắm vững bề mặt cờ một lần và bạn sẽ ngừng việc sao chép-dán một cách mù quáng.
apidog run là gì
Apidog CLI được đóng gói dưới dạng một gói npm có tên apidog-cli. Bạn cài đặt nó một lần và bạn sẽ có một tệp thực thi duy nhất, apidog, với lệnh con chính là run. Lệnh con đó nhận một trong các kịch bản kiểm thử Apidog của bạn và chạy nó theo cách mà ứng dụng desktop sẽ làm, sau đó báo cáo lại với mã thoát và bất kỳ tệp báo cáo nào bạn yêu cầu.
Cài đặt toàn cục:
npm install -g apidog-cli
Xác nhận đã cài đặt:
apidog -v
Điều cần hiểu trước khi tìm hiểu về các cờ là apidog run hoạt động trên cái gì. Nó không định nghĩa định dạng kiểm thử riêng của mình. Kiểm thử là kịch bản bạn đã tạo trong ứng dụng Apidog: các yêu cầu được xâu chuỗi, các xác nhận, các giá trị được lấy từ một phản hồi sang phản hồi tiếp theo, lặp lại dựa trên dữ liệu tùy chọn. CLI truy cập vào dự án của bạn, tìm kịch bản theo ID và chạy nó. Vì vậy, hầu hết các cờ đều để cho trình chạy biết phải tìm nạp gì và hành xử như thế nào khi nó chạy, chứ không phải để viết các bài kiểm thử trực tiếp.
Một lệnh thực tế tối thiểu trông như thế này:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
Lệnh này có nghĩa là: xác thực bằng token này, chạy kịch bản kiểm thử 605067, chống lại môi trường 1629989, một lần, và tạo báo cáo HTML cộng với đầu ra terminal dễ đọc. Mỗi cờ trong dòng đó đều được giải thích bên dưới, cùng với những cờ mà lệnh đó bỏ qua.
Tổng quan toàn bộ các tùy chọn
Dưới đây là bộ tùy chọn đầy đủ được nhóm theo chức năng. Hãy sử dụng nó như một bảng tra cứu; các phần sau đó sẽ giải thích những tùy chọn cần nhiều hơn một câu.
| Nhóm | Cờ (Flag) | Đối số (Argument) | Điều khiển gì |
|---|---|---|---|
| Chọn | -t, --test-scenario |
<testScenarioId> |
Chạy một kịch bản theo ID |
| Chọn | -f, --test-scenario-folder |
<folderId> |
Chạy mọi kịch bản trong một thư mục |
| Chọn | --test-suite |
<testSuiteId> |
Chạy một bộ kiểm thử theo ID |
| Chọn | --project |
<projectId> |
Dự án mà kịch bản thuộc về |
| Chọn | --branch |
<branchName> |
Chạy đối với một nhánh (mặc định là main) |
| Xác thực | --access-token |
<accessToken> |
Xác thực lần chạy; bắt buộc khi online |
| Môi trường | -e, --environment |
<environmentId> |
Môi trường để nhắm mục tiêu |
| Lặp lại | -n, --iteration-count |
<n> |
Chạy kịch bản n lần |
| Lặp lại | -d, --iteration-data |
<path> |
Thực hiện các lần lặp từ tệp JSON hoặc CSV |
| Lặp lại | --variables |
<path> |
Tải biến từ tệp cục bộ |
| Lặp lại | --global-var |
<value> |
Đặt một biến toàn cục trực tiếp, key=value |
| Lặp lại | --env-var |
<value> |
Ghi đè một biến môi trường trực tiếp, key=value |
| Báo cáo | -r, --reporters |
[reporters] |
Định dạng báo cáo: cli, html, json, junit |
| Báo cáo | --out-dir |
<outDir> |
Nơi lưu báo cáo |
| Báo cáo | --out-file |
<outFile> |
Tên tệp báo cáo, với các chỗ giữ chỗ tên |
| Báo cáo | --out-json-failures-separated |
<value> |
Ghi các lỗi vào một tệp JSON riêng biệt |
| Báo cáo | --upload-report |
[value] |
Tải lên tổng quan báo cáo lên đám mây Apidog |
| Lỗi | --on-error |
<behavior> |
ignore (bỏ qua), continue (tiếp tục), hoặc end (kết thúc) khi gặp lỗi |
| Lỗi | --ignore-redirects |
Không theo dõi chuyển hướng HTTP | |
| Lỗi | --delay-request |
[n] |
Chờ n ms giữa các yêu cầu |
| Lỗi | --timeout-request |
[n] |
Thời gian chờ cho mỗi yêu cầu tính bằng ms |
| Lỗi | --timeout-script |
[n] |
Thời gian chờ thực thi script tính bằng ms |
| TLS | -k, --insecure |
Tắt xác minh chứng chỉ SSL | |
| TLS | --ssl-client-cert |
<path> |
Chứng chỉ máy khách (PEM) |
| TLS | --ssl-client-key |
<path> |
Khóa riêng tư cho chứng chỉ máy khách |
| TLS | --ssl-client-passphrase |
<passphrase> |
Mật khẩu cho chứng chỉ máy khách |
| TLS | --ssl-client-cert-list |
<path> |
Cấu hình ánh xạ chứng chỉ tới các máy chủ |
| TLS | --ssl-extra-ca-certs |
<path> |
Các chứng chỉ CA đáng tin cậy bổ sung |
| Đầu ra | --verbose |
In chi tiết đầy đủ yêu cầu và phản hồi | |
| Đầu ra | --silent |
Ngừng xuất console | |
| Đầu ra | --color |
<value> |
Buộc bật hoặc tắt đầu ra màu |
| Đầu ra | --external-program-path |
<path> |
Tệp chương trình bên ngoài cho logic tùy chỉnh |
| Đầu ra | --database-connection |
<path> |
Cấu hình cơ sở dữ liệu cho các bước truy vấn DB |
| Đầu ra | --preferred-http-version |
<version> |
Phiên bản giao thức HTTP ưu tiên |
| Đầu ra | -b, --bigint |
Bật BigInt cho các giá trị số lớn | |
| Đầu ra | --lang |
<language> |
Ngôn ngữ CLI |
| Đầu ra | -h, --help |
In trợ giúp |
Tên cờ và giá trị mặc định có thể thay đổi giữa các bản phát hành CLI. Khi nghi ngờ, trình chạy là nguồn đáng tin cậy nhất: hãy chạy apidog run --help trên phiên bản bạn đã cài đặt và tin tưởng vào thông tin đó hơn bất kỳ bài viết nào, kể cả bài này.
Chọn cái gì để chạy
Ba cờ quyết định phạm vi của một lần chạy, và bạn chọn chính xác một trong số chúng cho mỗi lệnh.
-t, --test-scenario <id> chạy một kịch bản duy nhất. Đây là trường hợp thông thường hàng ngày: một bài kiểm thử khói tập trung, một kịch bản hồi quy, một thứ bạn muốn chặn trên một pull request.
-f, --test-scenario-folder <id> chạy mọi kịch bản bên trong một thư mục. Hãy sử dụng cờ này khi bạn đã tổ chức một khu vực tính năng vào một thư mục và muốn toàn bộ nhóm được chạy như một công việc, giống như một lượt quét hồi quy hàng đêm.
--test-suite <id> chạy một bộ kiểm thử được chọn lọc, là một tập hợp các kịch bản bạn đã tập hợp để chạy cùng nhau như một đơn vị logic. Một bộ kiểm thử là công cụ phù hợp khi các kịch bản bạn muốn không nằm trong cùng một thư mục nhưng vẫn thuộc cùng một lượt kiểm thử.
Hai bộ chọn nữa tinh chỉnh nơi trình chạy tìm kiếm. --project <id> đặt tên dự án mà kịch bản nằm trong, hữu ích khi token của bạn có quyền truy cập vào nhiều dự án. --branch <name> chạy kịch bản như nó tồn tại trên một nhánh cụ thể thay vì main, cho phép bạn xác thực các thay đổi kiểm thử trên một nhánh tính năng trước khi chúng được hợp nhất.
# một kịch bản
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
# toàn bộ thư mục
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit
# một bộ kiểm thử được chọn lọc
apidog run --access-token $APIDOG_ACCESS_TOKEN --test-suite 40231 -r junit
Xác thực lần chạy
--access-token <token> là cờ duy nhất mà mọi lần chạy trực tuyến cần. Nó chứng minh rằng lần chạy được phép tìm nạp và thực thi kịch bản của bạn. Bạn tạo token bên trong tab CI/CD của một kịch bản kiểm thử trong Apidog, nơi ứng dụng cũng xây dựng lệnh apidog run đầy đủ cho bạn với ID kịch bản và ID môi trường đã được điền sẵn.
Hãy coi token như một mật khẩu. Đừng dán nó vào một tệp pipeline đã cam kết hoặc một script được chia sẻ. Hãy lưu trữ nó dưới dạng một bí mật trong hệ thống CI của bạn và truyền nó qua một biến môi trường, đó là lý do tại sao mọi ví dụ ở đây đều tham chiếu đến $APIDOG_ACCESS_TOKEN thay vì một chuỗi ký tự. Nếu một token bị rò rỉ, hãy tạo lại nó từ cùng tab CI/CD đó và token cũ sẽ ngừng hoạt động.
Nhắm mục tiêu môi trường và lặp lại
Cờ môi trường là thứ cho phép một kịch bản phục vụ nhiều mục đích. -e, --environment <id> trỏ lần chạy đến một môi trường cụ thể, vì vậy cùng một kịch bản có thể kiểm tra staging trong một cổng pull-request và production trong một bài kiểm thử khói sau triển khai mà bạn không cần phải sao chép bất cứ thứ gì. Nếu bạn quản lý các giá trị trên các môi trường, hướng dẫn về quản lý môi trường và bí mật cho các máy khách API sẽ trình bày cách các giá trị đó được luân chuyển.
-n, --iteration-count <n> chạy kịch bản n lần liên tiếp. Hữu ích cho việc kiểm tra độ ổn định nhanh chóng hoặc để lặp lại một luồng đáng lẽ phải có tính chất idempotent.
-d, --iteration-data <path> là cờ điều khiển theo dữ liệu. Trỏ nó đến một tệp JSON hoặc CSV và trình chạy sẽ thực thi kịch bản một lần cho mỗi hàng, coi mỗi hàng là một lượt riêng với các giá trị đầu vào riêng của nó. Đó là cách bạn chạy một kịch bản đăng nhập trên năm mươi tài khoản, hoặc một luồng tạo đơn hàng trên một bảng các payload. Mô hình sâu hơn nằm trong kiểm thử API điều khiển bằng dữ liệu với CSV và JSON.
Ba cờ chèn giá trị mà không cần chỉnh sửa kịch bản. --variables <path> tải các biến từ một tệp cục bộ. --global-var key=value đặt một biến toàn cục trực tiếp. --env-var key=value ghi đè một biến môi trường duy nhất chỉ cho lần chạy này. Những điều này rất tiện lợi trong CI khi một giá trị (URL cơ sở, cờ tính năng) khác nhau cho mỗi pipeline và bạn không muốn có một môi trường riêng cho mỗi cái. Nếu biến trong Apidog là mới đối với bạn, làm chủ các biến trong Apidog sẽ giải thích các phạm vi.
# chạy một kịch bản 50 lần trên một tệp CSV đầu vào
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r junit
# ghi đè một biến môi trường chỉ cho lần chạy này
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 --env-var baseUrl=https://staging.internal -r cli
Reporters: mọi định dạng đầu ra mà apidog run có thể tạo ra
Đây là nhóm mà mọi người tìm kiếm nhiều nhất, vì vậy đây là mỗi reporter và mục đích của nó. Bạn chọn chúng bằng -r, --reporters và bạn có thể truyền nhiều cái cùng lúc, phân tách bằng dấu phẩy. Mặc định là cli.
cli in một bản tóm tắt dễ đọc ra terminal. Đây là thứ mà một người quét qua trong nhật ký build để xem số lượng pass/fail và các xác nhận nào bị lỗi. Hãy giữ nó bật ngay cả bên cạnh các định dạng máy để nhật ký vẫn hữu ích.
html viết một báo cáo HTML độc lập. Lưu trữ nó như một artifcat build và mở nó trong trình duyệt để xem toàn bộ lần chạy với chi tiết yêu cầu và phản hồi. Đây là định dạng bạn gửi cho người không theo dõi pipeline.
junit xuất XML theo định dạng JUnit tiêu chuẩn. Hầu hết mọi bảng điều khiển CI đều biết cách phân tích cú pháp JUnit XML thành một cây pass/fail, hiển thị lỗi trong widget yêu cầu hợp nhất và theo dõi kết quả theo thời gian. Nếu bạn chỉ chọn một định dạng máy cho CI, hãy chọn định dạng này.
json tạo ra kết quả cấu trúc thô. Hãy sử dụng nó khi bạn muốn xử lý hậu kỳ kết quả: cấp nó cho một script, đẩy các số liệu đến đâu đó, hoặc xây dựng một bản tóm tắt tùy chỉnh.
Một sự kết hợp CI phổ biến là HTML cho con người và JUnit cho bảng điều khiển:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./apidog-reports
Các cờ báo cáo còn lại kiểm soát nơi đầu ra được lưu và những gì bổ sung nó bao gồm:
--out-dir <dir>đặt thư mục mà báo cáo được ghi vào. Mặc định là./apidog-reports.--out-file <name>đặt tên tệp báo cáo và chấp nhận các chỗ giữ chỗ{FOLDER_NAME},{SCENARIO_NAME}, và{GENERATE_TIME}, vì vậy bạn có thể đóng dấu các tệp bằng tên kịch bản và dấu thời gian thay vì ghi đè một tệp mỗi lần chạy.--out-json-failures-separated <value>chia các lỗi thành tệp JSON riêng biệt, giúp dễ đọc sự khác biệt chỉ của các lỗi.--upload-report [value]tải lên tổng quan báo cáo lên đám mây Apidog để lần chạy hiển thị trong lịch sử dự án của bạn cùng với các tệp cục bộ.
Kiểm soát lỗi: xử lý lỗi và mã thoát
Một trình chạy chỉ hữu ích trong một pipeline nếu nó báo cho pipeline biết liệu các kiểm thử đã vượt qua hay chưa. apidog run thực hiện điều này theo cách mà các công cụ dòng lệnh hoạt động tốt thường làm: nó thoát với mã 0 khi mọi xác nhận vượt qua và một mã khác 0 khi có bất cứ điều gì thất bại. Hành vi duy nhất đó là toàn bộ cổng chất lượng. CI đọc mã thoát, đánh dấu bước thất bại và chặn việc hợp nhất hoặc triển khai. Bạn không cấu hình một cổng; mã thoát chính là cổng.
--on-error <behavior> định hình điều gì xảy ra khi một bước thất bại giữa chừng kịch bản, và nó có ba giá trị:
enddừng lần chạy tại bước thất bại đầu tiên. Sử dụng nó cho một bài kiểm thử khói thất bại nhanh chóng khi bạn muốn phản hồi ngay lập tức khi có gì đó bị hỏng.continuechạy mọi bước còn lại để bạn thu thập tất cả các lỗi trong một báo cáo. Sử dụng nó cho một lượt quét hồi quy khi xem tất cả các lỗi cùng một lúc giúp tiết kiệm thời gian.ignorecho phép lần chạy tiếp tục qua một bước được biết là không ổn định mà không coi đó là lỗi nghiêm trọng. Hãy sử dụng nó một cách tiết kiệm; một bước bị bỏ qua không nên che giấu một lỗi hồi quy thực sự.
Dù bằng cách nào, nếu bất kỳ xác nhận nào thất bại, lần chạy vẫn kết thúc với mã khác 0, vì vậy cổng vẫn giữ vững bất kể bạn chọn hành vi nào. Một điều âm thầm làm hỏng cổng: bao bọc lệnh trong một cái gì đó nuốt chửng mã thoát của nó, như thêm || true trong một shell. Đừng làm vậy. Mã thoát khác 0 mới là điểm mấu chốt.
Bốn cờ điều chỉnh hành vi yêu cầu trong quá trình chạy:
--ignore-redirectsngăn trình chạy tự động theo dõi chuyển hướng HTTP, vì vậy bạn có thể xác nhận trên chính phản hồi chuyển hướng.--delay-request [n]chờnmili giây giữa các yêu cầu, điều này giúp chống lại giới hạn tốc độ hoặc các điểm cuối nhạy cảm với tải.--timeout-request [n]giới hạn thời gian một yêu cầu duy nhất có thể mất, tính bằng mili giây.--timeout-script [n]giới hạn thời gian một script trước hoặc sau yêu cầu có thể chạy, tính bằng mili giây.
# kiểm thử khói: dừng lại ở lỗi đầu tiên
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --on-error end
# hồi quy: chạy mọi thứ, thu thập tất cả các lỗi
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports
TLS và chứng chỉ
Khi bạn kiểm thử các điểm cuối phía sau TLS tương hỗ hoặc một cơ quan chứng nhận nội bộ, nhóm này là cách bạn thực hiện kết nối.
-k, --insecure hoàn toàn vô hiệu hóa xác minh chứng chỉ SSL. Chỉ sử dụng nó đối với một máy chủ nội bộ đáng tin cậy với chứng chỉ tự ký; không bao giờ trỏ nó đến bất kỳ thứ gì công khai, vì nó tắt kiểm tra bảo vệ kết nối.
Để có TLS tương hỗ đúng cách, hãy cung cấp thông tin xác thực máy khách: --ssl-client-cert <path> cho chứng chỉ PEM, --ssl-client-key <path> cho khóa riêng tư của nó, và --ssl-client-passphrase <passphrase> nếu khóa được mã hóa. Khi các máy chủ khác nhau cần các chứng chỉ khác nhau, --ssl-client-cert-list <path> trỏ đến một tệp cấu hình ánh xạ chúng. Và --ssl-extra-ca-certs <path> thêm các chứng chỉ CA đáng tin cậy, đây là cách khắc phục sạch sẽ cho một chuỗi CA nội bộ mà trình chạy sẽ không nhận ra, tốt hơn là sử dụng -k.
Đầu ra và chẩn đoán
Nhóm cuối cùng kiểm soát những gì trình chạy in ra và một vài chi tiết thực thi.
--verbose in đầy đủ yêu cầu và phản hồi cho mọi bước. Đây là bước đầu tiên của bạn khi một kịch bản vượt qua cục bộ nhưng thất bại trong CI: nó hiển thị chính xác các byte mà trình chạy đã gửi và nhận được, vì vậy bạn có thể so sánh với những gì bạn gửi bằng tay. --silent làm điều ngược lại, ngăn chặn đầu ra console cho các công việc đã lên lịch gây ồn ào mà bạn chỉ quan tâm đến mã thoát và báo cáo đã lưu. --color <value> buộc bật hoặc tắt đầu ra màu, hữu ích khi trình xem nhật ký CI làm hỏng các mã ANSI.
Phần còn lại dành cho các tính năng kịch bản cụ thể:
--external-program-path <path>trỏ đến một tệp các chương trình bên ngoài cho logic tùy chỉnh mà một kịch bản gọi ra.--database-connection <path>cung cấp cấu hình cơ sở dữ liệu cho các kịch bản có các bước truy vấn cơ sở dữ liệu trực tiếp.--preferred-http-version <version>đặt phiên bản giao thức HTTP mà trình chạy ưu tiên.-b, --bigintbật xử lý BigInt để các giá trị số lớn không bị mất độ chính xác.--lang <language>đặt ngôn ngữ hiển thị của CLI.-h, --helpin văn bản trợ giúp, là danh sách có thẩm quyền cho phiên bản đã cài đặt của bạn.
Ghép nối lại: các lệnh bạn thực sự sẽ chạy
Kiểm thử khói đối với production ngay sau khi triển khai, thất bại nhanh chóng:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e $PROD_ENV_ID -r cli --on-error end
Hồi quy đầy đủ hàng đêm trên một thư mục, mọi lỗi trong một báo cáo HTML và JUnit:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports
Chạy điều khiển bằng dữ liệu trên một tệp CSV, đầu ra dễ đọc bằng máy cho CI:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-cases.csv -r junit
Xác thực các thay đổi kiểm thử trên một nhánh tính năng trước khi chúng được hợp nhất:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
Gỡ lỗi một lỗi chỉ có trong CI bằng cách xuất chi tiết kết nối:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --verbose
Nếu bạn đang chạy CLI trên một trình chạy CI tạm thời và không muốn cài đặt toàn cục, hãy thay thế việc cài đặt bằng npx:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit
Điều đó bao gồm cùng một bề mặt. Sự lựa chọn giữa cài đặt toàn cục và npx là về sự sạch sẽ của trình chạy, chứ không phải khả năng. Để thiết lập kịch bản mà CLI chạy, Tải xuống Apidog, xây dựng một kịch bản trong ứng dụng, sau đó sao chép lệnh đã tạo từ tab CI/CD của nó và tham số hóa token.\