Blog

Apidog CLI cho CI/CD: Quy trình tích hợp đơn giản để tự động kiểm thử API

Chạy các bài kiểm thử API Apidog của bạn trong CI/CD với trình chạy apidog-cli. Sao chép và dán các tệp pipeline cho GitHub Actions, GitLab CI, Jenkins, CircleCI và Azure Pipelines.

Ashley Innocent

Ashley Innocent

15 tháng 6 2026

Apidog CLI cho CI/CD: Quy trình tích hợp đơn giản để tự động kiểm thử API

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Bạn đã viết các bài kiểm thử API. Chúng hoạt động tốt trên máy của bạn. Và đó cũng chính là nơi chúng ở lại, bởi vì việc chạy chúng là điều mà ai đó phải nhớ để thực hiện. Một đồng đội đưa ra một thay đổi vào chiều thứ Sáu, điểm cuối xác thực lặng lẽ bắt đầu trả về lỗi 500 trên một đường dẫn mã, và người đầu tiên phát hiện ra điều đó là một người dùng vào thứ Hai. Phạm vi kiểm thử luôn có sẵn. Nhưng không ai chạy chúng vào thời điểm mà đáng lẽ chúng có thể phát hiện ra lỗi hồi quy.

Giải pháp là đưa các bài kiểm thử ra khỏi trình soạn thảo của bạn và vào quy trình tích hợp liên tục (pipeline), để chúng chạy trên mỗi lần đẩy mã mà không cần sự can thiệp của con người. Điều đó có nghĩa là bạn cần một lệnh để chạy các bài kiểm thử API của bạn một cách tự động (headless), trả về kết quả thành công hoặc thất bại rõ ràng, và tích hợp vào bất kỳ hệ thống CI nào bạn đang sử dụng. Apidog CLI làm được điều đó. Bạn xây dựng các kịch bản kiểm thử của mình một cách trực quan trong Apidog, sau đó chạy chúng từ một lệnh terminal duy nhất mà bất kỳ trình chạy CI nào có Node.js đều có thể thực thi. Không GUI, không cần viết lại kiểm thử dưới dạng mã, không cần dịch vụ bổ sung để lưu trữ.

Đây là hướng dẫn chỉ cần sao chép và dán. Dưới đây, bạn sẽ tìm thấy các tệp pipeline sẵn sàng sử dụng cho GitHub Actions, GitLab CI, Jenkins, CircleCI và Azure Pipelines, cùng với một số mẫu để duy trì tính chính xác của các bản dựng thành công. Hãy lấy khối mã phù hợp với nền tảng của bạn, thay thế ID và khóa bí mật của bạn, và bạn sẽ có các bài kiểm thử API kiểm soát mọi lần hợp nhất vào cuối ngày. Nếu bạn muốn tham khảo đầy đủ các cờ tùy chọn, chủ đề rộng hơn về cách tự động hóa kiểm thử API trong CI/CD sẽ bao gồm chiến lược; trang này là về việc thiết lập một pipeline hoạt động bằng cách dán mã.

Những gì bạn đang kết nối

Apidog CLI là một gói npm, apidog-cli. Nó chạy các kịch bản kiểm thử mà bạn tạo trong ứng dụng Apidog: các yêu cầu nối tiếp, xác nhận, giá trị được lấy từ phản hồi này sang phản hồi tiếp theo, lặp lại dựa trên dữ liệu. CLI không tạo ra định dạng kiểm thử riêng của nó. Nó truy cập vào dự án của bạn, tìm kịch bản theo ID, chạy nó theo cách mà ứng dụng sẽ làm, và báo cáo lại với một mã thoát.

Mã thoát đó là điểm mấu chốt. Khi mọi xác nhận đều thành công, quá trình chạy thoát với mã 0. Khi có bất kỳ lỗi nào, nó sẽ thoát với mã khác 0. Các hệ thống CI đọc mã thoát đó, đánh dấu bước đó là thất bại, và chặn việc hợp nhất hoặc triển khai. Bạn không cần cấu hình một cổng; cổng chính là mã thoát. Miễn là bước apidog run nằm trong pipeline của bạn, một xác nhận bị lỗi sẽ dừng toàn bộ quy trình.

Ba yếu tố làm cho một lần chạy hoạt động, và bạn sẽ thấy chúng trong mỗi khối dưới đây:

Bạn không cần nhập các ID đó bằng tay. Mở kịch bản kiểm thử trong Apidog, chuyển đến tab CI/CD của nó, chọn tùy chọn dòng lệnh, và tạo một mã thông báo truy cập. Apidog sẽ cung cấp cho bạn lệnh apidog run đầy đủ với ID kịch bản và ID môi trường đã được điền sẵn. Sao chép nó một lần, sau đó chuyển mã thông báo vào một bí mật. Nếu bạn chưa xây dựng kịch bản nào, hãy bắt đầu với cách viết kịch bản kiểm thử với Apidog và quay lại khi bạn có một kịch bản hoạt động.

