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

Bạn chạy các bài kiểm tra API của Apidog CLI trong Drone CI bằng cách thêm một bước pipeline Docker sử dụng ảnh Node, cài đặt apidog-cli và chạy apidog run với một môi trường. Mã thông báo truy cập Apidog của bạn được lưu trữ trong một bí mật của Drone và được đưa vào thông qua from_secret. Hướng dẫn này sẽ trình bày một tệp .drone.yml có thể sao chép-dán, cách xử lý bí mật, cổng phân nhánh và cách hiển thị báo cáo thử nghiệm vì Drone không có kho lưu trữ tạo phẩm tích hợp.

Drone CI là gì và cách hoạt động của nó

Drone là một nền tảng CI/CD mã nguồn mở, nguyên bản container, hiện là một phần của Harness. CI/CD là viết tắt của tích hợp liên tục và phân phối liên tục (Continuous Integration and Continuous Delivery), là thực tiễn tự động xây dựng và kiểm tra mã trên mỗi thay đổi. Nếu bạn muốn ôn lại khái niệm này, hãy xem CI/CD là gì.

Đặc điểm nổi bật của Drone rất đơn giản: mỗi bước pipeline chạy bên trong một container Docker riêng. Không có tác nhân xây dựng chung với một mớ công cụ được cài đặt sẵn. Bạn chọn một ảnh cho mỗi bước và Drone chạy các lệnh của bạn bên trong nó. Điều đó giúp các bản dựng có thể tái tạo và dễ hiểu.

Bạn định nghĩa một pipeline trong tệp .drone.yml ở thư mục gốc của kho lưu trữ. Một pipeline Docker có ba khóa cấp cao nhất: kind, type và name. Công việc diễn ra dưới mục steps, nơi mỗi bước khai báo một name, một image và một danh sách các commands.

kind: pipeline
type: docker
name: api-tests

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

Drone chạy các commands như một tập lệnh shell với set -e và set -x, do đó bản dựng sẽ thất bại nhanh chóng ở mã thoát khác không đầu tiên và hiển thị từng lệnh trước khi chạy nó. Các lệnh sẽ ghi đè lên điểm vào container và thư mục làm việc là thư mục gốc của kho lưu trữ của bạn.

Tại sao nên chạy kiểm tra API trong bước container

Các bài kiểm tra API giúp chống lại sự sai lệch của hợp đồng. Một thay đổi ở phần phụ trợ mà âm thầm thay đổi hình dạng phản hồi hoặc mã trạng thái có thể làm hỏng mọi client phía sau. Chạy các bài kiểm tra đó trên mỗi lần đẩy sẽ phát hiện hồi quy trước khi nó được triển khai.

Apidog rất phù hợp với mô hình này. Bạn xây dựng và duy trì các bài kiểm tra của mình một cách trực quan trong ứng dụng Apidog, sau đó chạy chính xác các kịch bản kiểm tra đó từ dòng lệnh với Apidog CLI. Không cần viết lại tập lệnh, không cần bộ công cụ kiểm tra riêng. Để có hướng dẫn rộng hơn về cách tích hợp kiểm tra API vào các pipeline, hãy đọc các phương pháp hay nhất về CI/CD cho kiểm tra API.

Apidog là một nền tảng API tất cả trong một để thiết kế, gỡ lỗi, kiểm tra, giả lập và tạo tài liệu. CLI là phần biến các kịch bản kiểm tra đã lưu của bạn thành một lệnh có thể lặp lại duy nhất, đây chính xác là những gì một bước Drone cần.

Lệnh Apidog CLI bạn sẽ chạy

Cài đặt CLI bằng npm, sau đó chạy một kịch bản kiểm tra. Trong CI, bạn trỏ lệnh chạy đến một kịch bản đã lưu bằng các cờ, vì vậy không có tệp bộ sưu tập cục bộ nào để quản lý.

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

Đây là chức năng của từng cờ:

