DEV Community

Cover image for Hướng dẫn chạy kiểm thử API Apidog CLI trên CircleCI
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Hướng dẫn chạy kiểm thử API Apidog CLI trên CircleCI

Để chạy kiểm thử API Apidog CLI trong CircleCI, hãy thêm .circleci/config.yml, dùng Docker executor cimg/node, cài apidog-cli bằng npm, rồi chạy apidog run với access token, test scenario ID và environment ID. Lưu các giá trị này trong biến môi trường CircleCI, sau đó xuất báo cáo JUnit và HTML bằng store_test_results và store_artifacts.

Dùng thử Apidog ngay hôm nay

Bài viết này tập trung vào cách chạy kiểm thử, không phải chọn nền tảng CI. Nếu bạn vẫn đang cân nhắc giữa các công cụ, hãy xem so sánh CircleCI và Jenkins. Ở đây, giả định là bạn đã chọn CircleCI và muốn bộ kiểm thử API chạy tự động trên mỗi lần đẩy code.

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. Khi bạn đẩy một commit, CircleCI chạy các bước build, test và deploy đã được định nghĩa trong một tệp YAML.

Tệp cấu hình mặc định nằm tại:

.circleci/config.yml
Enter fullscreen mode Exit fullscreen mode

CircleCI đọc tệp này trên mỗi lần đẩy và tạo pipeline từ đó. Định dạng cấu hình hiện tại là 2.1, hỗ trợ các khối tái sử dụng như orbs, commands và parameters.

Một cấu hình CircleCI thường có ba phần chính:

  • Jobs: đơn vị công việc, gồm nhiều steps, ví dụ checkout code, cài dependency, chạy test.
  • Executors: môi trường chạy job, ví dụ Docker image cimg/node.
  • Workflows: điều phối job nào chạy, chạy theo thứ tự nào, song song hay tuần tự.

Với kiểm thử API, bạn chỉ cần một job cài Apidog CLI và chạy test scenario, sau đó gắn job đó vào workflow.

Tại sao nên chạy kiểm thử API trong CircleCI

Chạy kiểm thử API trong CI giúp phát hiện lỗi hợp đồng API trước khi chúng lên production. Ví dụ:

  • Response schema thay đổi ngoài ý muốn.
  • Một field bị đổi tên.
  • Luồng xác thực bị hỏng.
  • Endpoint trả status code không đúng.
  • Dữ liệu trả về không còn khớp assertion.

Apidog CLI được thiết kế cho trường hợp này. Bạn tạo và debug test scenario trong Apidog, sau đó chạy scenario đó trong CI bằng một lệnh CLI. Bạn không cần viết lại assertion trong một test framework riêng.

Nếu muốn hiểu tổng thể hơn về kiểm thử API trong pipeline, xem thêm 12 thực tiễn tốt nhất CI/CD cho kiểm thử API.

Điều kiện tiên quyết

Trước khi viết cấu hình CircleCI, hãy chuẩn bị trong Apidog:

  • Access token: dùng để xác thực CLI trong môi trường không giao diện. Bạn có thể tạo token trong phần cài đặt tài khoản Apidog. Xem thêm hướng dẫn xác thực Apidog CLI.
  • Test scenario ID: ID của kịch bản kiểm thử bạn muốn chạy. Mở scenario trong Apidog và sao chép ID từ URL hoặc phần cài đặt scenario.
  • Environment ID: môi trường chứa base URL và biến cần dùng, ví dụ staging hoặc production.

Bạn cũng cần:

  • Tài khoản CircleCI.
  • Repository Git đã kết nối với CircleCI.
  • Project đã được bật trong dashboard CircleCI.

Lưu bí mật bằng biến môi trường CircleCI

Không hard-code access token trong config.yml. Tệp này được commit vào Git, nên token trong đó sẽ bị lộ.

CircleCI hỗ trợ hai cách lưu giá trị nhạy cảm:

Cách 1: Project environment variables

Dùng khi biến chỉ áp dụng cho một repository.

Trong CircleCI:

  1. Mở project.
  2. Vào Project Settings.
  3. Chọn Environment Variables.
  4. Thêm các biến sau: 
APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

Cách 2: Contexts

