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

Bạn có thể chạy bài kiểm tra API của Apidog CLI trong Drone CI bằng một bước Docker dùng ảnh Node, cài apidog-cli, rồi gọi apidog run với test scenario và environment tương ứng. Token Apidog nên được lưu trong Drone Secret và inject vào pipeline bằng from_secret. Bài viết này cung cấp cấu hình .drone.yml có thể copy-paste, cách quản lý secret, giới hạn chạy theo branch/event và cách xuất báo cáo khi Drone không có artifact storage tích hợp sẵn.

Dùng thử Apidog ngay hôm nay

Drone CI là gì và hoạt động như thế nào

Drone là nền tảng CI/CD mã nguồn mở, chạy theo mô hình container-native và hiện là một phần của Harness. CI/CD là thực hành tự động build, test và phân phối phần mềm trên mỗi thay đổi mã nguồn. Nếu cần ôn lại nền tảng, xem thêm CI/CD là gì.

Điểm quan trọng của Drone: mỗi step trong pipeline chạy trong một Docker container riêng. Bạn chọn image cho từng step, sau đó Drone chạy các command trong container đó. Cách này giúp pipeline dễ tái tạo, dễ debug và không phụ thuộc vào một build agent đã cài sẵn nhiều công cụ.

Pipeline được khai báo trong file .drone.yml ở thư mục gốc repository. Một Docker pipeline thường có:

• kind
• type
• name
• steps

Ví dụ tối thiểu:

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world

Drone chạy commands như shell script với cơ chế fail-fast. Nếu một command trả về exit code khác 0, build sẽ fail. Working directory mặc định là thư mục gốc của repository.

Vì sao nên chạy API test trong container step

API test giúp phát hiện sớm các thay đổi phá vỡ contract, ví dụ:

• response schema thay đổi ngoài ý muốn
• status code khác kỳ vọng
• field bắt buộc bị thiếu
• logic xác thực hoặc phân quyền bị lỗi

Với Apidog, bạn thiết kế và duy trì test scenario trong UI, sau đó chạy lại chính các scenario đó từ CLI. CI không cần giữ thêm collection file riêng hoặc viết lại test script. Để xem thêm về cách đưa API testing vào pipeline, đọc các phương pháp hay nhất về CI/CD cho kiểm tra API.

Apidog là nền tảng API all-in-one cho thiết kế, debug, test, mock và tạo tài liệu API. Phần CLI giúp biến test scenario đã lưu thành một lệnh có thể chạy lặp lại trong CI.

Lệnh Apidog CLI cần chạy

Trong Drone, bạn thường cần hai bước:

1. Cài Apidog CLI bằng npm.
2. Chạy test scenario bằng apidog run.

Ví dụ:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

Ý nghĩa các flag chính:

• --access-token: token truy cập Apidog. Không có dạng viết tắt.
• -t: ID test scenario cần chạy.
• -e: ID environment. Bắt buộc, dùng để chọn base URL và biến môi trường.
• -r: reporter cần dùng. Giá trị hợp lệ gồm cli, html, json, junit.

Một số flag hữu ích khác:

• -n hoặc --iteration-count: chạy lặp lại một số lần nhất định.
• -d hoặc --iteration-data: truyền file CSV/JSON hoặc ID dataset đã lưu cho data-driven testing.
• --out-dir: chỉ định thư mục xuất báo cáo.
• --upload-report: upload report overview lên Apidog Cloud để xem trong app.
• --on-error: điều khiển hành vi khi lỗi, gồm continue, end, ignore.
• --project <id> và --branch <name>: chạy test trên project branch cụ thể.

Tham khảo thêm hướng dẫn đầy đủ về Apidog CLI và hướng dẫn kiểm tra API REST từ dòng lệnh.

File .drone.yml hoàn chỉnh

Đây là cấu hình Drone CI cơ bản để chạy Apidog API test:

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Bạn cần thay:

• 1234567 bằng ID test scenario trong Apidog.
• 89012 bằng ID environment trong Apidog.
• apidog_access_token bằng tên secret đã tạo trong Drone.

Với reporter cli, kết quả pass/fail sẽ được in trực tiếp vào build log của Drone.

Lưu token Apidog bằng Drone Secret

Không commit API token vào repository. Hãy lưu token trong Drone Secret và inject vào runtime.

Trong .drone.yml, tham chiếu secret như sau:

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token

Ở đây:

• APIDOG_ACCESS_TOKEN là environment variable trong container.
• apidog_access_token là tên secret trong Drone.
• Giá trị token thật không xuất hiện trong YAML.

Có hai cách phổ biến để tạo secret.

Cách 1: dùng Drone UI:

1. Mở repository trong Drone.
2. Vào Settings.
3. Chọn Secrets.
4. Thêm secret tên apidog_access_token.
5. Dán token Apidog làm giá trị.

Cách 2: dùng Drone CLI:

drone secret add \
  --repository your-org/your-repo \
  --name apidog_access_token \
  --data your-apidog-token

Tên flag có thể khác giữa các phiên bản Drone CLI, vì vậy hãy kiểm tra tài liệu CLI tương ứng với bản bạn đang dùng.

Drone cũng hỗ trợ encrypted secret dạng YAML bằng drone encrypt, nhưng với hầu hết team, repo secret qua UI hoặc drone secret add là cách đơn giản hơn.