--access-token chuyển mã thông báo truy cập Apidog của bạn. Không có dạng viết tắt.
-t là ID kịch bản kiểm tra bạn muốn chạy.
-e là ID môi trường và nó bắt buộc. Điều này chọn URL cơ sở và các biến mà lệnh chạy sử dụng.
-r liệt kê các trình báo cáo. Các giá trị hợp lệ là cli, html, json và junit.

Bạn có thể thêm nhiều cờ hơn nếu cần:

-n hoặc --iteration-count lặp lại lệnh chạy một số lần nhất định.
-d hoặc --iteration-data nhận đường dẫn tệp CSV hoặc JSON, hoặc ID tập dữ liệu được lưu trữ bằng số, cho các lệnh chạy dựa trên dữ liệu.
--out-dir đặt thư mục đầu ra báo cáo.
--upload-report đẩy tổng quan báo cáo lên đám mây Apidog, nơi bạn có thể xem nó trong ứng dụng. Bạn có thể sử dụng nó như một cờ độc lập.
--on-error kiểm soát hành vi lỗi với continue, end hoặc ignore.
--project <id> và --branch <name> nhắm mục tiêu một nhánh dự án cụ thể.

Để biết đầy đủ về lệnh và các tùy chọn của nó, hãy xem hướng dẫn đầy đủ về Apidog CLI và hướng dẫn chi tiết về kiểm tra API REST từ dòng lệnh.

Tệp .drone.yml hoàn chỉnh cho các bài kiểm tra Apidog

Đây là một pipeline đang hoạt động. Nó sử dụng một ảnh Node, cài đặt CLI và chạy kịch bản của bạn. Mã thông báo đến từ một bí mật của Drone chứ không phải được mã hóa cứng.

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

Thay thế 1234567 bằng ID kịch bản kiểm tra của bạn và 89012 bằng ID môi trường của bạn. Cả hai đều hiển thị trong ứng dụng Apidog. Bởi vì bước này sử dụng trình báo cáo cli, toàn bộ chi tiết pass/fail sẽ được in trực tiếp vào nhật ký bản dựng của Drone, nơi bất kỳ ai xem xét bản dựng đều có thể đọc được.

Lưu trữ bí mật trong Drone CI

Không bao giờ cam kết mã thông báo API vào kho lưu trữ của bạn. Drone giữ các bí mật bên ngoài tệp YAML và chèn chúng vào thời gian chạy.

Bạn tham chiếu một bí mật bên trong khối environment của một bước (hoặc khối settings của một plugin) bằng from_secret. Giá trị bạn viết là tên của bí mật, không phải chính mã thông báo.

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token

Có hai cách phổ biến để tạo bí mật. Cách thứ nhất là thông qua giao diện người dùng Drone: mở kho lưu trữ của bạn, vào Cài đặt (Settings), sau đó Bí mật (Secrets) và thêm một bí mật có tên apidog_access_token với mã thông báo của bạn làm giá trị. Cách thứ hai là công cụ dòng lệnh Drone.

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

Xác nhận tên cờ chính xác với tài liệu Drone CLI cho phiên bản của bạn, vì các cờ CLI có thể thay đổi giữa các bản phát hành. Drone cũng hỗ trợ một biến thể bí mật được mã hóa trong repo, nơi drone encrypt tạo ra một blob được mã hóa mà bạn nhúng dưới dạng một tài liệu YAML kind: secret riêng biệt. Đối với hầu hết các nhóm, bí mật repo được thêm thông qua giao diện người dùng hoặc drone secret add đơn giản hơn và là điểm khởi đầu được khuyến nghị.

Việc giữ mã thông báo trong một bí mật là kỷ luật tương tự mà bạn sẽ áp dụng ở bất kỳ nơi nào khác. Để biết thêm về cách CLI xử lý thông tin xác thực, hãy xem hướng dẫn về xác thực Apidog CLI.

Giới hạn chạy theo nhánh và sự kiện

