API của bạn hoạt động tốt trên máy của bạn. Các bài kiểm thử đơn vị (unit test) đều thành công. Bạn hợp nhất, triển khai, và một giờ sau một đồng nghiệp báo cho bạn: endpoint /checkout trả về lỗi 500 cho bất kỳ ai có giỏ hàng trống. Lỗi đó không bao giờ nằm trong mã bạn đã thay đổi; nó nằm ở một giao kèo cách đó hai dịch vụ mà không ai kiểm tra lại. Đây là khoảng trống mà các bài kiểm thử API cấp độ tích hợp (integration-level API tests) lấp đầy, và đây chính xác là loại kiểm tra bạn muốn chạy tự động trên mỗi lần commit thay vì chỉ trong suy nghĩ của ai đó.
Travis CI là một trong những dịch vụ tích hợp liên tục (continuous integration) được lưu trữ lâu đời nhất, và nó vẫn làm tốt một điều: nó theo dõi kho lưu trữ Git của bạn, tạo ra một môi trường sạch cho mỗi lần đẩy (push) và yêu cầu hợp nhất (pull request), và chạy bất kỳ lệnh nào bạn đặt trong tệp .travis.yml. Hầu hết các nhóm sử dụng nó cho các vòng lặp biên dịch và kiểm thử đơn vị. Rất ít người sử dụng nó để chạy các bài kiểm thử HTTP thực tế đối với một API đang hoạt động, mặc dù đó là nơi ẩn chứa những lỗi tốn kém. Lý do là sự phức tạp. Kết nối một trình chạy kiểm thử API vào một hệ thống CI, truyền bí mật một cách an toàn, và nhận tín hiệu đạt/không đạt trở lại là những việc đủ rắc rối khiến mọi người bỏ qua.
Hướng dẫn này sẽ chỉ ra cách khắc phục khoảng trống đó với trình chạy dòng lệnh Apidog. Bạn thiết kế và gỡ lỗi các bài kiểm thử API của mình trong ứng dụng desktop Apidog, nơi bạn có thể thấy các yêu cầu và xác nhận một cách trực quan, sau đó chạy chính xác các bài kiểm thử đó một cách tự động bên trong Travis CI chỉ với một lệnh duy nhất. Không cần viết lại logic kiểm thử dưới dạng mã, không cần duy trì một công cụ kiểm thử riêng biệt. Bài viết bao gồm toàn bộ quá trình: một tệp .travis.yml tối thiểu, cài đặt trình chạy, truyền token truy cập của bạn một cách an toàn, chọn những gì cần chạy, tạo báo cáo và làm cho quá trình xây dựng (build) thất bại rõ ràng khi một endpoint bị lỗi. Tải Apidog nếu bạn muốn làm theo.
Tại sao cần chạy các bài kiểm thử API trong CI
Kiểm thử đơn vị (Unit test) xác nhận một hàm trả về giá trị đúng. Kiểm thử API xác nhận toàn bộ chu trình yêu cầu-phản hồi hoạt động đúng: route tồn tại, xác thực được thực thi, mã trạng thái (status code) chính xác, lược đồ JSON khớp, và các giá trị bên trong phần thân (body) hợp lệ. Đây là những chế độ lỗi khác nhau, và loại thứ hai là loại mà người dùng của bạn thực sự gặp phải.
Chạy chúng cục bộ thì tốt cho đến khi không còn tốt nữa. Việc chạy cục bộ phụ thuộc vào việc bạn nhớ chạy chúng, vào việc máy của bạn khớp với cấu hình sản xuất, và vào việc bạn không đang uống cà phê dở dang khi một lỗi hồi quy (regression) lọt qua. Tích hợp liên tục loại bỏ cả ba lý do này. Mỗi lần đẩy (push) sẽ kích hoạt cùng một bộ kiểm thử trong cùng một môi trường, và kết quả được đính kèm vào commit và pull request để mọi người cùng xem.
Có một lợi ích sâu sắc hơn đặc biệt dành cho các nhóm API. Khi các bài kiểm thử của bạn tồn tại song song với thiết kế API của bạn, một thay đổi gây lỗi (breaking change) sẽ xuất hiện dưới dạng một xác nhận thất bại ngay khi nó được đẩy, chứ không phải dưới dạng một phiếu hỗ trợ (support ticket). Nếu bạn muốn tìm hiểu nền tảng khái niệm về vị trí của điều này trong một quy trình phân phối, bài giải thích CI/CD là gì là một tài liệu đọc bổ ích; bài viết này tập trung vào việc xây dựng Travis CI thực tế.
Những gì bạn cần trước khi bắt đầu
Ba điều, và có lẽ bạn đã có sẵn hai trong số đó.
- Một kho lưu trữ Git được kết nối với Travis CI. Gói miễn phí trên
travis-ci.comhoạt động cho các kho lưu trữ công khai và riêng tư trong giới hạn sử dụng.