Lệnh duy nhất làm nền tảng cho mọi thứ

Đây là lệnh chạy chuẩn. Mọi tệp pipeline đều là một lớp bao quanh dòng này:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 \
  -e 1629989 \
  -n 1 \
  -r html,junit \
  --out-dir ./apidog-reports

Mỗi phần thực hiện chức năng gì:

Các trình báo cáo tạo nên sự khác biệt giữa "bản dựng thất bại" và "đây là xác nhận đã thất bại và phản hồi đã làm hỏng nó". JUnit XML là định dạng mà hầu hết mọi nền tảng đều hiểu nguyên bản, vì vậy nó xuất hiện trong tất cả năm khối dưới đây.

GitHub Actions

Thêm đoạn mã này vào .github/workflows/api-tests.yml. Nó sẽ chạy kịch bản của bạn trên mỗi pull request đối với nhánh main, tải báo cáo lên dưới dạng artifact, và đánh dấu kiểm tra thất bại nếu bất kỳ xác nhận nào không thành công.

name: API tests

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -n 1 \
            -r html,junit \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: ./apidog-reports

Hai chi tiết quan trọng. Mã thông báo nằm trong Settings → Secrets and variables → Actions dưới dạng APIDOG_ACCESS_TOKEN và được truyền đến bước thông qua env:. Và if: always() trên bước tải lên có nghĩa là bạn vẫn nhận được báo cáo khi các kiểm thử thất bại, đây là thời điểm bạn thực sự cần đọc nó. Nếu một kịch bản bị lỗi, bước apidog run sẽ thoát với mã khác 0, công việc sẽ bị đánh dấu đỏ, và PR sẽ hiển thị một kiểm tra thất bại. Để tìm hiểu sâu hơn về nền tảng này, hãy xem cách tự động hóa kiểm thử API trong GitHub Actions.

GitLab CI

Ý tưởng tương tự trong .gitlab-ci.yml. Hình ảnh node:20 đã có môi trường runtime, vì vậy việc cài đặt là thiết lập duy nhất cần làm.

stages:
  - test

