Bạn chạy các bài kiểm tra API tự động trong Buildkite bằng cách định nghĩa một bước lệnh trong .buildkite/pipeline.yml để cài đặt Apidog CLI, chạy apidog run với một môi trường, và tải lên báo cáo HTML như một build artifact. Hướng dẫn này sẽ trình bày toàn bộ quy trình, bao gồm cách Buildkite xử lý các bí mật để mã thông báo truy cập Apidog của bạn không bao giờ bị lộ trong nhật ký. Chúng tôi giả định rằng các bài kiểm tra Apidog của bạn đã tồn tại; bạn xây dựng chúng bằng giao diện một lần, sau đó chạy chúng từ một lệnh duy nhất trong CI.
Một lời giải thích nhanh trước khi chúng ta bắt đầu. Buildkite là một nền tảng CI/CD. Nó không giống với Docker BuildKit, backend xây dựng hình ảnh bên trong Docker. Tên gọi có vẻ giống nhau, nhưng chúng là những sản phẩm không liên quan. Bài viết này hoàn toàn về Buildkite, nền tảng CI/CD.
Buildkite là gì
Buildkite là một nền tảng CI/CD được xây dựng theo mô hình lai (hybrid). Nó có một mặt phẳng điều khiển được lưu trữ (hosted control plane), bảng điều khiển và điều phối bản dựng mà bạn thấy trong trình duyệt của mình, và các tác nhân (agents) thực sự chạy các công việc của bạn.
Sự phân chia này quan trọng. Mặt phẳng điều khiển lên lịch công việc, nhưng công việc chạy trên các tác nhân. Bạn có thể tự lưu trữ các tác nhân trên cơ sở hạ tầng hoặc đám mây của riêng mình, hoặc bạn có thể sử dụng các tác nhân được Buildkite lưu trữ, là điện toán được quản lý mà Buildkite chạy cho bạn.
Đây là điểm chính khiến Buildkite khác biệt so với các hệ thống CI được lưu trữ hoàn toàn. Mã nguồn và bí mật của bạn có thể ở trên máy của riêng bạn trong khi Buildkite điều phối các bản dựng. Đối với thử nghiệm API, điều đó có nghĩa là các bài kiểm tra của bạn chạy ở nơi các dịch vụ và quyền truy cập mạng của bạn đã có sẵn.
Tác nhân Buildkite bản thân nó là mã nguồn mở. Nó được viết bằng Go và phát hành theo Giấy phép MIT, với mã nguồn trên GitHub. Nền tảng và mặt phẳng điều khiển xung quanh nó là một sản phẩm SaaS thương mại.
Buildkite được sử dụng để làm gì
Các nhóm sử dụng Buildkite để chạy bất kỳ loại công việc tự động nào được kích hoạt bởi các thay đổi mã: xây dựng artifact, chạy kiểm thử đơn vị và tích hợp, triển khai dịch vụ và chạy kiểm tra end-to-end. Vì các tác nhân có thể chạy trên phần cứng của riêng bạn, nó phổ biến trong các nhóm cần kiểm soát về điện toán, ranh giới mạng hoặc phần cứng như GPU.
Thử nghiệm API rất phù hợp với điều này. Bạn muốn các bài kiểm tra của mình tác động đến môi trường staging hoặc test, xác nhận các phản hồi thực tế và chặn quá trình triển khai khi một hợp đồng bị lỗi. Buildkite cung cấp cho bạn các loại bước để mô hình hóa chính xác luồng đó, điều mà chúng ta sẽ sử dụng dưới đây.
Nếu bạn đang cân nhắc Buildkite với các lựa chọn khác, bài tổng hợp của chúng tôi về các công cụ tích hợp liên tục tốt nhất cho các nhóm API bao gồm cách một số nền tảng so sánh cho trường hợp sử dụng này.
Cách các pipeline của Buildkite được định nghĩa
Một pipeline của Buildkite là một danh sách các bước. Nơi mặc định để định nghĩa chúng là một tệp tại .buildkite/pipeline.yml trong kho lưu trữ của bạn. Khi một bản dựng bắt đầu, Buildkite tìm kiếm một thư mục có tên .buildkite chứa một tệp có tên pipeline.yml. Một thư mục buildkite/ không ẩn ở thư mục gốc của kho lưu trữ cũng hoạt động.
Khóa cấp cao nhất là steps:, và nó chứa một danh sách. Các loại bước bạn sẽ sử dụng nhiều nhất cho thử nghiệm API là:
- Bước lệnh (Command steps) chạy các lệnh shell trên một tác nhân. Đây là nơi các bài kiểm tra của bạn chạy.
- Bước chờ (Wait steps) tạm dừng pipeline cho đến khi mọi bước trước đó hoàn thành. Bạn viết chúng dưới dạng một mục danh sách
- waitđơn giản. - Bước chặn (Block steps) tạo một cổng phê duyệt thủ công, được viết dưới dạng
- block: "Label". Một người nhấp để tiếp tục, điều này hữu ích trước khi triển khai sản xuất.
Các bước lệnh hỗ trợ một tập hợp các khóa mà bạn sẽ thường xuyên sử dụng: label và key để đặt tên và tham chiếu, command hoặc commands cho tập lệnh, env cho các biến môi trường, agents để định hướng, secrets để chèn các giá trị bí mật, artifact_paths cho các tệp cần giữ, parallelism để phân tán, và matrix để chạy cùng một bước trên một tập hợp các giá trị.
Khóa agents là một hash của các cặp thẻ. Bạn sử dụng nó để định tuyến một bước đến tác nhân phù hợp, ví dụ queue: "tests". Các thẻ cho phép bạn giữ các công việc kiểm thử trên các tác nhân có quyền truy cập mạng hoặc công cụ phù hợp.
Một pipeline sao chép-dán chạy kiểm thử API
Đây là một tệp .buildkite/pipeline.yml tối thiểu cài đặt Apidog CLI, chạy một kịch bản kiểm thử trên một môi trường và tải lên báo cáo HTML. Apidog CLI là một công cụ Node.js chạy các kịch bản kiểm thử Apidog của bạn từ dòng lệnh.
steps:
- label: ":test_tube: API tests (Apidog)"
key: "api-tests"
command: |
npm install -g apidog-cli
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 637132 \
-e 358171 \
-r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
agents:
queue: "default"
secrets:
- APIDOG_ACCESS_TOKEN
Một vài lưu ý về các cờ (flags). -t là ID của kịch bản kiểm thử hoặc thư mục kịch bản bạn muốn chạy. -e là ID môi trường thời gian chạy, chọn URL cơ sở và các biến mà bài kiểm tra của bạn sử dụng. -r html,cli yêu cầu cả bản tóm tắt đầu cuối dễ đọc và một tệp báo cáo HTML. --access-token truyền mã thông báo Apidog của bạn để CLI có thể truy cập dự án của bạn.
Máy chủ tác nhân Buildkite đã có sẵn tệp thực thi buildkite-agent, vì đó là thứ chạy công việc. Bạn chỉ cần tự cài đặt apidog-cli. Để tìm hiểu sâu hơn về từng cờ, hãy xem hướng dẫn đầy đủ về Apidog CLI.
Nếu bạn muốn hướng dẫn từng bước về cách chạy một API duy nhất từ thiết bị đầu cuối trước, hướng dẫn kiểm thử dòng lệnh Apidog CLI là một bước khởi động tốt trước khi tích hợp nó vào CI.
Truyền mã thông báo truy cập Apidog bằng Buildkite secrets
Mã thông báo truy cập Apidog của bạn là một thông tin xác thực. Nó không bao giờ được nằm trong pipeline.yml của bạn hoặc in ra nhật ký bản dựng. Buildkite cung cấp cho bạn một tính năng gốc cho việc này được gọi là Buildkite secrets.
Buildkite secrets là một kho lưu trữ khóa-giá trị được mã hóa. Các giá trị được mã hóa khi không hoạt động và khi truyền qua TLS, được giải mã trên máy chủ Buildkite và được giới hạn theo từng cụm, trong đó mỗi cụm có khóa mã hóa riêng. Nó hoạt động với cả tác nhân được Buildkite lưu trữ và tác nhân tự lưu trữ. Bất kỳ giá trị bí mật nào xuất hiện trong nhật ký của bạn đều được tự động ẩn đi.
Có hai cách để sử dụng một bí mật đã lưu trữ. Cách thứ nhất là khóa secrets: trên một bước lệnh. Ở dạng danh sách đơn giản nhất, tên biến môi trường khớp với khóa bí mật:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
- APIDOG_ACCESS_TOKEN
Nếu bí mật đã lưu trữ của bạn có tên khác với tên biến môi trường bạn muốn, hãy sử dụng dạng hash. Khóa là tên biến môi trường và giá trị là khóa bí mật:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
APIDOG_ACCESS_TOKEN: apidog_token # tên biến môi trường : khóa bí mật Buildkite
Cách thứ hai là lấy bí mật một cách bắt buộc bên trong tập lệnh của bạn bằng CLI của tác nhân. Điều này tiện dụng khi bạn muốn kiểm soát chính xác thời điểm giá trị được đọc:
APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
Buildkite secrets không phải là lựa chọn duy nhất của bạn. Trên các tác nhân tự lưu trữ, bạn có thể sử dụng một hook tác nhân environment, một tập lệnh chạy khi bắt đầu mỗi công việc và xuất các giá trị vào môi trường. Bạn có thể giới hạn nó dựa trên các biến như $BUILDKITE_PIPELINE_SLUG hoặc $BUILDKITE_STEP_KEY để một bí mật chỉ tải cho các công việc phù hợp. Bạn cũng có thể kéo từ các kho lưu trữ bên ngoài như AWS Secrets Manager, HashiCorp Vault hoặc GCP thông qua các plugin Buildkite, trong trường hợp đó bí mật không bao giờ được lưu trữ hoặc gửi đến Buildkite.
Các giá trị env: đơn thuần là ổn cho cấu hình không nhạy cảm, nhưng đừng đặt mã thông báo ở đó. Để biết thêm chi tiết về cách mã thông báo chảy từ kho bí mật của bạn vào CLI, hãy xem hướng dẫn về xác thực Apidog CLI.
Tải báo cáo HTML lên dưới dạng artifact
Trình báo cáo -r html ghi một báo cáo HTML vào một đường dẫn cục bộ trong không gian làm việc của tác nhân. Tệp đó sẽ biến mất khi công việc kết thúc trừ khi bạn lưu nó. Lệnh buildkite-agent artifact upload giữ lại nó.
buildkite-agent artifact upload "apidog-reports/**/*"
Các dấu ngoặc kép quanh mẫu glob rất quan trọng. Chúng ngăn shell của bạn mở rộng mẫu trước khi tác nhân nhìn thấy nó, vì vậy tác nhân tự thực hiện việc khớp mẫu. Các artifact được tải lên sẽ được lưu trữ trong bộ nhớ do Buildkite quản lý theo mặc định, với thời gian lưu trữ 6 tháng và giới hạn 5GB cho mỗi artifact. Bạn có thể truyền một đích đến làm đối số thứ hai nếu muốn gửi chúng đến nơi khác.
Sau khi một bản dựng chạy, báo cáo sẽ hiển thị dưới tab Artifacts của bản dựng. Bất kỳ ai xem xét bản dựng đều có thể tải xuống và xem các xác nhận nào đã vượt qua hoặc thất bại. Nếu bạn muốn hiểu trước các định dạng báo cáo, hướng dẫn báo cáo kiểm thử Apidog CLI bao gồm đầu ra CLI, HTML và JSON.
Chạy kiểm thử song song trên nhiều môi trường
Khi bạn muốn cùng một bộ kiểm thử chạy trên nhiều môi trường cùng một lúc, hãy sử dụng một matrix. Buildkite mở rộng một định nghĩa bước thành một công việc cho mỗi giá trị matrix, và chúng chạy song song.
steps:
- label: ":test_tube: API tests {{matrix.env}}"
command: |
npm install -g apidog-cli
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e "{{matrix.env}}" -r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
secrets:
- APIDOG_ACCESS_TOKEN
matrix:
setup:
env:
- "358171" # id môi trường staging
- "358172" # id môi trường production
Ở đây, {{matrix.env}} được thay thế vào cả label và cờ -e, vì vậy mỗi công việc nhắm mục tiêu một môi trường Apidog khác nhau. Nếu bạn chỉ muốn phân tán các bản sao giống hệt nhau của một công việc duy nhất, hãy đặt parallelism: 5 trên bước thay vì sử dụng matrix.
Đối với các lần chạy dựa trên dữ liệu, trong đó một kịch bản lặp qua các hàng của tệp CSV hoặc JSON, Apidog CLI xử lý điều đó bằng cờ -d riêng của nó thay vì Buildkite matrix. Hướng dẫn kiểm thử dựa trên dữ liệu Apidog CLI chỉ ra cách đưa tệp dữ liệu vào một kịch bản.
Chặn triển khai đằng sau các bài kiểm thử
Một hình thức phổ biến là: chạy kiểm thử, đợi chúng hoàn thành, yêu cầu con người phê duyệt, sau đó triển khai. Buildkite mô hình hóa điều này bằng các bước wait và block.
steps:
- label: ":test_tube: API tests"
command: "npm install -g apidog-cli && apidog run --access-token \"$APIDOG_ACCESS_TOKEN\" -t 637132 -e 358171 -r html,cli"
secrets:
- APIDOG_ACCESS_TOKEN
- wait
- block: ":rocket: Deploy?"
branches: "main"
- label: ":rocket: Deploy"
command: "scripts/deploy.sh"
Bước wait giữ pipeline cho đến khi các bài kiểm thử hoàn tất. Bước block tạm dừng để nhấp thủ công và bị giới hạn ở nhánh main với branches:. Chỉ sau khi ai đó phê duyệt thì bước triển khai mới chạy. Điều này ngăn một bộ kiểm thử thất bại tiếp cận môi trường sản xuất. Để biết các mẫu rộng hơn về điều này, hãy xem các phương pháp hay nhất về CI/CD cho thử nghiệm API của chúng tôi.
Thêm chú thích tóm tắt
Nhật ký bản dựng thường dài. Một chú thích đặt một bản tóm tắt ngắn gọn, được định dạng ở đầu trang bản dựng. Bạn tạo một chú thích bằng cách đưa markdown vào buildkite-agent annotate.
cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### Kết quả kiểm thử API
Tất cả các kịch bản Apidog đã vượt qua. [Tải xuống báo cáo HTML đầy đủ tại đây](artifact://apidog-reports/index.html)
EOF
Cờ --style kiểm soát màu sắc và biểu tượng, với các giá trị info, warning, error, và success. Cờ --context cung cấp cho chú thích một ID duy nhất, vì vậy một bước sau đó với cùng ngữ cảnh sẽ cập nhật chú thích đó thay vì thêm một cái mới. Liên kết artifact:// chỉ thẳng người xem đến báo cáo HTML đã tải lên.
Apidog phù hợp ở đâu
Pipeline trên ngắn gọn có chủ đích. Việc nặng nhọc trong việc viết và bảo trì các bài kiểm thử diễn ra trong Apidog, không phải trong YAML.
Apidog là một nền tảng API tất cả trong một để thiết kế, gỡ lỗi, kiểm thử, giả lập và tài liệu hóa API. Bạn xây dựng các kịch bản kiểm thử trong một trình chỉnh sửa trực quan: nối chuỗi các yêu cầu, truyền dữ liệu giữa các bước và thêm các xác nhận mà không cần viết tập lệnh. Vì các kịch bản nằm trong dự án Apidog của bạn, nhóm của bạn chỉnh sửa chúng ở một nơi và quản lý phiên bản chúng với hỗ trợ nhánh.
CLI là cầu nối đến CI. Bạn xây dựng một kịch bản một lần, lấy ID kịch bản và môi trường của nó, và toàn bộ quá trình tích hợp CI chỉ là một lệnh apidog run duy nhất. Khi bạn cập nhật một bài kiểm tra trong Apidog, bản dựng Buildkite tiếp theo sẽ nhận thay đổi mà không cần chỉnh sửa YAML. Đặc tính chỉ một lệnh đó là điều khiến Apidog dễ dàng tích hợp vào Buildkite, GitHub Actions, hoặc bất kỳ hệ thống nào khác. Chúng tôi đề cập đến cùng một lệnh trên các nền tảng khác trong hướng dẫn pipeline CI/CD của Apidog CLI và hướng dẫn Apidog CLI với GitHub Actions.
Để thử nó từ máy của riêng bạn trước, trước khi tích hợp bất cứ thứ gì vào CI, hãy chạy lệnh tương tự cục bộ với mã thông báo của bạn:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html
Tải Apidog miễn phí, xây dựng một kịch bản kiểm thử, và đưa lệnh apidog run một dòng vào pipeline Buildkite của bạn.
Câu hỏi thường gặp
Buildkite là gì?
Buildkite là một nền tảng CI/CD với thiết kế lai. Một mặt phẳng điều khiển được lưu trữ chạy bảng điều khiển và điều phối các bản dựng, trong khi các tác nhân chạy các công việc thực tế. Các tác nhân có thể chạy trên cơ sở hạ tầng của riêng bạn hoặc trên điện toán được Buildkite lưu trữ. Nó không liên quan đến Docker BuildKit, một công cụ xây dựng hình ảnh riêng biệt mà tình cờ có tên tương tự.
Buildkite được sử dụng để làm gì?
Các nhóm sử dụng Buildkite để tự động hóa các công việc được kích hoạt bởi thay đổi mã: xây dựng artifact, chạy kiểm thử và triển khai. Nó phổ biến trong các nhóm muốn các bản dựng của họ chạy trên phần cứng của riêng họ hoặc bên trong mạng của riêng họ. Đối với các nhóm API, nó chạy các bài kiểm thử tự động trên môi trường staging và production và có thể chặn triển khai khi kiểm thử thất bại.
Buildkite có phải là mã nguồn mở không?
Tác nhân Buildkite là mã nguồn mở. Nó được viết bằng Go và phát hành theo Giấy phép MIT, với mã nguồn trên GitHub. Nền tảng và mặt phẳng điều khiển xung quanh tác nhân là một sản phẩm SaaS thương mại, vì vậy chỉ riêng tác nhân là mã nguồn mở.
Buildkite có miễn phí không?
Có, Buildkite có gói miễn phí tên là Personal. Nó không tốn phí ($0), không yêu cầu thẻ tín dụng và không có thời hạn. Nó bao gồm 3 công việc đồng thời, 1 người dùng, lưu trữ 90 ngày, 500 phút tác nhân Linux được lưu trữ mỗi tháng và 50.000 lượt chạy kiểm thử mỗi tháng. Ngoài ra còn có bản dùng thử All Access 30 ngày để đánh giá các tính năng trả phí.
Làm thế nào để bạn tải artifact lên trong Buildkite?
Bạn chạy buildkite-agent artifact upload "<pattern>" bên trong một bước lệnh. Đặt mẫu glob trong dấu ngoặc kép để tác nhân khớp nó thay vì shell. Các tệp được gửi đến bộ nhớ do Buildkite quản lý theo mặc định, với thời gian lưu trữ 6 tháng và giới hạn 5GB cho mỗi artifact. Đối với kiểm thử API, bạn tải lên báo cáo HTML để người xem có thể mở nó từ tab Artifacts của bản dựng.
Làm thế nào để chạy kiểm thử API trong một pipeline Buildkite?
Thêm một bước lệnh vào .buildkite/pipeline.yml để cài đặt Apidog CLI bằng npm install -g apidog-cli, sau đó chạy apidog run với ID kịch bản kiểm thử, ID môi trường qua -e, và -r html,cli cho các báo cáo. Truyền mã thông báo truy cập của bạn qua một Buildkite secret, và tải lên báo cáo HTML bằng buildkite-agent artifact upload để kết quả tồn tại sau bản dựng.