- Một dự án Apidog với ít nhất một kịch bản kiểm thử (test scenario) bạn đã xây dựng và chạy thành công trong ứng dụng desktop. Một kịch bản kiểm thử trong Apidog là một tập hợp các yêu cầu API được sắp xếp theo thứ tự với các xác nhận (assertions); hãy coi đó là một luồng end-to-end, ví dụ như “đăng nhập, tạo đơn hàng, lấy đơn hàng, xóa nó.”
- Node.js. Apidog CLI chạy trên Node, và nó cần phiên bản 16 trở lên. Travis cung cấp Node sẵn có trong môi trường ngôn ngữ
node_js, vì vậy đây chủ yếu là một khai báo một dòng.
Nếu bạn chưa xây dựng kịch bản kiểm thử nào, hãy thực hiện điều đó trước trong ứng dụng. Toàn bộ ý nghĩa của quy trình làm việc này là bạn gỡ lỗi trực quan một lần, sau đó tự động hóa mãi mãi. Cố gắng viết kiểm thử mù quáng bên trong nhật ký CI là con đường chậm chạp. Để nắm vững các nguyên tắc cơ bản của việc viết các kiểm tra tốt, Xác nhận API: hướng dẫn thực hành bao gồm cách xác thực mã trạng thái, phần thân phản hồi và lược đồ JSON trước khi bạn đẩy mã.
Bước 1: Lấy mã truy cập (access token) và ID kịch bản (scenario ID) của bạn
Apidog CLI chạy các bài kiểm thử được lưu trữ trên đám mây của bạn một cách tự động, vì vậy nó cần hai phần thông tin nhận dạng:
- Mã truy cập (access token) để chứng minh trình chạy được phép đọc dự án của bạn. Tạo nó từ cài đặt tài khoản Apidog của bạn trong phần mã truy cập. Hãy coi nó như một mật khẩu; nó cấp quyền truy cập API vào dữ liệu dự án của bạn.
- ID kịch bản kiểm thử. Mở kịch bản trong ứng dụng desktop và sao chép ID của nó, hoặc sử dụng tùy chọn “Run in CI/CD”, tùy chọn này sẽ tạo ra một lệnh sẵn có với ID đã được điền sẵn.
Cách dễ nhất để có được một lệnh đầu tiên chính xác là để Apidog viết nó cho bạn. Bên trong một kịch bản kiểm thử, tùy chọn chạy CI/CD tạo ra thứ gì đó như thế này:
apidog run --access-token <your-access-token> -t 5564321 -e 4417023 -r cli
Đó là toàn bộ cấu trúc của nó: xác thực, trỏ đến một kịch bản (-t), trỏ đến một môi trường (-e), và chọn một trình báo cáo (-r). Sao chép lệnh đó, xác nhận nó chạy trên máy tính xách tay của bạn trước, và chỉ sau đó mới đưa nó vào Travis. Xác minh cục bộ giúp bạn tiết kiệm hàng tá bản dựng thất bại do gỡ lỗi lỗi chính tả trong mã token.
Bước 2: Lưu mã token dưới dạng biến mã hóa trong Travis
Không bao giờ dán mã truy cập của bạn vào .travis.yml. Tệp đó được commit vào Git, và một mã token bị rò rỉ sẽ cấp quyền đọc dự án API của bạn cho bất kỳ ai. Travis có hai tùy chọn an toàn.
Cách an toàn là sử dụng các biến môi trường của kho lưu trữ được thiết lập trong giao diện web của Travis. Truy cập cài đặt kho lưu trữ của bạn trên Travis, tìm các biến môi trường, và thêm:
APIDOG_ACCESS_TOKENvới giá trị token của bạnAPIDOG_ENV_IDvới ID môi trường bạn muốn kiểm thử
Để tùy chọn “hiển thị giá trị trong nhật ký build” tắt để token không bao giờ được in ra. Travis chèn các biến này vào mỗi bản dựng dưới dạng biến môi trường thực, và cấu hình của bạn tham chiếu chúng bằng tên. Điều này giữ bí mật hoàn toàn khỏi kho lưu trữ, đây là hành vi bạn mong muốn; nếu một người đóng góp fork kho lưu trữ, token của bạn sẽ không bị sao chép theo.
Nếu bạn thích mọi thứ nằm trong tệp, Travis cũng hỗ trợ các biến được mã hóa thông qua CLI của nó:
travis encrypt APIDOG_ACCESS_TOKEN="your-token-here" --add env.global
Điều này ghi một khối dữ liệu được mã hóa vào .travis.yml mà chỉ bản dựng của kho lưu trữ của bạn mới có thể giải mã. Cả hai cách tiếp cận đều hoạt động. Cách sử dụng giao diện người dùng đơn giản hơn cho hầu hết các nhóm và dễ dàng thay đổi khi token hết hạn.
Bước 3: Viết tệp .travis.yml
Dưới đây là một cấu hình hoàn chỉnh, tối thiểu để cài đặt Apidog CLI và chạy một kịch bản trên mỗi lần đẩy (push) và yêu cầu hợp nhất (pull request):
language: node_js
node_js:
- "18"
cache:
npm: true
install:
- npm install -g apidog-cli
script:
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli
Ba khối thực hiện công việc. language: node_js với một phiên bản cung cấp cho bạn một môi trường Node đủ mới cho CLI. Bước install cài đặt apidog-cli toàn cục để lệnh apidog có trong đường dẫn. Bước script chạy các bài kiểm thử của bạn. Trình báo cáo -r cli in một bản tóm tắt đạt/không đạt dễ đọc trực tiếp vào nhật ký Travis, đó là những gì bạn sẽ nhìn vào khi có lỗi xảy ra.
Lưu ý rằng ID kịch bản được mã hóa cứng nhưng các bí mật (secrets) đến từ các biến môi trường. Đó là sự phân tách đúng đ đắn: ID không nhạy cảm, token thì có. Commit tệp này, đẩy (push), và Travis sẽ tự động chạy các bài kiểm thử API của bạn. Bản dựng xanh đầu tiên là thời điểm API của bạn có một mạng lưới an toàn.
Nếu bạn duy trì một số dịch vụ và muốn có một mô hình tư duy chung giữa các trình chạy, hướng dẫn tự động hóa kiểm thử API trong CI/CD cho thấy cùng một mẫu được áp dụng cho các nền tảng khác, và phiên bản GitHub Actions gần như tương đồng về tinh thần nếu bạn có ý định di chuyển.
Bước 4: Làm cho bản dựng thất bại khi một bài kiểm thử thất bại
Đây là phần mà các nhóm thường quên, và nó âm thầm làm mất đi toàn bộ ý nghĩa của việc này. Một công việc CI chỉ hữu ích nếu một bài kiểm thử thất bại làm cho bản dựng chuyển sang màu đỏ. Nếu trình chạy luôn thoát với mã 0 bất kể điều gì, bạn đã tạo ra một trình in nhật ký rất tốn kém.
Tin tốt: Apidog CLI đã làm đúng điều này. Khi một xác nhận (assertion) thất bại, tiến trình apidog run thoát với mã trạng thái khác 0, và Travis coi bất kỳ thoát khác 0 nào trong giai đoạn script là một lỗi bản dựng. Vì vậy, cấu hình tối thiểu ở trên đã thất bại đúng cách ngay từ đầu. Bạn không cần thêm bất kỳ sự can thiệp nào.
Điều bạn có thể điều chỉnh là cách chạy hoạt động giữa kịch bản khi một yêu cầu duy nhất gặp lỗi. Cờ (flag) --on-error điều khiển điều này:
--on-error enddừng kịch bản ở lỗi đầu tiên. Phản hồi nhanh nhất, ít đầu ra hơn.--on-error continuechạy các bước còn lại để bạn thấy mọi lỗi trong một lần chạy.--on-error ignoretiếp tục chạy và không để lỗi làm dừng quá trình.
Đối với CI, continue thường là lựa chọn tối ưu: bạn muốn có cái nhìn đầy đủ về những gì đã hỏng mà không làm gián đoạn công việc sau xác nhận lỗi đầu tiên, đồng thời vẫn kết thúc với mã thoát khác 0 để bản dựng thất bại. Một dòng lệnh script hợp lý trông như thế này:
script:
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli --on-error continue
Tránh cám dỗ thêm || true vào lệnh để “làm cho bản dựng thành công.” Điều đó sẽ nuốt mất mã thoát và tái tạo chính xác điểm mù mà bạn đã muốn loại bỏ.
Bước 5: Tạo và giữ lại báo cáo HTML
Trình báo cáo cli tốt cho việc xem nhanh, nhưng khi một bản dựng thất bại, bạn thường muốn một tạo phẩm phong phú hơn: yêu cầu nào, xác nhận nào, phần thân phản hồi thực tế là gì. CLI tạo ra một báo cáo HTML với trình báo cáo html, và bạn có thể xếp chồng các trình báo cáo trong một lần chạy.
script:
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli,html --out-dir ./apidog-reports
-r cli,html in ra nhật ký và ghi một tệp HTML độc lập. --out-dir đặt nơi báo cáo được lưu, mặc định là ./apidog-reports. Để báo cáo đó tồn tại sau khi bản dựng kết thúc, hãy triển khai nó đến một nơi Travis có thể xuất bản, chẳng hạn như một S3 bucket hoặc GitHub Pages, trong một khối deploy. Một mẫu phổ biến:
deploy:
provider: pages
skip_cleanup: true
github_token: $GITHUB_TOKEN
local_dir: apidog-reports
on:
branch: main
Nếu bạn không muốn quản lý bộ lưu trữ tạo phẩm (artifact) chút nào, CLI có thể đẩy báo cáo lên đám mây Apidog với --upload-report, nơi nhóm của bạn có thể mở nó từ một liên kết mà không cần bất kỳ dịch vụ lưu trữ bổ sung nào. Đó là tùy chọn ít bảo trì nhất cho các nhóm phân tán.
Bước 6: Thêm môi trường, dữ liệu và chạy ma trận (matrix runs)
Một kịch bản đơn lẻ chống lại một môi trường đơn lẻ là một khởi đầu tốt. Các quy trình (pipeline) thực tế phát triển theo ba hướng, và các cờ CLI ánh xạ rõ ràng vào từng hướng.
- Nhiều môi trường. Cờ
-echọn các URL cơ sở và biến của môi trường nào sẽ sử dụng. Chạy cùng một kịch bản đối với môi trường staging trên mỗi lần đẩy và đối với môi trường production trên một bản dựng cron hàng đêm bằng cách hoán đổi ID môi trường. Các công việc cron của Travis được cấu hình cho mỗi kho lưu trữ trong giao diện cài đặt người dùng (UI). - Chạy theo dữ liệu (Data-driven runs). Cờ
-d(dạng dài--iteration-data) đưa một tệp CSV hoặc JSON vào kịch bản của bạn để nó chạy một lần cho mỗi hàng. Đây là cách bạn bao quát các trường hợp biên: đầu vào hợp lệ, các trường bị thiếu, tải trọng quá lớn, ký tự đặc biệt, tất cả từ một định nghĩa kịch bản duy nhất. Kết hợp nó với-n(--iteration-count) khi bạn muốn một số lần lặp cố định thay vì các lần lặp dựa trên tệp.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -d ./test-data.csv -r cli
- Các kịch bản song song. Ma trận bản dựng (build matrices) của Travis cho phép bạn chạy nhiều kịch bản cùng một lúc trên các công việc song song. Xác định một ma trận biến môi trường trong đó mỗi mục mang một ID kịch bản khác nhau, và mỗi công việc ma trận chạy một kịch bản. Bản dựng chỉ chuyển sang màu xanh (thành công) khi tất cả chúng đều vượt qua.
env:
- SCENARIO_ID=5564321 # checkout flow
- SCENARIO_ID=5564322 # auth flow
- SCENARIO_ID=5564323 # search flow
script:
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t $SCENARIO_ID -e $APIDOG_ENV_ID -r cli
Khi các bộ kiểm thử phát triển, việc tổ chức các kịch bản thành bộ kiểm thử cho kiểm thử API tự động giúp ma trận dễ quản lý hơn thay vì trở thành một bức tường toàn ID.
Tại sao cách này vượt trội hơn việc viết mã kiểm thử thủ công trong script CI của bạn
Bạn có thể viết các bài kiểm thử API trực tiếp trong một script Travis bằng curl và jq, hoặc dưới dạng chạy Newman của một collection đã xuất. Cả hai cách đều hoạt động, và cả hai đều lỗi thời nhanh chóng.
Cách tiếp cận curl-cộng-shell biến mỗi xác nhận (assertion) thành một phép so sánh chuỗi dễ vỡ. Kiểm tra một trường JSON lồng nhau trở thành một câu thần chú jq; kiểm tra một lược đồ về cơ bản là không thể; và ngay khi API của bạn thêm một trường, một nửa các lệnh grep của bạn cần phải viết lại. Cuối cùng, bạn phải duy trì một bản sao thứ hai, tệ hơn của kiến thức API của mình trong Bash.
Cách tiếp cận trình chạy collection tốt hơn nhưng lại gắn CI của bạn vào một nghi thức xuất và đồng bộ hóa: chỉnh sửa các bài kiểm thử trong một công cụ, xuất, commit tệp JSON, hy vọng nó không lệch khỏi thực tế. Sự lệch lạc là có thật, và đó là nguồn gốc của những lời phàn nàn “các bài kiểm thử thành công nhưng API bị hỏng”. Chúng tôi đã viết về chế độ lỗi chính xác này trong bài tại sao các Postman collections của bạn không phải là nguồn sự thật duy nhất, và nếu bạn đang chạy collections trong CI ngày nay, cách chạy Postman collections trong CI mà không cần Newman sẽ đề cập đến lộ trình di chuyển.
Mô hình Apidog khép kín vòng lặp. Các bài kiểm thử, thiết kế API, môi trường và máy chủ giả lập (mock servers) của bạn đều nằm ở một nơi. CLI chạy phiên bản trực tiếp, hiện tại của các bài kiểm thử đó; không có gì để xuất và không có gì để lệch lạc. Bạn gỡ lỗi một xác nhận không ổn định một cách trực quan trong ứng dụng, lưu lại và lần chạy CI tiếp theo sẽ nhận thay đổi. Nguồn sự thật duy nhất đó là toàn bộ lý do để sử dụng một trình chạy được xây dựng chuyên dụng thay vì một đống script shell. Nếu bạn đang đánh giá nó so với thiết lập hiện tại của mình, tổng hợp các lựa chọn thay thế Postman tốt nhất để kiểm thử API sẽ đặt các tùy chọn cạnh nhau.
Lưu ý về Travis CI nói riêng
Travis đã từng là CI mã nguồn mở mặc định trong nhiều năm, và rất nhiều kho lưu trữ cũ vẫn chạy trên đó. Nếu bạn bắt đầu mới vào năm 2026, điều đáng biết là lĩnh vực này đã thay đổi; GitHub Actions, GitLab CI và CircleCI hiện đang hỗ trợ hầu hết các dự án mới, và bài so sánh các công cụ CI/CD tốt nhất của chúng tôi phân tích từng công cụ phù hợp ở đâu. Tin tốt là Apidog CLI được thiết kế không phụ thuộc nền tảng. Lệnh apidog run chính xác hoạt động trong tệp .travis.yml của bạn cũng hoạt động trong bước GitHub Actions, tệp .gitlab-ci.yml của GitLab, hoặc một giai đoạn Jenkins. Nếu bạn di chuyển khỏi Travis, các bài kiểm thử API của bạn sẽ di chuyển theo mà không thay đổi; chỉ có các khóa YAML xung quanh là khác. Khả năng di động đó là một lợi ích thầm lặng nhưng thực sự của việc giữ logic kiểm thử tách biệt khỏi cú pháp cụ thể của CI.
Các câu hỏi thường gặp
Tôi có cần cài đặt ứng dụng desktop Apidog trên máy chủ CI không? Không. Ứng dụng desktop dùng để thiết kế và gỡ lỗi các bài kiểm thử. Travis chỉ cần gói npm apidog-cli và môi trường chạy Node 16+, điều mà môi trường ngôn ngữ node_js đã cung cấp. CLI sẽ lấy và chạy các kịch bản được lưu trữ trên đám mây của bạn một cách tự động.
Tôi tìm mã truy cập và ID kịch bản ở đâu? Tạo mã truy cập trong cài đặt tài khoản Apidog của bạn trong phần mã truy cập. ID kịch bản hiển thị trong ứng dụng desktop trên mỗi kịch bản kiểm thử; tùy chọn “Run in CI/CD” tích hợp sẵn cũng tạo ra một lệnh hoàn chỉnh với ID được điền sẵn, đây là cách nhanh nhất để có được một bản cơ sở hoạt động.
Làm thế nào để tôi giữ mã token khỏi kho lưu trữ của mình? Đặt nó làm biến môi trường kho lưu trữ trong giao diện web của Travis với hiển thị nhật ký build tắt, sau đó tham chiếu nó dưới dạng $APIDOG_ACCESS_TOKEN trong cấu hình của bạn. Ngoài ra, hãy sử dụng travis encrypt để lưu trữ một giá trị được mã hóa trong .travis.yml. Không bao giờ commit mã token thô.
Bản dựng có thực sự thất bại nếu một bài kiểm thử thất bại không? Có. Lệnh apidog run thoát với mã khác 0 khi một xác nhận (assertion) thất bại, và Travis coi bất kỳ thoát khác 0 nào trong giai đoạn script là một bản dựng thất bại. Chỉ cần đừng chặn mã thoát bằng || true. Sử dụng --on-error continue nếu bạn muốn mọi lỗi được báo cáo trong một lần chạy duy nhất mà bản dựng vẫn thất bại.
Tôi có thể chạy kiểm thử đối với nhiều môi trường hoặc với nhiều bộ dữ liệu không? Có. Sử dụng -e để chuyển đổi môi trường (staging khi đẩy, production trên một cron hàng đêm), -d để đưa một tệp dữ liệu CSV hoặc JSON vào cho các lần lặp theo dữ liệu, và một ma trận build của Travis để chạy nhiều kịch bản trong các công việc song song.
Tôi có thể sử dụng điều này nếu tôi không dùng Travis CI không? Có. Lệnh CLI giống hệt nhau trên các nền tảng. Thay thế YAML xung quanh cho GitHub Actions, GitLab CI, hoặc Jenkins và dòng apidog run vẫn giữ nguyên.
Tóm tắt
Đưa các bài kiểm thử API vào Travis CI gói gọn trong bốn bước: lưu mã truy cập của bạn dưới dạng biến được mã hóa, cài đặt apidog-cli trong bước cài đặt, chạy kịch bản của bạn với apidog run trong bước script, và để mã thoát khác 0 làm thất bại bản dựng. Từ đó, bạn có thể thêm các báo cáo HTML, nhiều môi trường, các lần lặp theo dữ liệu, và một ma trận song song khi bộ kiểm thử của bạn phát triển.
Lý do để thực hiện điều này với một trình chạy chuyên dụng thay vì một loạt các lệnh gọi curl là nguồn sự thật duy nhất. Bạn thiết kế và gỡ lỗi trực quan, sau đó chạy phiên bản trực tiếp của chính xác các bài kiểm thử đó trên mỗi lần commit, không có bước xuất để tránh bị lệch lạc. Lỗi hồi quy của /checkout của bạn sẽ được phát hiện trên pull request, chứ không phải trong môi trường sản xuất.
Xây dựng kịch bản kiểm thử đầu tiên của bạn, sau đó tải Apidog và tích hợp nó vào lần đẩy tiếp theo của bạn. Khi bản dựng đầu tiên thành công, mỗi commit sau đó sẽ được bảo vệ.