api-tests:
  stage: test
  image: node:20
  script:
    - npm install -g apidog-cli
    - >
      apidog run
      --access-token "$APIDOG_ACCESS_TOKEN"
      -t 605067
      -e 1629989
      -r junit,cli
      --out-dir ./apidog-reports
  artifacts:
    when: always
    paths:
      - apidog-reports/
    reports:
      junit: apidog-reports/*.xml

Lưu trữ APIDOG_ACCESS_TOKEN dưới Settings → CI/CD → Variables dưới dạng biến được che (masked) và bảo vệ (protected) để nó không bao giờ in ra trong nhật ký. Khối reports: junit: là phần mà người dùng GitLab thường bỏ qua: nó hướng dẫn GitLab phân tích XML và hiển thị kết quả ngay trong tiện ích yêu cầu hợp nhất. Người đánh giá có thể thấy những xác nhận nào đã thất bại mà không cần tải xuống bất cứ thứ gì.

Jenkins

Đối với một pipeline khai báo, lưu trữ mã thông báo dưới dạng thông tin xác thực Jenkins và kéo nó vào môi trường, sau đó gọi CLI trong một giai đoạn. Khối post sẽ đưa JUnit XML vào biểu đồ xu hướng kiểm thử của Jenkins và giữ báo cáo HTML trên bản dựng.

pipeline {
  agent any
  environment {
    APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
  }
  stages {
    stage('API tests') {
      steps {
        sh 'npm install -g apidog-cli'
        sh '''
          apidog run \
            --access-token $APIDOG_ACCESS_TOKEN \
            -t 605067 \
            -e 1629989 \
            -n 1 \
            -r html,junit \
            --out-dir apidog-reports
        '''
      }
    }
  }
  post {
    always {
      junit 'apidog-reports/*.xml'
      archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
    }
  }
}

Nếu các tác nhân xây dựng (build agents) của bạn đã có CLI được lưu vào bộ nhớ cache, hãy bỏ dòng npm install và gọi trực tiếp apidog run. Apidog cũng cung cấp hướng dẫn tích hợp dành riêng cho Jenkins nếu bạn muốn sử dụng plugin thay vì bước shell: tích hợp kiểm thử tự động Apidog với Jenkins cho CI/CD.

CircleCI

Trong .circleci/config.yml, sử dụng hình ảnh Node tiện lợi và lưu trữ mã thông báo dưới dạng biến môi trường dự án trong Project Settings → Environment Variables.

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 API test scenario
          command: |
            apidog run \
              --access-token "$APIDOG_ACCESS_TOKEN" \
              -t 605067 \
              -e 1629989 \
              -r junit,cli \
              --out-dir ./apidog-reports
      - store_test_results:
          path: ./apidog-reports
      - store_artifacts:
          path: ./apidog-reports
          destination: apidog-reports

workflows:
  test:
    jobs:
      - api-tests

store_test_results là tương đương của khối JUnit của GitLab trong CircleCI; trỏ nó vào thư mục báo cáo và CircleCI sẽ hiển thị các xác nhận thất bại trong tab Tests của nó. store_artifacts giữ báo cáo HTML được đính kèm để bạn có thể mở nó từ trang bản dựng.

Azure Pipelines

Trong azure-pipelines.yml, cài đặt Node bằng tác vụ, chạy CLI và xuất kết quả JUnit. Thêm APIDOG_ACCESS_TOKEN làm biến bí mật trong pipeline (hoặc kéo nó từ một nhóm biến Azure Key Vault), sau đó ánh xạ nó vào env của bước script.

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
    displayName: 'Install Node.js'

  - script: npm install -g apidog-cli
    displayName: 'Install Apidog CLI'

  - script: |
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 605067 \
        -e 1629989 \
        -r junit,html \
        --out-dir ./apidog-reports
    displayName: 'Run API test scenario'
    env:
      APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)

  - task: PublishTestResults@2
    condition: always()
    inputs:
      testResultsFormat: 'JUnit'
      testResultsFiles: 'apidog-reports/*.xml'
      testRunTitle: 'Apidog API tests'

Macro $(APIDOG_ACCESS_TOKEN) đọc biến pipeline bí mật; ánh xạ nó qua env giúp nó không hiển thị trên dòng lệnh. PublishTestResults@2 với condition: always() làm cho kết quả hiển thị trong tab Tests dù quá trình chạy thành công hay thất bại. Để tìm hiểu chi tiết hơn về nền tảng này, Apidog có hướng dẫn chuyên sâu về kiểm thử API pipeline trong Azure DevOps.

Các mẫu giúp duy trì tính chính xác của cổng kiểm soát

Một pipeline chạy các bài kiểm thử của bạn là nền tảng cơ bản. Những công thức này là thứ giúp nó hữu ích hàng ngày.

Kiểm thử khói ngay sau khi triển khai. Chạy một kịch bản nhanh chóng trên môi trường sản xuất ngay khi một bản phát hành được triển khai, nhắm mục tiêu vào môi trường prod, và dừng lại ở lỗi đầu tiên:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end

Kiểm thử hồi quy toàn diện qua đêm. Chạy toàn bộ một thư mục kịch bản theo lịch trình và thu thập mọi lỗi vào một báo cáo thay vì dừng lại ở lỗi đầu tiên:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports

--on-error là tùy chọn điều khiển ở đây. end dừng nhanh chóng khi có lỗi, điều bạn muốn cho một cổng triển khai. continue chạy mọi bước để một báo cáo hàng đêm hiển thị tất cả các lỗi cùng một lúc. Dù bằng cách nào, quá trình chạy vẫn thoát với mã khác 0 nếu có bất kỳ lỗi nào, vì vậy cổng kiểm soát vẫn được giữ.

Chạy một kịch bản với nhiều đầu vào. Thực hiện các lần lặp từ một tệp dữ liệu và coi mỗi hàng là một lượt chạy riêng biệt:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit

Kiểm thử một nhánh tính năng, không phải nhánh main. Chạy các kịch bản chính xác như chúng tồn tại trên nhánh đó:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli

Gỡ lỗi lỗi chỉ xảy ra trong CI. Khi một kịch bản chạy thành công cục bộ nhưng thất bại trong pipeline, hãy thêm --verbose. Nó sẽ in ra yêu cầu chính xác mà trình chạy đã gửi và phản hồi chính xác mà nó nhận được, đây hầu như luôn là cách bạn tìm ra sự khác biệt về môi trường gây ra vấn đề.

Khi bản dựng đánh lừa bạn

Một vài chế độ thất bại xuất hiện đủ thường xuyên để cần lưu ý, bởi vì mỗi cái đều ngấm ngầm làm mất hiệu lực của cổng kiểm soát.

Tại sao nên xây dựng trực quan và chạy tự động (headless)

Có một lựa chọn thiết kế thực sự đằng sau tất cả những điều này, và nó đáng để dành một đoạn. Với các trình chạy ưu tiên script, kiểm thử và quá trình thực thi của nó là cùng một tệp, vì vậy một script dễ vỡ vừa là kiểm thử vừa là điểm tắc nghẽn của bạn. Với Apidog, kịch bản trong dự án của bạn là kiểm thử, và CLI chỉ chạy nó ở nơi mà con người không thể có mặt. Không ai phải duy trì hai phiên bản của cùng một kiểm tra. Bạn tạo nhanh chóng trong trình xây dựng trực quan, bạn chạy tự động trong pipeline, và hai thứ này luôn đồng bộ vì chúng là cùng một artifact. Đó là một phần lớn lý do tại sao các đội coi Apidog là một thay thế Postman cho kiểm thử API một khi CI được đưa vào, và tại sao các xác nhận API vững chắc lại quan trọng hơn trình chạy mà bạn bao bọc chúng.

Vòng lặp rất đơn giản một khi nó đã chạy. Thiết kế và gỡ lỗi các yêu cầu trong ứng dụng. Nối chúng thành một kịch bản với các xác nhận. Đẩy mã của bạn, và CLI chạy kịch bản đó trong CI trên mỗi thay đổi. Khi có lỗi, báo cáo sẽ nêu tên xác nhận bị lỗi và mã thoát sẽ dừng quá trình triển khai. Bạn sửa lỗi, đẩy lại, và cùng một cổng kiểm soát sẽ xác nhận sửa lỗi.

Nếu các bài kiểm thử của bạn vẫn đang nằm trong trình soạn thảo của ai đó, đó là khoảng trống cần khắc phục trong tuần này. Tải Apidog, làm cho một kịch bản chạy thành công, sao chép lệnh apidog run từ tab CI/CD của nó, và dán khối mã trên cho nền tảng của bạn. Bạn sẽ có các bài kiểm thử API kiểm soát mọi lần hợp nhất ngay trong buổi chiều cùng ngày.

button

Các câu hỏi thường gặp

Apidog CLI có miễn phí để sử dụng trong CI không? CLI là một gói npm miễn phí: npm install -g apidog-cli. Nó chạy các kịch bản từ dự án Apidog của bạn, vì vậy những gì bạn có thể chạy phụ thuộc vào gói Apidog của bạn, nhưng bản thân trình chạy dòng lệnh không phải là một sản phẩm trả phí riêng biệt.

Tôi có phải viết lại các bài kiểm thử của mình dưới dạng mã không? Không. Bạn xây dựng các kịch bản trực quan trong Apidog và CLI chạy chúng bằng ID. Kịch bản là bài kiểm thử; CLI chỉ là trình thực thi. Đó là điểm chính phân biệt nó với các trình chạy ưu tiên script.

Một bài kiểm thử thất bại thực sự làm hỏng bản dựng của tôi như thế nào? Thông qua mã thoát. Khi bất kỳ xác nhận nào thất bại, apidog run sẽ thoát với mã khác 0. Hệ thống CI của bạn đọc mã đó, đánh dấu bước đó là thất bại, và chặn việc hợp nhất hoặc triển khai. Bạn không cần thêm bất kỳ cấu hình bổ sung nào để cổng kiểm soát hoạt động.

Tôi nên sử dụng định dạng báo cáo nào? Sử dụng junit cho XML có thể đọc được bằng máy mà bảng điều khiển CI của bạn phân tích thành kết quả thành công/thất bại, và thêm html nếu bạn muốn một báo cáo có thể duyệt được lưu dưới dạng artifact của bản dựng. Một cặp phổ biến là -r junit,html. Hãy bật cả cli nếu bạn muốn đầu ra dễ đọc trong nhật ký bản dựng.

Tôi có cần cài đặt Apidog trên máy chủ CI không? Không. Trình chạy CI chỉ cần Node.js (phiên bản 16 trở lên) và gói apidog-cli. Không cần ứng dụng desktop, không GUI, không tệp giấy phép trên máy chủ. Gói này cộng với một mã thông báo truy cập là đủ.

Tôi có thể chạy mà không cần cài đặt toàn cục không? Có. Sử dụng npx apidog-cli run ... để thực thi mà không cần cài đặt toàn cục liên tục, điều này gọn gàng hơn trên các trình chạy tạm thời được gỡ bỏ sau mỗi công việc.

Điều này khác với Newman như thế nào? Newman chạy các bộ sưu tập Postman từ dòng lệnh. Apidog CLI chạy các kịch bản kiểm thử Apidog. Các vai trò tương tự nhau, nhưng trình chạy Apidog thực thi các kịch bản bạn đã tạo trong ứng dụng và được phân phối dưới dạng gói apidog-cli duy nhất. Xem Postman CLI vs Newman để biết so sánh từ phía Postman.

Tôi lấy mã thông báo truy cập và ID ở đâu? Tất cả đều từ tab CI/CD của kịch bản kiểm thử trong Apidog. Chọn tùy chọn dòng lệnh, tạo một mã thông báo truy cập, và sao chép lệnh apidog run đầy đủ mà Apidog đã tạo sẵn với ID kịch bản và ID môi trường. Sau đó chuyển mã thông báo vào một bí mật CI và tham chiếu nó dưới dạng $APIDOG_ACCESS_TOKEN.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống