Blog

Cách chạy Test API tự động trên Bamboo CI từng bước

Thêm các kiểm thử API tự động vào Atlassian Bamboo CI. Xây dựng các kiểm thử nhận biết lược đồ trong Apidog, chạy chúng bằng Apidog CLI và làm thất bại bản dựng khi một hợp đồng bị vi phạm.

Ashley Innocent

Ashley Innocent

15 tháng 6 2026

Cách chạy Test API tự động trên Bamboo CI từng bước

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 dựng của bạn đã xanh. Các bài kiểm tra đơn vị (unit test) vượt qua, JAR được đóng gói, artifact được triển khai. Sau đó, yêu cầu thực tế đầu tiên gửi đến API staging và một dịch vụ hạ nguồn trả về lỗi 500 vì ai đó đã thay đổi một trường phản hồi cách đây hai commit. Bản dựng nói mọi thứ đều ổn. Nhưng thực tế không phải vậy. Nó chỉ chưa bao giờ kiểm tra API.

Đây là lỗ hổng mà hầu hết các pipeline CI của Bamboo mắc phải. Atlassian Bamboo giỏi trong việc biên dịch mã, chạy các bộ JUnit và gửi các artifact. Điều nó không tự làm được là xác minh rằng các điểm cuối HTTP của bạn vẫn hoạt động theo đúng hợp đồng đã cam kết. Nếu bạn muốn có mạng lưới an toàn đó, bạn phải thêm các bài kiểm tra API tự động như một giai đoạn trong pipeline. Hướng dẫn này sẽ chỉ cho bạn cách thực hiện điều đó, sử dụng Apidog để xây dựng các bài kiểm tra và Apidog CLI để chạy chúng trong một tác vụ Bamboo.

Cuối cùng, bạn sẽ có một kế hoạch Bamboo mà, với mỗi lần đẩy (push), sẽ truy cập các điểm cuối của bạn, kiểm tra mã trạng thái, xác thực nội dung phản hồi so với lược đồ của bạn và làm thất bại bản dựng ngay khi một hợp đồng bị vi phạm. Không cần giấy phép Postman cho mỗi người dùng, không cần duy trì các script kiểm định viết tay, và có một báo cáo kiểm thử HTML thực sự đính kèm với mỗi bản dựng. Tải Apidog nếu bạn muốn làm theo; phần CLI là miễn phí và mã nguồn mở.

nút

Tại sao các bài kiểm tra API nên có trong Bamboo, chứ không phải sau nó

Nhiều nhóm kiểm tra API của họ theo cách thủ công, hoặc tệ hơn là trong môi trường production. Ai đó nhấp qua một bộ sưu tập các yêu cầu đã lưu trước khi phát hành và kiểm tra nhanh các phản hồi. Điều đó có tác dụng cho đến khi không còn nữa. Mọi người quên. Các bản phát hành diễn ra vào thứ Sáu. Điểm cuối mà không ai nghĩ đến việc kiểm tra lại lại là điểm bị hỏng.

Bamboo CI

CI tồn tại để loại bỏ yếu tố con người đó. Mục đích của một máy chủ xây dựng là các kiểm tra tương tự chạy theo cùng một cách mỗi lần, tự động, mà không cần ai phải nhớ chạy chúng. Các bài kiểm tra đơn vị của bạn đã nằm ở đó. Các bài kiểm tra tích hợp của bạn có thể cũng vậy. Các bài kiểm tra API xứng đáng được đối xử tương tự, và vì một vài lý do cụ thể:

Bối cảnh sâu hơn là cùng một lý do các nhóm áp dụng CI/CD ngay từ đầu: bắt các vấn đề sớm, khi chúng còn rẻ để khắc phục, thay vì muộn, khi chúng tốn kém và đáng xấu hổ. Kiểm thử API chỉ là lớp của chiến lược đó mà hầu hết các pipeline bỏ qua.

Kiểm thử API phù hợp như thế nào vào một kế hoạch Bamboo

Trước khi đi vào từng bước, điều quan trọng là phải hiểu vị trí của nó trong mô hình của Bamboo. Bamboo tổ chức công việc thành các kế hoạch (plans), và mỗi kế hoạch chứa một hoặc nhiều giai đoạn (stages) chạy theo thứ tự. Mỗi giai đoạn chứa các tác vụ (jobs), và mỗi tác vụ là một chuỗi các nhiệm vụ (tasks). Các nhiệm vụ là các lệnh thực tế: checkout, compile, chạy một script.