Dùng khi nhiều repository dùng chung cùng một bộ biến.

Trong CircleCI:

  1. Vào Organization Settings.
  2. Chọn Contexts.
  3. Tạo context, ví dụ apidog-secrets.
  4. Thêm các biến Apidog vào context.
  5. Tham chiếu context trong workflow.

Với hướng dẫn này, bạn cần ba biến:

APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

Tệp .circleci/config.yml đầy đủ

Tạo tệp sau trong repository:

.circleci/config.yml
Enter fullscreen mode Exit fullscreen mode

Dán cấu hình này vào:

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
Enter fullscreen mode Exit fullscreen mode

Sau đó:

  1. Commit tệp cấu hình.
  2. Push lên repository.
  3. Mở CircleCI để xem job chạy.
  4. Kiểm tra log, tab Tests và Artifacts.

Phân tích cấu hình CircleCI

1. Chọn Docker executor 

docker:
  - image: cimg/node:20.11
Enter fullscreen mode Exit fullscreen mode

cimg/node là image tiện lợi của CircleCI cho Node.js. Nó đã có sẵn Node, npm và một số công cụ build phổ biến, nên bạn có thể chạy:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Trong ví dụ này, image dùng Node 20.11. Nếu team của bạn chuẩn hóa phiên bản Node khác, hãy đổi tag tương ứng.

2. Checkout source code 

- checkout
Enter fullscreen mode Exit fullscreen mode

Bước này kéo repository vào working directory của job. Dù test scenario nằm trong Apidog, bạn vẫn thường cần checkout để CircleCI có context của repo và lưu report đúng workspace.

3. Cài Apidog CLI 

- run:
    name: Install Apidog CLI
    command: npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Bước này cài CLI toàn cục trong container CircleCI hiện tại. Container chỉ tồn tại trong job, nên mỗi lần job chạy sẽ cài lại CLI.

4. Chạy test scenario 

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

Ý nghĩa từng tham số:

  • --access-token: xác thực CLI bằng token từ biến môi trường.
  • -t: chọn test scenario theo ID.
  • -e: chọn environment theo ID. CLI cần environment để biết base URL và biến môi trường.
  • -r: chọn reporter.
    • cli: in kết quả trực tiếp trong build log.
    • junit: xuất XML để CircleCI đọc và hiển thị trong tab Tests.
    • html: xuất báo cáo HTML để xem trên trình duyệt.
  • --out-dir: thư mục ghi report.

Xuất báo cáo trong CircleCI

Cấu hình này có hai bước xuất báo cáo:

- store_test_results:
    path: ./reports

- store_artifacts:
    path: ./reports
Enter fullscreen mode Exit fullscreen mode

store_test_results

CircleCI đọc JUnit XML trong ./reports và hiển thị kết quả trong tab Tests của build. Điều này giúp bạn xem lỗi theo test case thay vì phải đọc toàn bộ log.

store_artifacts

CircleCI upload thư mục ./reports dưới dạng artifact. Sau khi build hoàn tất, bạn có thể mở tab Artifacts và tải hoặc xem report HTML.

Nếu cần hiểu thêm về các định dạng report, xem hướng dẫn báo cáo kiểm thử Apidog CLI.

Chỉ chạy kiểm thử trên nhánh chính

Nếu không muốn chạy toàn bộ bộ API test trên mọi feature branch, thêm branch filter vào workflow:

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop
Enter fullscreen mode Exit fullscreen mode

Khi đó job api-tests chỉ chạy khi push lên:

  • main
  • develop

Các nhánh khác sẽ bỏ qua job này.

Dùng Context thay vì biến môi trường project

Nếu nhiều repo dùng chung token Apidog, dùng CircleCI Context để quản lý tập trung.

Ví dụ:

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apidog-secrets
Enter fullscreen mode Exit fullscreen mode

Trong context apidog-secrets, bạn thêm:

APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

Khi cần xoay token, bạn chỉ cập nhật trong context. Các repository dùng context đó sẽ nhận giá trị mới ở lần chạy tiếp theo.

Chạy kiểm thử dựa trên dữ liệu

Apidog CLI cũng hỗ trợ chạy scenario với dữ liệu từ CSV hoặc JSON bằng cờ -d.