Drone cung cấp cho bạn hai đòn bẩy để kiểm soát thời điểm công việc chạy: trigger ở cấp pipeline và when ở cấp bước.

Một khối trigger quyết định liệu toàn bộ pipeline có chạy hay không. Tất cả các điều kiện phải được đánh giá là đúng, vì vậy ví dụ dưới đây chỉ chạy trên các lần đẩy và yêu cầu kéo nhắm mục tiêu đến main.

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

Một khối when nằm bên trong một bước duy nhất và chỉ giới hạn bước đó. Điều này hữu ích khi bạn muốn hầu hết các pipeline chạy ở mọi nơi nhưng chỉ dành một bài kiểm tra nặng hơn cho một nhánh.

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

Cả hai khối đều hỗ trợ các mẫu glob và các khóa phụ include/exclude. Các loại sự kiện được hỗ trợ bao gồm push, pull_request, tag, promote, rollback, cron và custom.

Hiển thị báo cáo kiểm tra mà không cần kho lưu trữ tạo phẩm

Drone không có tính năng lưu trữ tạo phẩm gốc. Điều đó thay đổi cách bạn xử lý báo cáo, nhưng bạn có hai tùy chọn rõ ràng.

Cách thứ nhất là đơn giản nhất: sử dụng trình báo cáo cli để kết quả được in vào nhật ký bản dựng. Đối với hầu hết các nhóm, điều này là đủ, vì nhật ký đã hiển thị những xác nhận nào đã qua và những xác nhận nào đã thất bại.

Tùy chọn thứ hai là tạo một báo cáo HTML và tải nó lên một nơi lưu trữ bền vững. Drone phát hành một plugin S3 chính thức, plugins/s3, tải tệp lên S3 hoặc bất kỳ kho lưu trữ tương thích S3 nào. Tạo báo cáo bằng trình báo cáo html và --out-dir, sau đó thêm một bước tải lên.

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

Plugin đọc thông tin xác thực AWS từ các bí mật thông qua from_secret, cùng cơ chế mà bạn đã sử dụng cho mã thông báo Apidog. Khóa source là một mẫu glob của các tệp cần tải lên và target là tiền tố đích trong bucket.

Nếu bạn muốn xem chi tiết hơn về nội dung của báo cáo và cách đọc nó, hãy xem phân tích chi tiết về các báo cáo kiểm tra Apidog CLI.

Thêm các lần chạy theo hướng dữ liệu

Đôi khi một kịch bản cần chạy trên nhiều hàng đầu vào: mười ID người dùng, hàng tá payload, một tập hợp các trường hợp biên. CLI xử lý điều này bằng -d, chấp nhận đường dẫn tệp CSV hoặc JSON hoặc ID tập dữ liệu được lưu trữ.

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

Mỗi hàng trong data.csv trở thành một lần lặp, với các giá trị cột được liên kết với các biến kịch bản của bạn. Mẫu đầy đủ được đề cập trong kiểm tra theo hướng dữ liệu của Apidog CLI.

So sánh với các công cụ CI khác

Mẫu Drone, cài đặt CLI trong một container sạch và chạy một lệnh, được áp dụng cho hầu hết mọi hệ thống CI. Cú pháp trình bao bọc có thể khác nhau, nhưng bước Apidog vẫn như nhau.

Nếu bạn cũng chạy các pipeline ở nơi khác, Apidog có các hướng dẫn chi tiết tương ứng cho GitHub Actions và Azure Pipelines. Ý tưởng chung là các bài kiểm tra của bạn được lưu trữ trong Apidog và công cụ CI chỉ đơn giản là kích hoạt chúng.

Một lưu ý chân thành về phạm vi: Apidog CLI chạy các bài kiểm tra chức năng và hợp đồng, không phải kiểm tra tải quy mô lớn. Nếu bạn cần hàng nghìn người dùng ảo đồng thời để kiểm tra một điểm cuối, hãy tìm một công cụ kiểm tra tải chuyên dụng. Để xác minh rằng API của bạn hoạt động chính xác trên mỗi cam kết, CLI trong một bước Drone sẽ thực hiện tốt công việc đó.