Tác vụ Bamboo

Các bài kiểm tra API của bạn trở thành một nhiệm vụ (task) bên trong một tác vụ (job) bên trong một giai đoạn (stage). Vị trí tự nhiên là một giai đoạn chuyên dụng chạy sau khi ứng dụng của bạn được xây dựng và triển khai tới môi trường thử nghiệm, bởi vì bạn cần một thứ gì đó đang chạy để gửi yêu cầu đến. Một kế hoạch điển hình sẽ trông như thế này:

Kế hoạch: payments-service
├── Giai đoạn: Build
│   └── Tác vụ: Biên dịch & Kiểm tra đơn vị
│       ├── Nhiệm vụ: Tải mã nguồn
│       └── Nhiệm vụ: Maven, clean package
├── Giai đoạn: Triển khai đến Staging
│   └── Tác vụ: Triển khai
│       └── Nhiệm vụ: Triển khai artifact đến staging
└── Giai đoạn: Kiểm tra API           <- đây là phần bạn đang thêm
    └── Tác vụ: Chạy Bộ API
        ├── Nhiệm vụ: Tải mã nguồn
        ├── Nhiệm vụ: Script, cài đặt & chạy Apidog CLI
        └── Nhiệm vụ: Cuối cùng, xuất bản báo cáo kiểm thử

Nếu một nhiệm vụ trong giai đoạn Kiểm tra API thoát với mã không phải số không, Bamboo sẽ đánh dấu giai đoạn đó là thất bại và toàn bộ bản dựng sẽ chuyển sang màu đỏ. Đó chính xác là hành vi bạn muốn; một hợp đồng bị hỏng nên dừng lại, không được phép lọt qua.

Công cụ thực hiện công việc thực tế trong nhiệm vụ script đó là Apidog CLI, một trình chạy dòng lệnh thực thi các kịch bản kiểm thử mà bạn thiết kế trực quan trong Apidog. Bạn xây dựng bài kiểm thử một lần, trong giao diện người dùng đồ họa (GUI), không cần mã, và bài kiểm thử đó chạy không thay đổi trong terminal của bạn và trong Bamboo. Đây là cùng một mô hình mà các nhóm sử dụng để tự động hóa kiểm thử API trên bất kỳ hệ thống CI/CD nào; Bamboo là một trong nhiều mục tiêu.

Bước 1: Xây dựng các bài kiểm thử API của bạn trong Apidog

Bạn không thể chạy các bài kiểm thử trong CI cho đến khi bạn có các bài kiểm thử. Apidog là nơi bạn thiết kế chúng, và thiết kế này trực quan, vì vậy một kỹ sư QA không viết mã vẫn có thể xây dựng cùng một bộ kiểm thử mà một nhà phát triển backend sẽ làm.

Mở Apidog và tạo một kịch bản kiểm thử. Một kịch bản là một chuỗi các yêu cầu API được sắp xếp theo thứ tự, chạy từ trên xuống dưới, trong đó mỗi bước có thể sử dụng lại dữ liệu từ các bước trước đó. Một kịch bản thực tế cho dịch vụ thanh toán có thể là:

  1. POST /auth/login với thông tin đăng nhập hợp lệ, sau đó trích xuất bearer token từ phản hồi.
  2. POST /orders sử dụng token đó, tạo một đơn hàng mới, sau đó lưu orderId được trả về.
  3. GET /orders/{orderId} và xác nhận đơn hàng hiển thị với trạng thái chính xác.
  4. DELETE /orders/{orderId} để dọn dẹp.

Đối với mỗi yêu cầu, hãy thêm các xác nhận (assertions). Đây là phần biến một yêu cầu thành một bài kiểm thử. Apidog cho phép bạn xác nhận trực quan, không yêu cầu viết script:

Các xác nhận dựa trên lược đồ đáng được chú ý. Vì Apidog là schema-first, nó đã biết hình dạng mà điểm cuối của bạn đã cam kết trong định nghĩa API của nó. Bạn có thể xác nhận "phản hồi này khớp với lược đồ của nó" chỉ bằng một cú nhấp chuột, và kiểm tra duy nhất đó bảo vệ chống lại toàn bộ loại sai lệch hợp đồng, các trường được đổi tên, kiểu dữ liệu sai, thuộc tính bị bỏ qua, mà không cần bạn viết một dòng mã nào. Nếu bạn đang sử dụng một công cụ nặng về script, điều này thôi cũng đã giảm bớt rất nhiều công việc bảo trì. Đây là cùng một mô hình xác nhận trực quan khiến Apidog trở thành một giải pháp thay thế Postman phổ biến để kiểm thử API.