Để tìm hiểu thêm về xác thực CLI, xem xác thực Apidog CLI.

Giới hạn pipeline theo branch và event

Drone có hai cấp điều kiện:

• trigger: áp dụng cho toàn bộ pipeline.
• when: áp dụng cho từng step.

Dùng trigger cho toàn pipeline

Ví dụ dưới đây chỉ chạy pipeline khi có push hoặc pull_request vào branch main:

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Dùng when cho một step cụ thể

Nếu bạn muốn pipeline chạy rộng hơn, nhưng chỉ chạy API test ở main, dùng when trong step:

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
    when:
      branch:
        - main
      event:
        - push

Drone hỗ trợ glob pattern và các điều kiện include/exclude. Một số event phổ biến:

• push
• pull_request
• tag
• promote
• rollback
• cron
• custom

Hiển thị report khi Drone không có artifact storage tích hợp

Drone không có artifact storage mặc định, vì vậy bạn có hai lựa chọn thực tế.

Cách 1: dùng CLI reporter

Đây là cách đơn giản nhất:

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

Kết quả test được ghi trực tiếp vào build log. Với nhiều team, log này là đủ để review lỗi.

Cách 2: xuất HTML report và upload lên S3

Nếu cần report dạng file, bạn có thể xuất HTML vào thư mục reports, sau đó upload bằng plugin S3 của Drone.

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports

  - name: upload-report
    image: plugins/s3
    settings:
      bucket: my-bucket
      region: us-east-1
      source: reports/**/*
      target: /apidog-reports
      access_key:
        from_secret: aws_access_key
      secret_key:
        from_secret: aws_secret_key

Trong đó:

• source: glob pattern của file cần upload.
• target: prefix đích trong bucket.
• access_key và secret_key: lấy từ Drone Secret.

Để hiểu thêm cấu trúc report, xem các báo cáo kiểm tra Apidog CLI.

Chạy data-driven testing

Nếu một scenario cần chạy với nhiều bộ dữ liệu, dùng flag -d.

Ví dụ với file CSV:

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli

Mỗi dòng trong data.csv sẽ trở thành một iteration. Giá trị trong từng cột được map vào biến trong test scenario.

Tham khảo thêm kiểm tra theo hướng dữ liệu của Apidog CLI.

So sánh với các CI tool khác

Pattern trong Drone khá giống các CI tool khác:

1. Chọn runtime image, ví dụ node:20-alpine.
2. Cài Apidog CLI.
3. Inject token từ secret.
4. Chạy apidog run.
5. Fail build nếu test fail.

Nếu bạn cũng dùng pipeline khác, Apidog có hướng dẫn riêng cho GitHub Actions và Azure Pipelines.

Lưu ý: Apidog CLI phù hợp cho functional testing và contract testing. Nó không thay thế công cụ load testing chuyên dụng nếu bạn cần mô phỏng hàng nghìn virtual user đồng thời.

Quy trình khuyến nghị

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

1. Thiết kế endpoint và test scenario trong Apidog.
2. Tạo environment tương ứng cho dev/staging/prod.
3. Lấy test scenario ID và environment ID.
4. Tạo Drone Secret chứa Apidog access token.
5. Commit .drone.yml vào repository.
6. Kiểm tra build log sau mỗi push hoặc pull_request.

Ví dụ final command trong pipeline:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

Khi một thành viên cập nhật test scenario trong Apidog, lần chạy Drone tiếp theo sẽ dùng phiên bản test mới. Bạn không cần đồng bộ thêm bộ test thứ hai trong repository.

Tải Apidog miễn phí để tạo test scenario đầu tiên, sau đó thêm file .drone.yml ở trên vào repository để chạy API test trên mỗi lần push.

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

Drone CI là gì?

Drone là nền tảng CI/CD mã nguồn mở, container-native và hiện là một phần của Harness. Mỗi step trong pipeline chạy trong Docker container riêng, còn pipeline được khai báo bằng file .drone.yml.

Drone CI có miễn phí không?

Dự án cốt lõi của Drone là mã nguồn mở và có thể tự host miễn phí. Sau khi được Harness mua lại, Drone trở thành Harness CI Community Edition, đồng thời có các gói doanh nghiệp trả phí.

Drone CI có mã nguồn mở không?

Có. Drone là một trong các CI tool container-native đời đầu và vẫn là mã nguồn mở. Bạn có thể tự host và dùng nó để chạy pipeline như trong hướng dẫn này.

Drone CI được dùng như thế nào?

Team thường dùng Drone để tự động build, test và deploy trên mỗi push hoặc pull request. Bạn commit file .drone.yml, Drone đọc file đó và chạy từng step trong container tương ứng.

Làm thế nào để lưu secret trong Drone CI?

Bạn thêm secret qua Settings > Secrets trong Drone UI hoặc dùng lệnh drone secret add. Sau đó tham chiếu secret trong environment hoặc settings bằng from_secret. Token thật không xuất hiện trong file YAML.

Có thể chạy Apidog test trong CI mà không viết test script không?

Có. Bạn tạo test scenario trực quan trong Apidog, sau đó chạy trong Drone bằng một lệnh apidog run. Pipeline chỉ cần image Node, lệnh cài apidog-cli, token từ secret, test scenario ID và environment ID.