Để chạy các bài kiểm tra API Apidog CLI trong CircleCI, hãy thêm tệp .circleci/config.yml sử dụng bộ thực thi Docker cimg/node, cài đặt apidog-cli bằng npm và chạy apidog run với mã thông báo truy cập, ID kịch bản kiểm tra và ID môi trường của bạn. Lưu trữ mã thông báo và các ID này dưới dạng biến môi trường của CircleCI, sau đó xuất các báo cáo JUnit và HTML bằng store_test_results và store_artifacts. Hướng dẫn này sẽ trình bày từng phần để bạn có thể sao chép, dán và triển khai.
Bài viết này nói về việc chạy các bài kiểm tra, không phải chọn một nền tảng CI. Nếu bạn vẫn đang cân nhắc giữa các công cụ, so sánh CircleCI và Jenkins sẽ giải quyết vấn đề đó. Ở đây chúng tôi giả định bạn đã chọn CircleCI và muốn bộ API của mình chạy trên mỗi lần đẩy.
CircleCI là gì và cách nó hoạt động
CircleCI là một dịch vụ tích hợp và triển khai liên tục dựa trên đám mây. Nó theo dõi kho lưu trữ Git của bạn, và khi bạn đẩy một commit, nó sẽ chạy các bước xây dựng, kiểm thử và triển khai mà bạn đã định nghĩa. Bạn mô tả các bước đó trong một tệp YAML duy nhất, vì vậy pipeline của bạn nằm trong hệ thống kiểm soát phiên bản cùng với mã của bạn.
Mọi thứ bắt đầu với .circleci/config.yml ở thư mục gốc của repo của bạn. CircleCI đọc tệp này trên mỗi lần đẩy và biến nó thành một pipeline. Định dạng cấu hình hiện tại là phiên bản 2.1, bổ sung các khối xây dựng có thể tái sử dụng như orbs, commands và parameters trên nền tảng của engine 2.0 cơ bản.
Một cấu hình CircleCI có ba khái niệm cốt lõi:
- Jobs (Công việc) là các đơn vị công việc. Mỗi job chạy một loạt steps (bước), chẳng hạn như kiểm tra mã nguồn, cài đặt các phụ thuộc hoặc chạy một lệnh kiểm thử.
- Executors (Bộ thực thi) định nghĩa nơi một job chạy. Một bộ thực thi Docker chạy các bước của bạn bên trong một hình ảnh container mà bạn chọn, như
cimg/nodecho các dự án Node.js. - Workflows (Quy trình làm việc) điều phối các job. Một workflow quyết định job nào chạy, theo thứ tự nào, và liệu chúng có chạy song song hay tuần tự.
Sự phân tách đó rất quan trọng đối với việc kiểm thử API. Bạn định nghĩa một job cài đặt Apidog CLI và chạy các kịch bản của mình, sau đó là một workflow kích hoạt nó trên các nhánh mà bạn quan tâm.
Tại sao nên chạy kiểm thử API trong CircleCI
Chạy bộ API của bạn trong CI sẽ phát hiện các lỗi vi phạm hợp đồng trước khi chúng đến môi trường sản xuất. Một thay đổi lược đồ, một trường bị đổi tên hoặc một luồng xác thực bị hỏng sẽ hiển thị dưới dạng một bản dựng lỗi thay vì một phiếu hỗ trợ.
Apidog CLI được xây dựng chính xác cho mục đích này. Bạn thiết kế và gỡ lỗi một kịch bản kiểm thử trong ứng dụng Apidog, sau đó chạy kịch bản đó không giao diện trong CI chỉ bằng một lệnh. Không cần viết lại các xác nhận trong mã và không cần một bộ kiểm thử riêng biệt để duy trì.
Nếu bạn muốn có cái nhìn tổng quát hơn về cách các kiểm tra tự động phù hợp với một pipeline, hướng dẫn 12 thực tiễn tốt nhất CI/CD cho kiểm thử API là một tài liệu bổ sung tốt.
Điều kiện tiên quyết
Trước khi bạn viết cấu hình, hãy chuẩn bị những điều sau trong ứng dụng Apidog:
- Một access token (mã thông báo truy cập). Tạo nó trong phần cài đặt tài khoản Apidog của bạn. Điều này sẽ xác thực CLI trong các môi trường không giao diện. Hướng dẫn xác thực Apidog CLI trình bày chi tiết việc tạo mã thông báo và xử lý bí mật CI.
- Một test scenario ID (ID kịch bản kiểm thử). Mở kịch bản kiểm thử bạn muốn chạy và sao chép ID của nó từ URL hoặc cài đặt kịch bản.
- Một environment ID (ID môi trường). Điều này cho CLI biết URL cơ sở và các biến nào sẽ sử dụng, chẳng hạn như staging hoặc production.
Bạn cũng sẽ cần một tài khoản CircleCI được kết nối với nhà cung cấp Git của bạn, với dự án đã được bật trong bảng điều khiển CircleCI.
Lưu trữ bí mật dưới dạng biến môi trường
Không bao giờ mã hóa cứng mã thông báo truy cập của bạn trong config.yml. Tệp này được commit vào Git, vì vậy một mã thông báo ở đó sẽ là một mã thông báo bị rò rỉ.
CircleCI cung cấp cho bạn hai tùy chọn an toàn:
- Biến môi trường dự án. Trong giao diện người dùng CircleCI, mở Cài đặt Dự án, sau đó Biến Môi trường, và thêm từng giá trị. Chúng được mã hóa và hiển thị cho các job dưới dạng
$VARS. - Ngữ cảnh (Contexts). Ngữ cảnh là một nhóm các biến môi trường được đặt tên được chia sẻ giữa các dự án. Bạn tạo nó trong Cài đặt Tổ chức, sau đó Ngữ cảnh, và tham chiếu nó từ một workflow. Ngữ cảnh hữu ích khi nhiều repo chia sẻ cùng một mã thông báo Apidog.
Đối với hướng dẫn này, hãy thêm ba biến: APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID và APIDOG_ENVIRONMENT_ID. CLI sẽ đọc chúng khi chạy và không có gì nhạy cảm nằm trong repo của bạn.
Tệp config.yml đầy đủ
Đây là một cấu hình hoàn chỉnh, chỉ cần sao chép và dán. Đặt nó vào .circleci/config.yml, đặt ba biến môi trường của bạn và đẩy lên.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run Apidog API tests
command: |
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
workflows:
test-api:
jobs:
- api-tests
Hãy cùng phân tích từng phần xem chúng làm gì.
Bộ thực thi
docker:
- image: cimg/node:20.11
cimg/node là hình ảnh tiện lợi của CircleCI dành cho Node.js. Nó được cài đặt sẵn Node, npm và các công cụ xây dựng phổ biến, vì vậy npm install -g apidog-cli hoạt động mà không cần thiết lập thêm. Thẻ :20.11 gắn một phiên bản Node; hãy gắn vào phiên bản mà nhóm của bạn đã chuẩn hóa.
Các bước
checkout kéo kho lưu trữ của bạn vào thư mục làm việc của job. Bước run đầu tiên cài đặt CLI toàn cục. Bước run thứ hai thực thi các bài kiểm thử của bạn.
Hãy xem kỹ lệnh kiểm thử:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
Mỗi cờ thực hiện một công việc:
--access-tokenxác thực lần chạy. Nó không có dạng ngắn gọn.-tchọn kịch bản kiểm thử theo ID.-echọn môi trường. Cờ này là bắt buộc; CLI cần biết URL cơ sở và các biến nào sẽ sử dụng.-rđặt các trình báo cáo. Ở đây bạn yêu cầu ba:cliin kết quả trực tiếp vào nhật ký xây dựng,junitghi XML dễ đọc bằng máy vàhtmlghi một báo cáo có thể duyệt.--out-dircho CLI biết nơi ghi các tệp báo cáo.
Xuất bản các báo cáo
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
store_test_results chỉ CircleCI đến tệp JUnit XML trong ./reports. CircleCI phân tích nó và hiển thị tab Tests trên bản dựng, vì vậy các lỗi được liệt kê theo tên với dữ liệu thời gian. Đây là điều biến một bức tường văn bản nhật ký thành một chế độ xem đạt/không đạt có cấu trúc.
store_artifacts tải thư mục tương tự lên dưới dạng các tệp có thể tải xuống, bao gồm cả báo cáo HTML. Sau khi một bản dựng hoàn tất, bạn mở tab Artifacts và xem báo cáo được hiển thị trong trình duyệt của mình. Hướng dẫn báo cáo kiểm thử Apidog CLI giải thích các định dạng CLI, HTML và JSON chi tiết hơn.
Quy trình làm việc
workflows:
test-api:
jobs:
- api-tests
Quy trình làm việc này chạy job api-tests trên mỗi lần đẩy. Bạn có thể thêm các bộ lọc để hạn chế nó chỉ với một số nhánh nhất định, hoặc thêm các job khác chạy trước hoặc sau nó. Đối với một job kiểm thử đơn lẻ, khối tối thiểu này là tất cả những gì bạn cần.
Chỉ chạy kiểm thử trên nhánh chính
Bạn có thể không muốn chạy API đầy đủ trên mọi nhánh tính năng. Thêm một bộ lọc nhánh vào quy trình làm việc:
workflows:
test-api:
jobs:
- api-tests:
filters:
branches:
only:
- main
- develop
Bây giờ job chỉ chạy trên các lần đẩy tới main và develop. Các nhánh khác sẽ bỏ qua nó, điều này giúp tập trung thời gian xây dựng của bạn vào các nhánh được triển khai.
Sử dụng Ngữ cảnh thay vì biến dự án
Nếu nhiều kho lưu trữ chia sẻ một mã thông báo Apidog, Ngữ cảnh sẽ giữ nó ở một nơi. Tạo Ngữ cảnh trong Cài đặt Tổ chức, thêm các biến của bạn vào đó, sau đó tham chiếu nó:
workflows:
test-api:
jobs:
- api-tests:
context:
- apidog-secrets
Job bây giờ sẽ đọc APIDOG_ACCESS_TOKEN và phần còn lại từ Ngữ cảnh apidog-secrets. Xoay mã thông báo một lần, và mọi dự án sẽ nhận được giá trị mới.
Các lần chạy dựa trên dữ liệu và các tùy chọn khác
CLI có nhiều cờ hơn những gì hướng dẫn này sử dụng. Có hai cờ đáng biết đối với CI.
Bạn có thể lặp lại một kịch bản trên các hàng dữ liệu kiểm thử bằng -d và -n:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-d ./data/users.csv \
-r cli,junit \
--out-dir ./reports
Cờ -d nhận đường dẫn tệp CSV hoặc JSON, hoặc một ID bộ dữ liệu được lưu trữ dạng số, và chạy kịch bản một lần cho mỗi hàng. Hướng dẫn kiểm thử dựa trên dữ liệu chỉ ra cách cấu trúc các tệp đó.
Bạn cũng có thể kiểm soát cách chạy xử lý lỗi bằng --on-error, chấp nhận continue, end hoặc ignore. Và đối với các dự án sử dụng nhánh Apidog, --project <id> --branch <name> nhắm mục tiêu một nhánh cụ thể. Để đẩy tổng quan báo cáo lên đám mây Apidog, hãy thêm --upload-report dưới dạng cờ trần.
Điều này phù hợp với quy trình làm việc của Apidog như thế nào
Mục đích của Apidog CLI là bạn không cần phải viết hoặc duy trì mã kiểm thử. Bạn xây dựng một kịch bản kiểm thử từ dòng lệnh hoặc trong trình xây dựng kiểm thử trực quan, đặt các xác nhận về mã trạng thái và thân phản hồi, sau đó lưu lại. CI sau đó sẽ chạy chính xác kịch bản đó.
Vì kịch bản nằm trong dự án Apidog của bạn, nhóm của bạn chỉnh sửa các bài kiểm thử ở một nơi. Cấu hình CI hiếm khi thay đổi; nó chỉ gọi apidog run. Khi ai đó thêm một xác nhận trong ứng dụng, bản dựng CircleCI tiếp theo sẽ nhận nó mà không cần chỉnh sửa YAML.
Điều đó giữ một sự phân chia rõ ràng. Apidog sở hữu những gì được kiểm thử. CircleCI sở hữu khi nào và ở đâu nó chạy. Nếu bạn muốn so sánh CircleCI với các công cụ chạy khác cho loại công việc này, bản tổng hợp các công cụ tích hợp liên tục tốt nhất cho các nhóm API sẽ trình bày các đánh đổi.
Sẵn sàng đưa bộ API của bạn vào mỗi lần đẩy? Tải Apidog, xây dựng một kịch bản kiểm thử và thả cấu hình trên vào kho lưu trữ của bạn.
Các câu hỏi thường gặp
CircleCI là gì?
CircleCI là một nền tảng tích hợp và triển khai liên tục trên đám mây. Nó kết nối với kho lưu trữ Git của bạn, đọc tệp .circleci/config.yml và tự động chạy các bước xây dựng, kiểm thử và triển khai mỗi khi bạn đẩy mã. Nó loại bỏ nhu cầu chạy các bước đó bằng tay trên máy của riêng bạn.
CircleCI được dùng để làm gì?
Các nhóm sử dụng CircleCI để tự động hóa kiểm thử và triển khai. Các công việc phổ biến bao gồm biên dịch mã, chạy kiểm thử đơn vị và tích hợp, kiểm tra hợp đồng API, xây dựng hình ảnh Docker và phát hành các bản phát hành đến môi trường staging hoặc production. Trong hướng dẫn này, công việc chạy kiểm thử API Apidog CLI trên mỗi lần đẩy.
CircleCI có miễn phí không?
CircleCI có gói miễn phí bao gồm một lượng tín dụng xây dựng hàng tháng, đủ cho các dự án nhỏ và kho lưu trữ cá nhân. Các nhóm lớn hơn cần nhiều khả năng chạy đồng thời hơn, thời gian xây dựng dài hơn hoặc máy lớn hơn sẽ chuyển sang các gói trả phí Performance và Scale. Kiểm tra trang giá hiện tại của CircleCI để biết giới hạn chính xác.
CircleCI có phải là mã nguồn mở không?
Không, CircleCI là một sản phẩm thương mại, được lưu trữ, không phải mã nguồn mở. Bạn cấu hình nó thông qua một tệp YAML và chạy nó trên cơ sở hạ tầng của CircleCI hoặc một runner tự lưu trữ. Nếu bạn cần một máy chủ CI hoàn toàn mã nguồn mở, Jenkins là lựa chọn thay thế phổ biến, điều mà bài so sánh CircleCI vs Jenkins đã thảo luận.
CircleCI hoạt động như thế nào?
Khi bạn đẩy một commit, CircleCI phát hiện sự thay đổi, đọc tệp .circleci/config.yml và khởi động bộ thực thi mà bạn đã định nghĩa, chẳng hạn như một Docker container cimg/node. Nó chạy từng bước trong các job của bạn theo thứ tự, sau đó báo cáo kết quả trở lại nhà cung cấp Git của bạn. Các workflow cho phép bạn xâu chuỗi và chạy song song các job. Để có cái nhìn tổng thể hơn về cách điều này phù hợp với một pipeline phân phối, hãy xem Hướng dẫn CI/CD là gì.