Nhóm các kịch bản liên quan vào một bộ kiểm thử nếu bạn có nhiều. Một bộ kiểm thử chỉ là một tập hợp các kịch bản mà bạn có thể chạy cùng nhau, điều này giúp lệnh CI của bạn đơn giản; bạn chỉ cần trỏ trình chạy vào một bộ kiểm thử thay vì liệt kê hai mươi kịch bản.

Sử dụng biến môi trường cho bất kỳ thứ gì thay đổi giữa môi trường cục bộ, staging và production: URL cơ sở, thông tin đăng nhập, khóa API. Định nghĩa một môi trường staging trong Apidog với baseUrl được đặt thành máy chủ staging của bạn. Bạn sẽ cho CLI biết môi trường nào cần sử dụng khi chạy, vì vậy cùng một kịch bản chính xác sẽ chạy trên staging trong Bamboo và trên localhost trên máy tính xách tay của bạn.

Bước 2: Tạo một mã thông báo truy cập Apidog và lấy các ID

Bamboo chạy không giao diện (headless) trên một tác nhân xây dựng (build agent). Nó không thể đăng nhập vào tài khoản Apidog của bạn thông qua trình duyệt, vì vậy CLI sẽ xác thực bằng mã thông báo truy cập thay thế.

Trong kịch bản kiểm thử của bạn, mở tab CI/CD. Nhấp vào Thêm mã thông báo truy cập, sau đó Tạo mã thông báo. Sao chép giá trị vào một nơi an toàn tạm thời; bạn sẽ lưu trữ nó như một biến Bamboo trong thời gian tới, chứ không dán vào một script. Mã thông báo là thứ cho phép một tác nhân xây dựng kéo và chạy các bài kiểm thử của dự án riêng tư của bạn.

Trong khi bạn ở trong tab CI/CD đó, Apidog sẽ tạo lệnh chạy đầy đủ cho bạn. Chọn "Command line" làm nhà cung cấp và nó sẽ in ra thứ bạn có thể sao chép trực tiếp, với ID kịch bản kiểm thử và ID dự án của bạn đã được điền sẵn. Lệnh đã sao chép đó là nền tảng cho nhiệm vụ Bamboo của bạn. Các phần bạn cần quan tâm:

Giữ lệnh đã tạo đó tiện dụng. Các bước tiếp theo sẽ điều chỉnh nó cho Bamboo.

Bước 3: Lưu mã thông báo dưới dạng biến kế hoạch Bamboo

Không bao giờ mã hóa cứng (hard-code) mã thông báo vào một nhiệm vụ script. Bất kỳ ai có quyền truy cập đọc vào kế hoạch, và bất kỳ ai đọc nhật ký bản dựng, đều có thể nhìn thấy nó.

Trong Bamboo, đi đến kế hoạch của bạn, mở Cấu hình Kế hoạch (Plan Configuration), và tìm tab Biến (Variables). Thêm một biến mới. Đặt tên rõ ràng như APIDOG_ACCESS_TOKEN và dán mã thông báo làm giá trị. Bamboo sẽ che giấu các biến có tên chứa password, secret hoặc token, vì vậy hãy đặt tên phù hợp và giá trị sẽ được ẩn trong nhật ký và giao diện người dùng.

Khi chạy, Bamboo hiển thị các biến kế hoạch cho các script dưới dạng biến môi trường, được thêm tiền tố và viết hoa, với dấu chấm trở thành dấu gạch dưới. Một biến có tên APIDOG_ACCESS_TOKEN có sẵn cho nhiệm vụ shell của bạn dưới dạng $bamboo_APIDOG_ACCESS_TOKEN. Bạn sẽ tham chiếu đến biến này, chứ không bao giờ là mã thông báo thô, trong script xây dựng.

Quy tắc vệ sinh tương tự áp dụng cho bất kỳ bí mật nào khác mà các bài kiểm thử của bạn cần; mật khẩu cơ sở dữ liệu, khóa API của bên thứ ba, bí mật ký. Hãy định nghĩa chúng dưới dạng biến Bamboo được che giấu và đọc chúng thông qua tiền tố môi trường bamboo_.

Bước 4: Thêm giai đoạn kiểm thử API và một nhiệm vụ script