Xây dựng các bài kiểm tra trực quan, chạy chúng bằng một lệnh

Quy trình làm việc giúp việc này trở nên dễ chịu là sự phân chia giữa việc tạo và thực thi. Bạn thiết kế các điểm cuối và tập hợp các kịch bản kiểm tra một cách trực quan trong Apidog, chuỗi các yêu cầu, xác nhận về mã trạng thái và các trường phản hồi, và tái sử dụng các biến môi trường. Không cần mã để xây dựng bộ kiểm thử.

Sau đó, CI chạy bộ kiểm thử đó bằng một lệnh CLI duy nhất bên trong một bước container. Khi một đồng nghiệp cập nhật một bài kiểm thử trong ứng dụng Apidog, bản dựng Drone tiếp theo sẽ tự động nhận được thay đổi đó. Không có bản sao thứ hai của các bài kiểm thử để đồng bộ hóa.

Tải Apidog miễn phí để xây dựng kịch bản kiểm thử đầu tiên của bạn, sau đó thả tệp .drone.yml ở trên vào kho lưu trữ của bạn để chạy nó trên mỗi lần đẩy.

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

Drone CI là gì?

Drone là một nền tảng CI/CD mã nguồn mở, nguyên bản container, hiện là một phần của Harness. Nó chạy mọi bước pipeline bên trong container Docker riêng, với các pipeline được định nghĩa trong tệp .drone.yml. Điều này giúp các bản dựng có thể tái tạo và tránh sự phân tán công cụ được cài đặt sẵn của các tác nhân xây dựng truyền thống.

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

Dự án cốt lõi của Drone là mã nguồn mở và miễn phí để tự lưu trữ. Sau khi được Harness mua lại, Drone trở thành Harness CI Community Edition, với các gói doanh nghiệp trả phí có sẵn. Đối với hầu hết các nhóm, phiên bản mã nguồn mở tự lưu trữ đủ để chạy các bài kiểm tra API như được mô tả trong hướng dẫn này.

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

Có. Drone là một trong những công cụ CI nguyên bản container ban đầu và vẫn là mã nguồn mở. Khi Harness mua lại nó vào năm 2020, công ty đã cam kết giữ dự án mã nguồn mở và bạn vẫn có thể tự lưu trữ nó.

Drone CI được sử dụng như thế nào?

Các nhóm sử dụng Drone để tự động xây dựng, kiểm tra và phân phối mã trên mỗi lần đẩy hoặc yêu cầu kéo. Bạn cam kết một tệp .drone.yml vào kho lưu trữ của mình, Drone đọc nó và chạy từng bước trong một container. Các bước phổ biến bao gồm biên dịch mã, chạy kiểm tra đơn vị, chạy kiểm tra API và tải tạo phẩm lên bộ lưu trữ ngoài.

Làm thế nào để lưu trữ bí mật trong Drone CI?

Bạn thêm bí mật thông qua màn hình Cài đặt (Settings) sau đó Bí mật (Secrets) của kho lưu trữ trong giao diện người dùng Drone, hoặc bằng lệnh drone secret add từ CLI. Sau đó, bạn tham chiếu từng bí mật bên trong khối environment của một bước hoặc khối settings của một plugin bằng cách sử dụng from_secret, trong đó giá trị là tên của bí mật. Bản thân mã thông báo không bao giờ xuất hiện trong tệp YAML của bạn.

Tôi có thể chạy các bài kiểm tra Apidog trong CI mà không cần viết kịch bản không?

Có. Bạn xây dựng các kịch bản kiểm tra một cách trực quan trong ứng dụng Apidog, sau đó chạy chúng trong CI bằng một lệnh apidog run duy nhất. Bước Drone chỉ cần một ảnh Node, một dòng npm install -g apidog-cli và lệnh chạy được trỏ đến ID kịch bản và môi trường của bạn.