Bạn chạy các bài kiểm thử Apidog CLI trong Harness bằng cách thêm một giai đoạn CI với một bước Run duy nhất để cài đặt `apidog-cli`, thực thi `apidog run` và công bố kết quả JUnit. Lưu trữ mã thông báo truy cập Apidog của bạn dưới dạng bí mật Harness, tham chiếu nó bằng biểu thức `<+secrets.getValue("...")>` và trỏ một khối báo cáo JUnit vào đầu ra XML của CLI. Hướng dẫn này cung cấp cho bạn YAML pipeline có thể sao chép-dán cho cả Harness Cloud và một delegate tự lưu trữ.
Harness CI/CD là gì?
Harness CI là module tích hợp liên tục của nền tảng Harness. Nó xây dựng, kiểm thử và xác thực mã của bạn trên cơ sở hạ tầng xây dựng được quản lý hoặc tự lưu trữ, sau đó chuyển giao các thành phẩm cho Harness CD để triển khai.
Bạn định nghĩa mọi thứ dưới dạng YAML. Một pipeline chứa một hoặc nhiều giai đoạn. Mỗi giai đoạn có một loại, và một giai đoạn CI chạy trên cơ sở hạ tầng xây dựng. Bên trong giai đoạn, một khối thực thi chứa một danh sách các bước có thứ tự để chạy các lệnh của bạn.
Mô hình này áp dụng rõ ràng cho việc kiểm thử API. Bạn thêm một giai đoạn CI, đặt một bước chạy lệnh kiểm thử của bạn, và để Harness kiểm soát quá trình xây dựng dựa trên kết quả. Nếu các bài kiểm thử thất bại, bước đó sẽ thất bại và pipeline dừng lại.
Harness đọc JUnit XML để báo cáo kết quả kiểm thử. Vì Apidog CLI có thể xuất JUnit, bạn sẽ có một tab "Tests" gốc với số lần vượt qua và thất bại trên mỗi bản dựng. Không cần mã "glue".
Harness CI hoạt động như thế nào
Hệ thống phân cấp YAML rất nghiêm ngặt, vì vậy việc hiểu cấu trúc lồng nhau trước khi viết bất cứ điều gì là hữu ích. Một pipeline CI có cấu trúc từ trên xuống như sau:
- `pipeline` chứa siêu dữ liệu và danh sách `stages`.
- Mỗi `stage` có `type: CI` và một `spec`.
- `spec` của giai đoạn khai báo cơ sở hạ tầng xây dựng và một khối `execution`.
- `execution` chứa danh sách `steps`.
- Mỗi `step` có `type`, `name`, `identifier` và `spec` riêng.
Để chạy một lệnh shell, loại bước là `Run`. `spec` của bước Run chứa trường `shell` (Bash, Sh, PowerShell, Pwsh hoặc Python) và trường `command` chứa tập lệnh của bạn. Bạn viết các lệnh nhiều dòng bằng cách sử dụng dấu `|-` của YAML block scalar.
Bước Run duy nhất đó là tất cả những gì bạn cần để cài đặt và thực thi Apidog CLI. Mọi thứ khác trong hướng dẫn này là cấu hình xoay quanh bước đó.
Apidog CLI trong một phút
Apidog CLI là công cụ chạy dòng lệnh cho các kịch bản kiểm thử mà bạn xây dựng trực quan trong Apidog. Bạn thiết kế các bài kiểm thử trong ứng dụng, sau đó thực thi chúng không cần giao diện đồ họa (headless) trong bất kỳ pipeline nào, tương tự như cách Newman chạy các bộ sưu tập Postman. Nếu bạn muốn so sánh, hãy xem Apidog CLI vs Newman.
Bạn cài đặt nó từ npm và chạy một lệnh duy nhất:
npm install -g apidog-cli
apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -r cli,junit --out-dir ./apidog-reports
Một vài cờ quan trọng đối với CI. Cờ `--access-token` xác thực việc thực thi trên đám mây và không có dạng viết tắt. Cờ `-e` đặt môi trường và là bắt buộc. Cờ `-t` chọn một kịch bản kiểm thử theo ID. Cờ `-r` chọn các trình báo cáo, và `junit` là một trong các giá trị được hỗ trợ (`cli`, `html`, `json`, `junit`). Cờ `--out-dir` kiểm soát nơi các báo cáo được lưu trữ, mặc định là `./apidog-reports`.
Lựa chọn `-r cli,junit` đó là cầu nối đến Harness. CLI ghi JUnit XML vào thư mục đầu ra và Harness đọc nó trực tiếp. Để biết thêm về những gì CLI tạo ra, hãy xem hướng dẫn báo cáo kiểm thử Apidog CLI.
Lưu trữ mã thông báo truy cập Apidog của bạn dưới dạng bí mật Harness
Không bao giờ mã hóa cứng mã thông báo trong YAML. Trước tiên, hãy thêm nó vào trình quản lý bí mật Harness, sau đó tham chiếu nó.
Trong giao diện người dùng Harness, hãy vào cài đặt dự án (hoặc tổ chức/tài khoản) của bạn, mở Secrets, và tạo một bí mật Text mới. Đặt định danh là `apidog_token`. Định danh là thứ bạn tham chiếu trong YAML, và nó khác với tên hiển thị.
Bạn tham chiếu bí mật bằng biểu thức này:
<+secrets.getValue("apidog_token")>
Sử dụng định danh bên trong dấu ngoặc kép, không phải tên hiển thị. Đối với bí mật có phạm vi tổ chức (org-scoped), hãy thêm tiền tố `org.` như `<+secrets.getValue("org.apidog_token")>`. Đối với bí mật có phạm vi tài khoản (account-scoped), hãy sử dụng `account.` thay thế.
Đặt biểu thức trong dấu nháy đơn bên trong một lệnh shell. Mã thông báo có thể chứa ký tự `$`, và dấu nháy đơn ngăn shell mở rộng nó. Bạn có thể đọc thêm về thiết lập mã thông báo trong ghi chú xác thực Apidog CLI.
Pipeline Harness Cloud (điểm khởi đầu được khuyến nghị)
Harness Cloud cung cấp cho bạn các máy xây dựng được quản lý bởi Harness với Node.js và npm được cài đặt sẵn. Không có cơ sở hạ tầng nào phải bảo trì, và Linux hoạt động ngay lập tức. Đây là cách nhanh nhất để có một pipeline hoạt động.
Trên Harness Cloud, `spec` của giai đoạn sử dụng một khối `platform` và một khối `runtime` với `type: Cloud`. Bạn không cần chỉ định `image` trên bước Run ở đây, vì máy được quản lý đã có sẵn các công cụ.
pipeline:
name: Apidog API Tests
identifier: apidog_api_tests
projectIdentifier: YOUR_PROJECT
orgIdentifier: YOUR_ORG
stages:
- stage:
name: API Tests
identifier: api_tests
type: CI
spec:
cloneCodebase: false
platform:
os: Linux
arch: Amd64
runtime:
type: Cloud
spec: {}
execution:
steps:
- step:
type: Run
name: Run Apidog CLI Tests
identifier: run_apidog_cli_tests
spec:
shell: Sh
command: |-
npm install -g apidog-cli
apidog run \
--access-token '<+secrets.getValue("apidog_token")>' \
-t 605067 \
-e 1629989 \
-n 1 \
-r cli,junit \
--out-dir ./apidog-reports
reports:
type: JUnit
spec:
paths:
- apidog-reports/*.xml
Thay thế `605067` bằng ID kịch bản kiểm thử của bạn và `1629989` bằng ID môi trường của bạn. Cờ `-n 1` chạy một lần lặp. Đặt `cloneCodebase: false` vì các bài kiểm thử nằm trong đám mây của Apidog, nên pipeline không cần kho lưu trữ của bạn.
Công bố kết quả kiểm thử
Khối `reports` trên bước Run là thứ hiển thị kết quả trong Harness. Nó nhận một `type` là `JUnit` và một `spec` với một danh sách `paths` trỏ đến các tệp XML của bạn.
reports:
type: JUnit
spec:
paths:
- apidog-reports/*.xml
Harness chỉ phân tích cú pháp JUnit XML để báo cáo gốc. Sau khi xây dựng, bạn sẽ thấy một tab "Tests" với mỗi kịch bản, trạng thái và thời gian của nó. Glob `apidog-reports/*.xml` khớp với các tệp mà CLI đã ghi bằng `-r cli,junit` vào thư mục đầu ra mặc định.
Harness cũng cung cấp Test Intelligence, sử dụng một loại bước `Test` riêng biệt để chỉ chạy các bài kiểm thử bị ảnh hưởng bởi thay đổi mã. Tối ưu hóa đó nhắm mục tiêu vào các bài kiểm thử đơn vị cấp độ ngôn ngữ, không phải các kịch bản API không có giao diện đồ họa. Để nhập đầu ra Apidog CLI, bước Run thông thường với khối `reports` của JUnit là đường dẫn chính xác.
Nếu bạn thay đổi trình báo cáo, hãy giữ ít nhất `junit` trong danh sách `-r`. Nếu không có nó, CLI sẽ không ghi XML nào và tab "Tests" sẽ trống ngay cả khi bước đó thành công.
Giải pháp thay thế delegate tự lưu trữ
Sử dụng bản dựng được hỗ trợ bởi delegate khi bạn cần truy cập mạng riêng, một runtime tùy chỉnh hoặc cũ, hoặc bạn muốn tránh tín dụng xây dựng của Harness Cloud. Một delegate Kubernetes chạy mỗi giai đoạn như một pod.
Cấu trúc thay đổi theo hai cách. `spec` của giai đoạn sử dụng một khối `infrastructure` thay vì `platform` và `runtime`. Và trên cơ sở hạ tầng Kubernetes, mỗi bước Run phải khai báo `connectorRef` và một `image`, vì bước đó chạy bên trong một container mà bạn chỉ định.
spec:
cloneCodebase: false
infrastructure:
type: KubernetesDirect
spec:
connectorRef: YOUR_K8S_CONNECTOR
namespace: harness-ci
execution:
steps:
- step:
type: Run
name: Run Apidog CLI Tests
identifier: run_apidog_cli_tests
spec:
connectorRef: YOUR_DOCKER_CONNECTOR
image: node:20
shell: Sh
command: |-
npm install -g apidog-cli
apidog run \
--access-token '<+secrets.getValue("apidog_token")>' \
-t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
reports:
type: JUnit
spec:
paths:
- apidog-reports/*.xml
Dòng `image: node:20` cung cấp cho bạn Node.js và npm bên trong pod. Các giá trị `connectorRef` trỏ đến các kết nối Kubernetes và Docker đã đăng ký của bạn. Không kết hợp hai kiểu cơ sở hạ tầng trong một giai đoạn. Một giai đoạn là Harness Cloud (`platform` cộng với `runtime`) hoặc được hỗ trợ bởi delegate (`infrastructure`), không bao giờ cả hai.
Chọn Harness Cloud hay một delegate
Chọn dựa trên nơi API của bạn tồn tại và ai sở hữu các máy xây dựng.
| Yếu tố | Harness Cloud | Delegate tự lưu trữ |
|---|---|---|
| Cài đặt | Không cần hạ tầng, npm được cài đặt sẵn | Bạn quản lý cụm hoặc máy ảo |
| Phạm vi mạng | Các điểm cuối công cộng | Các điểm cuối riêng tư và nội bộ |
| Bước Run cần image | Không | Có, trên hạ tầng Kubernetes |
| Mô hình chi phí | Sử dụng tín dụng xây dựng | Máy tính của riêng bạn |
| Tốt nhất cho | API đám mây, khởi động nhanh | API nội bộ, runtime tùy chỉnh |
Bắt đầu với Harness Cloud nếu môi trường Apidog của bạn truy cập các điểm cuối công cộng. Chuyển sang delegate khi môi trường kiểm thử của bạn nằm sau VPN hoặc cần một runtime mà bạn kiểm soát. Bước Run và lệnh Apidog gần như giống hệt nhau giữa hai lựa chọn.
Chạy theo dữ liệu (Data-driven runs)
Bạn có thể cung cấp tệp CSV hoặc JSON vào quá trình chạy để kiểm thử tham số hóa. Cờ `-d` (tên dài `--iteration-data`) lấy đường dẫn tệp dữ liệu, và `-n` đặt số lần lặp.
apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -d ./data.csv -n 5 -r cli,junit --out-dir ./apidog-reports
Điều này chạy kịch bản một lần cho mỗi hàng dữ liệu. Trong một bước Harness Run, bạn sẽ `git clone` hoặc dàn dựng tệp dữ liệu trước, sau đó trỏ `-d` đến đường dẫn của nó. Để biết mẫu đầy đủ, hãy xem kiểm thử theo dữ liệu của Apidog CLI và hướng dẫn kiểm thử API tự động rộng hơn.
Tại sao nên thiết kế các bài kiểm thử trong Apidog trước
CLI chỉ chạy các kịch bản đã tồn tại trong dự án Apidog của bạn. Đó chính là điểm mấu chốt. Apidog là một nền tảng API tất cả trong một để thiết kế, gỡ lỗi, kiểm thử, mô phỏng và tài liệu hóa, vì vậy bạn xây dựng bộ kiểm thử của mình một lần và tái sử dụng nó ở mọi nơi.
Bạn thiết kế các bài kiểm thử bằng trình xây dựng trực quan, không cần viết script. Bạn chuỗi các yêu cầu, trích xuất giá trị từ phản hồi này sang phản hồi khác, và thêm các xác nhận thông qua giao diện người dùng. CLI sau đó thực thi chính xác bộ kiểm thử đó một cách không cần giao diện đồ họa trong Harness, vì vậy những gì bạn gỡ lỗi cục bộ chính là những gì chạy trong pipeline.
Bởi vì Apidog là nền tảng OpenAPI-native với hỗ trợ nhánh và không gian làm việc nhóm, các kỹ sư QA và nhà phát triển backend của bạn chia sẻ một nguồn thông tin đáng tin cậy duy nhất. Một kịch bản được chấp thuận trong một nhánh trở thành cùng một kịch bản mà lệnh `apidog run` của bạn thực thi. Đối với các mẫu pipeline rộng hơn, tài liệu giới thiệu về CI/CD là gì và hướng dẫn quy trình làm việc của GitHub Actions bao gồm cùng một CLI trong các hệ thống khác. Hướng dẫn Jenkins trong tích hợp kiểm thử Apidog với Jenkins sử dụng hình dạng lệnh giống hệt.
Tải xuống Apidog miễn phí để xây dựng kịch bản kiểm thử đầu tiên của bạn, sau đó kết nối nó vào Harness bằng YAML ở trên.
Các câu hỏi thường gặp
Harness CI/CD là gì?
Harness CI/CD là một nền tảng pipeline để xây dựng, kiểm thử và triển khai phần mềm. Bạn định nghĩa các pipeline dưới dạng YAML gồm các giai đoạn và bước. Một giai đoạn CI chạy trên cơ sở hạ tầng xây dựng, có thể là máy Cloud do Harness quản lý hoặc một delegate tự lưu trữ, và một giai đoạn CD xử lý việc triển khai.
Harness CI hoạt động như thế nào?
Một pipeline chứa danh sách các giai đoạn. Mỗi giai đoạn CI có một `spec` khai báo cơ sở hạ tầng xây dựng và một khối thực thi. Khối thực thi chạy một danh sách các bước có thứ tự. Một bước Run thực thi một lệnh shell, đó là nơi bạn cài đặt và chạy Apidog CLI.
Bạn lưu trữ và sử dụng bí mật trong Harness như thế nào?
Tạo một bí mật Text trong trình quản lý bí mật Harness và ghi lại định danh của nó. Tham chiếu nó trong YAML bằng `<+secrets.getValue("identifier")>`, sử dụng định danh thay vì tên hiển thị. Thêm tiền tố `org.` hoặc `account.` cho các phạm vi đó, và đặt biểu thức trong dấu nháy đơn bên trong các lệnh shell.
Bạn công bố kết quả kiểm thử trong Harness như thế nào?
Thêm một khối `reports` vào bước Run của bạn với `type: JUnit` và một danh sách `paths` trỏ đến các tệp XML của bạn. Harness phân tích cú pháp JUnit XML và hiển thị kết quả trên tab "Tests" của bản dựng. Apidog CLI xuất XML này khi bạn truyền `-r junit` hoặc `-r cli,junit`.
Harness CI có miễn phí không?
Harness cung cấp một gói miễn phí cho CI, và các bản dựng trên Harness Cloud tiêu thụ tín dụng xây dựng được bao gồm trong gói của bạn. Giá cả và giới hạn tín dụng thay đổi theo thời gian, vì vậy hãy kiểm tra trang giá của Harness hiện tại để biết số liệu chính xác trước khi bạn cam kết với một gói.
Tôi có thể chạy các bài kiểm thử Apidog CLI mà không cần sao chép kho lưu trữ của mình không?
Có. Đặt `cloneCodebase: false` trên giai đoạn khi các bài kiểm thử của bạn nằm trong đám mây của Apidog. CLI xác thực bằng mã thông báo truy cập của bạn và kéo kịch bản cũng như môi trường theo ID, vì vậy pipeline không bao giờ cần mã nguồn của bạn cho quá trình chạy kiểm thử.