Bây giờ hãy kết nối nó vào kế hoạch. Trong Cấu hình Kế hoạch (Plan Configuration), thêm một giai đoạn mới và gọi nó là Kiểm thử API (API Tests). Thêm một tác vụ (job) vào đó, sau đó thêm các nhiệm vụ (tasks) vào tác vụ theo thứ tự này.

Nhiệm vụ 1, Tải Mã nguồn (Source Code Checkout). Mặc dù các bài kiểm thử nằm trong đám mây của Apidog, việc tải kho lưu trữ của bạn sẽ cung cấp cho tác nhân một thư mục làm việc sạch sẽ và cho phép bạn commit bất kỳ tệp dữ liệu cục bộ nào (ví dụ: dữ liệu lặp CSV) cùng với mã của bạn.

Nhiệm vụ 2, Script. Đây là phần cốt lõi. Chọn một nhiệm vụ Script, đặt trình thông dịch là Shell (hoặc /bin/sh), và sử dụng nội dung script nội tuyến. Script này sẽ cài đặt Apidog CLI trên tác nhân và chạy kịch bản của bạn.

Apidog CLI là một gói npm, vì vậy tác nhân cần Node.js v16 trở lên. Nếu các tác nhân của bạn đã có Node, bạn có thể bỏ qua dòng cài đặt; nếu không, hãy cung cấp nó thông qua các khả năng của Bamboo hoặc một tác nhân dựa trên Docker. Dưới đây là nội dung script hoàn chỉnh:

#!/bin/sh
set -e

# Cài đặt Apidog CLI toàn cục trên tác nhân
npm install -g apidog-cli

# Chạy kịch bản kiểm thử trên môi trường staging, xuất báo cáo HTML + CLI
apidog run \
  --access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r cli,html \
  --out-dir ./apidog-reports

Thay thế 637132 bằng ID kịch bản kiểm thử thực của bạn và 358171 bằng ID môi trường staging của bạn, các giá trị từ lệnh Apidog đã tạo ở bước 2. Một vài ghi chú về chức năng của mỗi cờ:

set -e ở trên cùng rất quan trọng. Nó làm cho shell thoát ngay khi lệnh đầu tiên thất bại. Apidog CLI đã trả về mã thoát khác không khi bất kỳ xác nhận nào thất bại, và mã khác không đó là thứ báo cho Bamboo biết để làm thất bại bản dựng. Cùng nhau, chúng đảm bảo một hợp đồng API bị hỏng sẽ khiến bản dựng chuyển sang màu đỏ thay vì bị chôn vùi trong nhật ký.

Nếu bạn đã từng tích hợp kiểm thử API vào GitHub Actions trước đây, điều này sẽ quen thuộc; trình chạy và các cờ là giống hệt nhau, chỉ khác ở lớp bao bọc YAML so với giao diện người dùng Bamboo.

Bước 5: Xuất bản báo cáo kiểm thử dưới dạng một artifact Bamboo

Một bản dựng màu đỏ cho bạn biết có gì đó đã hỏng. Báo cáo HTML cho bạn biết cái gì đã hỏng. Hãy thiết lập để mỗi bản dựng giữ lại báo cáo này.

Trong cùng tác vụ đó, đi đến tab Artifacts và định nghĩa một artifact chia sẻ mới:

Sau mỗi bản dựng, Bamboo thu thập mọi thứ trong thư mục apidog-reports và đính kèm vào kết quả bản dựng. Mở bất kỳ bản dựng nào, đi đến tab Artifacts, và bạn có thể tải xuống hoặc xem báo cáo HTML; kết quả từng yêu cầu, các xác nhận đã chạy, và nội dung phản hồi chính xác cho bất kỳ thứ gì thất bại. Phần cuối cùng đó giúp tiết kiệm thời gian gỡ lỗi thực sự. Thay vì chạy lại yêu cầu thất bại bằng tay, bạn đọc phản hồi đã chụp được trực tiếp từ bản dựng.

Để hiển thị phong phú hơn trong Bamboo, trình báo cáo junit cũng hữu ích. Thêm junit vào danh sách -r, sau đó thêm một nhiệm vụ JUnit Parser trỏ đến tệp XML JUnit. Bamboo sau đó sẽ hiển thị số lượng kiểm thử, phân tích thành công/thất bại và xu hướng thất bại một cách tự nhiên trên bản tóm tắt bản dựng, giống như cách nó hiển thị kết quả kiểm thử đơn vị của bạn.

Bước 6: Chạy và đọc kết quả