Ví dụ:

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
Enter fullscreen mode Exit fullscreen mode

Cờ -d nhận:

  • Đường dẫn tệp CSV.
  • Đường dẫn tệp JSON.
  • ID bộ dữ liệu đã lưu.

CLI sẽ chạy scenario một lần cho mỗi hàng dữ liệu. Xem thêm hướng dẫn kiểm thử dựa trên dữ liệu.

Một số tùy chọn CLI hữu ích trong CI

Kiểm soát hành vi khi có lỗi

Bạn có thể dùng --on-error để quyết định cách CLI xử lý lỗi:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  --on-error continue
Enter fullscreen mode Exit fullscreen mode

Các giá trị được hỗ trợ:

continue
end
ignore
Enter fullscreen mode Exit fullscreen mode

Chạy theo branch trong Apidog

Nếu dự án Apidog của bạn dùng branch, có thể chỉ định project và branch:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  --project <id> \
  --branch <name> \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

Upload report lên Apidog

Để đẩy tổng quan report lên cloud Apidog, thêm cờ:

--upload-report
Enter fullscreen mode Exit fullscreen mode

Ví dụ:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

Quy trình làm việc đề xuất

Một workflow thực tế có thể như sau:

  1. Thiết kế API và test scenario trong Apidog.
  2. Thêm assertion cho status code, response body và các biến cần kiểm tra.
  3. Tạo access token, lấy test scenario ID và environment ID.
  4. Lưu các giá trị đó trong CircleCI Environment Variables hoặc Context.
  5. Thêm .circleci/config.yml.
  6. Push code.
  7. Kiểm tra kết quả trong CircleCI:
    • Build log cho output CLI.
    • Tab Tests cho JUnit result.
    • Tab Artifacts cho HTML report.

Mục tiêu là giữ ranh giới rõ ràng:

  • Apidog quản lý kiểm thử gì.
  • CircleCI quản lý khi nào và ở đâu kiểm thử chạy.

Bạn có thể tạo 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 của Apidog. Khi test scenario được cập nhật trong Apidog, lần build CircleCI tiếp theo sẽ chạy phiên bản mới mà không cần sửa YAML.

Nếu muốn so sánh CircleCI với các công cụ CI khác cho nhóm API, xem các công cụ tích hợp liên tục tốt nhất cho các nhóm API.

Sẵn sàng đưa bộ API test vào mỗi lần đẩy? Tải Apidog, tạo test scenario và thêm cấu hình CircleCI ở trên vào repository 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 repository Git, đọc tệp .circleci/config.yml và tự động chạy các bước build, test và deploy mỗi khi bạn đẩy code.

CircleCI được dùng để làm gì?

Các nhóm dùng CircleCI để tự động hóa kiểm thử và triển khai. Các công việc phổ biến gồm:

  • Build source code.
  • Chạy unit test.
  • Chạy integration test.
  • Kiểm tra hợp đồng API.
  • Build Docker image.
  • Deploy lên staging hoặc production.

Trong hướng dẫn này, CircleCI được dùng để chạy kiểm thử API bằng Apidog CLI.

CircleCI có miễn phí không?

CircleCI có gói miễn phí với một lượng build credit hàng tháng, thường đủ cho dự án nhỏ hoặc repository cá nhân. Các nhóm cần nhiều concurrency hơn, thời gian build dài hơn hoặc máy lớn hơn có thể dùng các gói trả phí như Performance và Scale. Hãy 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à 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 pipeline bằng YAML và chạy trên hạ tầng CircleCI hoặc runner tự lưu trữ. Nếu cần một CI server mã nguồn mở hoàn toàn, Jenkins là một lựa chọn phổ biến.

CircleCI hoạt động như thế nào?

Khi bạn đẩy commit, CircleCI phát hiện thay đổi, đọc .circleci/config.yml, khởi động executor đã định nghĩa, ví dụ Docker container cimg/node, rồi chạy từng step trong job theo thứ tự. Kết quả được báo cáo lại về provider Git của bạn. Workflow cho phép bạn nối chuỗi hoặc chạy song song nhiều job.

Để hiểu CI/CD ở mức tổng quan hơn, xem hướng dẫn CI/CD là gì.

Top comments (0)