Kích hoạt kế hoạch thủ công cho lần chạy đầu tiên; trong Bamboo, chọn Chạy kế hoạch (Run plan) từ trang kế hoạch. Theo dõi nhật ký bản dựng cho giai đoạn Kiểm thử API (API Tests). Bạn sẽ thấy npm cài đặt CLI, sau đó luồng đầu ra chạy của Apidog hiển thị, tên kịch bản, mỗi yêu cầu, mỗi xác nhận, và một dòng tóm tắt cuối cùng với tổng số.

Hai kết quả có thể xảy ra:

Tất cả các xác nhận đều vượt qua. CLI thoát với mã 0, giai đoạn chuyển sang màu xanh, bản dựng thành công và báo cáo HTML vẫn được đính kèm dưới dạng một artifact, vì vậy bạn có một bản ghi. Tốt. Bây giờ hãy làm cho nó tự động; đặt kế hoạch để kích hoạt trên mỗi commit vào nhánh chính của bạn (Cấu hình Kế hoạch, Trình kích hoạt, thăm dò kho lưu trữ hoặc webhook). Từ đây, mỗi lần đẩy sẽ chạy bộ API của bạn mà không cần sự can thiệp của con người.

Một xác nhận thất bại. CLI thoát với mã khác không, set -e dừng script, giai đoạn chuyển sang màu đỏ, và bản dựng thất bại. Mở artifact, tìm yêu cầu bị lỗi và đọc phản hồi đã chụp. Có thể một trường đã thay đổi. Có thể staging trả về 502 vì một dependency bị lỗi. Dù bằng cách nào, bạn sẽ biết trong vòng một hoặc hai phút kể từ commit đã gây ra lỗi, đó là toàn bộ lợi ích.

Một bản tóm tắt console thực tế trông như thế này:

┌──────────────┬──────────┬──────────┐
│              │ đã chạy   │ thất bại │
├──────────────┼──────────┼──────────┤
│   iterations │        1 │        0 │
├──────────────┼──────────┼──────────┤
│     requests │        4 │        0 │
├──────────────┼──────────┼──────────┤
│   assertions │       11 │        1 │
└──────────────┴──────────┴──────────┘

  1 xác nhận thất bại:
    GET /orders/{orderId}
      mong đợi $.data.status bằng "pending" nhưng nhận được "failed"

Xác nhận thất bại đó là toàn bộ lý do giai đoạn này tồn tại. Nó đã bắt được một lỗi hồi quy hợp đồng đã biên dịch sạch sẽ và vượt qua mọi bài kiểm thử đơn vị.

Làm cho bộ kiểm thử đáng tin cậy trong CI

Một bài kiểm thử API không ổn định (flaky) còn tệ hơn là không có kiểm thử, bởi vì nó khiến nhóm bỏ qua các bản dựng màu đỏ. Một vài thói quen giúp bộ kiểm thử đáng tin cậy.

Tổng kết

Bamboo đã bảo vệ bạn khỏi mã không biên dịch được và các bài kiểm thử đơn vị không vượt qua. Việc thêm một giai đoạn kiểm thử API mở rộng sự bảo vệ đó đến các hợp đồng mà dịch vụ của bạn thực sự phơi bày qua mạng, lớp mà hầu hết các sự cố "nhưng nó hoạt động cục bộ" thực sự xảy ra.

Việc thiết lập rất ngắn gọn: xây dựng các bài kiểm thử trực quan, nhận biết lược đồ trong Apidog, tạo một mã thông báo truy cập, lưu trữ nó dưới dạng biến Bamboo được che giấu, và thêm một nhiệm vụ script chạy apidog run với ID kịch bản và môi trường của bạn. Xuất bản báo cáo dưới dạng một artifact, chặn giai đoạn triển khai của bạn đằng sau nó, và kích hoạt kế hoạch trên mỗi commit. Sau đó mọi thứ sẽ tự động. Mỗi lần đẩy sẽ kiểm tra API của bạn, và một hợp đồng bị hỏng sẽ làm cho bản dựng chuyển sang màu đỏ trước khi nó có thể biến thành một sự cố gián đoạn.

Tải Apidog và xây dựng kịch bản kiểm thử đầu tiên của bạn, sau đó thả lệnh CLI đã tạo vào một nhiệm vụ script Bamboo. Lần đầu tiên nó bắt được một lỗi hồi quy đã biên dịch sạch sẽ, giai đoạn đó sẽ xứng đáng với mười phút đã bỏ ra để thiết lập.

nút

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