Cách cài đặt Apidog Self-Hosted Runner để chạy kiểm thử API theo lịch trình

Bộ kiểm thử API của bạn chỉ hữu ích nếu nó chạy theo một lịch trình mà bạn có thể tin cậy. Một bộ sưu tập mà bạn tự kích hoạt sẽ bắt lỗi khi bạn nhớ nhấp chuột. Một lần chạy hàng đêm trên máy bạn kiểm soát sẽ bắt chúng vào lúc 2 giờ sáng, trước khi người dùng của bạn phát hiện ra. Đó là công việc của Apidog runner: một dịch vụ tự triển khai, được cài đặt bằng Docker trên máy chủ của riêng bạn, thực thi các kịch bản kiểm thử đã lên lịch mà bạn xây dựng trong Apidog và đẩy các báo cáo trở lại dự án của bạn.

Chúng tôi đã đề cập đến ba cách để lên lịch kiểm thử trong Apidog trong hướng dẫn lên lịch kiểm thử API tự động của chúng tôi. Bài viết đó so sánh việc thực thi trên đám mây, runner và CLI ở mức độ tổng quát. Bài viết này sẽ đi sâu vào đường dẫn runner: khi nào bạn cần nó, cách triển khai nó, cách trỏ một tác vụ đã lên lịch vào nó và cách nó so sánh với các lựa chọn thay thế.

Khi bạn cần một trình chạy kiểm thử tự lưu trữ (self-hosted)

Thực thi trên đám mây tiện lợi, nhưng ba tình huống sau đây thúc đẩy các nhóm chuyển sang sử dụng trình chạy kiểm thử tự lưu trữ.

API của bạn nằm trên một mạng riêng. Một môi trường staging tại https://orders.staging.internal:8443 không thể phân giải từ internet công cộng. Không có dịch vụ đám mây nào có thể truy cập được nó. Một runner được triển khai bên trong VPC hoặc mạng văn phòng của bạn có thể làm được, vì nó thực hiện các yêu cầu từ vị trí của nó. Đây là lý do tương tự đằng sau việc chạy một máy chủ giả lập tự lưu trữ trên mạng nội bộ của bạn: khối lượng công việc phải nằm ở nơi có quyền truy cập mạng.

Tuân thủ quy định giữ lưu lượng truy cập nội bộ. Nếu nhóm bảo mật của bạn cấm các tải trọng kiểm thử chứa dữ liệu khách hàng thực tế rời khỏi hạ tầng của bạn, thì việc thực thi trên đám mây là không thể. Với runner, các yêu cầu bắt nguồn từ máy chủ của bạn và truy cập trực tiếp vào API của bạn. Chỉ có các báo cáo kiểm thử mới được gửi về Apidog.

Bạn muốn có lịch trình ổn định không phụ thuộc vào bất kỳ máy tính xách tay nào. Các kiểm thử được lên lịch trong ứng dụng máy tính để bàn sẽ dừng khi ứng dụng đóng. Các kiểm thử được tích hợp vào CI sẽ chạy khi ai đó đẩy mã. Cả hai đều không mang lại cho bạn trạng thái "mỗi 6 giờ, mãi mãi, bất kể điều gì." Một runner trên một máy chủ luôn hoạt động sẽ làm chính xác điều này.

Nếu không có điều nào trong số này áp dụng, có lẽ bạn không cần runner. Các lần chạy thủ công trong ứng dụng hoặc CLI trong CI sẽ giải quyết vấn đề của bạn.

Apidog runner là gì

Runner tự lưu trữ là một dịch vụ tự động hóa mà bạn triển khai trên một máy chủ độc lập. Sau khi được kết nối với nhóm của bạn, nó có thể:

• Chạy các tác vụ kiểm thử tự động theo lịch trình được xây dựng từ các kịch bản kiểm thử Apidog của bạn
• Nhập tài liệu API theo lịch trình định kỳ
• Cung cấp phản hồi giả lập tự lưu trữ

Nó có hai phạm vi. Một runner chung cấp độ nhóm thuộc về một nhóm. Một runner cấp độ tổ chức có thể được chia sẻ trên tất cả các dự án trong các nhóm của tổ chức bạn. Việc triển khai hoạt động theo cùng một cách cho cả hai.

Mô hình tư duy quan trọng: runner là một worker, không phải là một bản sao của dự án của bạn. Các kịch bản kiểm thử, môi trường và xác nhận của bạn vẫn nằm trong Apidog. Runner nhận các tác vụ, thực thi chúng trên bất kỳ mạng nào nó có thể tiếp cận và tải kết quả lên. Các thành viên trong nhóm không bao giờ SSH vào đó để xem điều gì đã xảy ra; họ mở lịch sử chạy trong ứng dụng.

Điều kiện tiên quyết

Kiểm tra những điều này trước khi bạn triển khai. Chúng đến trực tiếp từ tài liệu môi trường triển khai runner.

Phần cứng. Tối thiểu 2 lõi CPU và 4 GB RAM; khuyến nghị 4+ lõi và 8 GB nếu bạn sẽ chạy các tác vụ đồng thời hoặc có một nhóm lớn hơn. Dành ít nhất 30 GB đĩa cho nhật ký và các tạo phẩm kiểm thử, 50 GB để thoải mái.

Docker. Máy chủ cần Docker phiên bản 20.10.0 trở lên, với 20.10.13 được khuyến nghị. Nếu máy chủ còn mới, trước tiên hãy làm theo hướng dẫn cài đặt Docker Engine chính thức cho bản phân phối của bạn.

Mạng. Runner giao tiếp với máy chủ Apidog qua HTTPS trên cổng 443 và duy trì kết nối WebSocket (WSS) mở để phân phối tác vụ theo thời gian thực. Nó cũng cần quyền truy cập ra ngoài đến các miền AWS được sử dụng để tải lên báo cáo, cộng với, rõ ràng là, khả năng truy cập mạng đến mọi API mà kiểm thử của bạn nhắm đến. Lưu ý hướng ở đây: runner thực hiện kết nối ra ngoài. Bạn không cần mở các cổng vào để Apidog tiếp cận nó, điều này giúp các cuộc trao đổi về tường lửa với nhóm vận hành của bạn trở nên ngắn gọn.

Quyền và gói dịch vụ. Triển khai runner là một hành động tài nguyên của nhóm, vì vậy bạn sẽ cần vai trò nhóm phù hợp. Số lượng lần chạy tác vụ theo lịch trình mà bạn nhận được phụ thuộc vào cấp độ gói đăng ký của bạn; kiểm tra trang giá Apidog để biết giới hạn hiện tại cho mỗi gói.

Bước 1: lấy lệnh triển khai từ Apidog

Apidog tạo lệnh triển khai Docker cho bạn, với mã thông báo xác thực được tích hợp sẵn. Đừng sao chép từ một bài đăng trên blog, bao gồm cả bài này; mã thông báo là thứ liên kết container với nhóm của bạn.

1. Mở Apidog và truy cập trang chủ Apidog. Nếu bạn chưa có tài khoản, hãy tải Apidog miễn phí để làm theo.
2. Chọn nhóm mà runner sẽ thuộc về.
3. Nhấp vào Tài nguyên (Resources) ở phía bên phải.
4. Nhấp vào Triển khai Runner chung (Deploy General Runner).

Một cửa sổ bật lên hiển thị lệnh triển khai đầy đủ. Sao chép nó ngay lập tức: nó chứa một mã thông báo nhạy cảm và chỉ hiển thị một lần. Hãy coi nó như một bí mật CI, không phải là một đoạn mã cho wiki nhóm của bạn.

Trước khi sao chép, hộp thoại cho phép bạn tùy chỉnh lệnh:

• Hệ điều hành máy chủ: Linux, macOS hoặc Windows.
• Biến thể hình ảnh: General đi kèm với Node.js 18, Java 21, Python 3 và PHP 8, vì vậy các tập lệnh tiền/hậu xử lý bằng các ngôn ngữ đó hoạt động mà không cần thiết lập thêm. Slim chỉ bao gồm Node.js 18 và tải nhanh hơn. Custom cho phép bạn cung cấp Dockerfile của riêng mình khi các kiểm thử phụ thuộc vào chứng chỉ CA nội bộ hoặc các thư viện bất thường.
• Cổng hiển thị: ánh xạ một cổng với -p (ví dụ -p 80:4524) nếu bạn cũng sẽ sử dụng runner cho các mô phỏng tự lưu trữ.
• Thư mục dữ liệu được gắn kết: thêm một gắn kết ổ đĩa -v nếu các kịch bản kiểm thử của bạn đọc các tệp dữ liệu cục bộ, chẳng hạn như bộ dữ liệu CSV cho các lần chạy dựa trên dữ liệu.

Tài liệu runner chung bao gồm chi tiết từng tùy chọn.

Bước 2: chạy container và xác nhận nó đã được kết nối

SSH vào máy chủ đích, dán lệnh và để Docker kéo hình ảnh và khởi động container. Hai ghi chú vận hành đáng thiết lập ngay từ ngày đầu tiên:

• Truyền TZ dưới dạng biến môi trường (ví dụ TZ=Asia/Singapore) để "mỗi ngày lúc 02:00" có nghĩa là 02:00 của bạn, không phải mặc định của container.
• Từ phiên bản runner 2.2.5, hình ảnh bao gồm một người dùng runner không phải root (UID/GID 10001). Nếu nền tảng của bạn thực thi runAsNonRoot, hãy đặt ngữ cảnh bảo mật phù hợp và cấu hình trước các quyền ổ đĩa, vì điểm vào không thể chown các thư mục ở chế độ không phải root.

Trở lại Apidog, runner xuất hiện trong Tài nguyên của nhóm bạn sau khi quá trình bắt tay WebSocket hoàn tất và các thành viên trong nhóm có thể chọn nó khi tạo tác vụ. Nếu nó không hiển thị trong vòng một phút, hãy kiểm tra nhật ký container bằng docker logs và xác nhận máy chủ có thể tiếp cận máy chủ Apidog trên cổng 443; kết nối WSS bị chặn là nguyên nhân phổ biến trên các mạng công ty bị khóa chặt.

Bạn có thể triển khai một vài runner trong một nhóm. Các nhóm thường giữ một runner bên trong VPC staging và một runner khác có quyền truy cập đọc vào production, sau đó chọn cho từng tác vụ.

Bước 3: tạo một tác vụ theo lịch trình nhắm đến runner

Với runner trực tuyến, việc lên lịch là một biểu mẫu, không phải một tập lệnh.

1. Trong dự án của bạn, mở mô-đun Kiểm thử (Tests) và nhấp vào Tác vụ theo lịch trình (Scheduled Tasks). Các tác vụ nằm trong cấu trúc thư mục, vì vậy hãy nhóm chúng theo dịch vụ hoặc môi trường khi danh sách phát triển.
2. Tạo một tác vụ và đặt tên mà đồng đội sẽ hiểu trong sáu tháng: "Orders service smoke, staging, every 6h" tốt hơn "test1".
3. Chọn một hoặc nhiều kịch bản kiểm thử. Đối với mỗi kịch bản, bạn có thể đặt môi trường, dữ liệu kiểm thử, số lần lặp, độ trễ giữa các yêu cầu và liệu có lưu thân yêu cầu/phản hồi hay không.
4. Đặt môi trường và phạm vi biến. Áp dụng các biến cho tất cả các kịch bản trong tác vụ là giải pháp trung gian được khuyến nghị; phạm vi toàn thư mục mạnh mẽ nhưng dễ mắc lỗi.
5. Đặt Chu kỳ chạy (Run Cycle): mỗi Chủ nhật lúc 11 giờ tối, mỗi 6 giờ, bất cứ điều gì phù hợp với mức độ nhanh chóng bạn cần biết có điều gì đó đã bị hỏng.
6. Trong Chạy trên (Runs on), chọn runner tự lưu trữ của bạn theo tên.
7. Cấu hình thông báo. Bạn có thể cảnh báo sau mỗi lần chạy hoặc chỉ khi thất bại. Chỉ thất bại là mặc định hợp lý; một kênh đầy các dấu kiểm màu xanh lá cây sẽ khiến mọi người bỏ qua nó.

Lưu lại. Từ thời điểm này, lịch trình sẽ được thực thi trên máy chủ của bạn bất kể ai đó có mở ứng dụng Apidog hay không.

Bước 4: đọc báo cáo chạy trong Apidog

Sau mỗi lần chạy, runner tự động tải kết quả lên máy chủ Apidog. Mở Tác vụ theo lịch trình (Scheduled Tasks) → Lịch sử chạy (Run History) trong ứng dụng để xem mọi lần thực thi: trạng thái đạt/không đạt, kết quả từng kịch bản, lỗi xác nhận và thời gian.

Đây là lợi thế thầm lặng của runner so với thiết lập cron-cộng-tập lệnh tự chế. Việc thực thi xảy ra trên hạ tầng của bạn, nhưng báo cáo được gửi đến cùng một không gian làm việc chung nơi các kiểm thử được định nghĩa. Khi lần chạy lúc 02:00 sáng Thứ Ba thất bại, kỹ sư QA điều tra sẽ thấy xác nhận nào đã thất bại ở bước nào, trong ngữ cảnh, mà không cần phải grep nhật ký trên máy chủ.

Kết hợp các thông báo thất bại với lịch sử chạy và bạn sẽ có một vòng lặp giám sát: cảnh báo kích hoạt, mở báo cáo, tái tạo bước thất bại thủ công trong ứng dụng trên cùng môi trường, sửa lỗi và chờ đợi lần chạy xanh tiếp theo.

Runner so với CLI so với đám mây: lựa chọn đường dẫn thực thi

Apidog cung cấp cho bạn ba cách để thực hiện kiểm thử ngoài việc nhấp chuột thủ công trong ứng dụng, và chúng giải quyết các vấn đề khác nhau. Chúng tôi đã viết một hướng dẫn đầy đủ về đường dẫn CI trong hướng dẫn Apidog CLI GitHub Actions của chúng tôi, và bảng so sánh dưới đây cho thấy mỗi tùy chọn phù hợp ở đâu.

Các đường dẫn bổ sung cho nhau chứ không cạnh tranh. Một thiết lập phổ biến: CLI kiểm soát mọi triển khai trong pipeline, trong khi runner thực hiện một bộ kiểm thử nhanh hàng giờ trên môi trường staging và một kiểm thử hồi quy đầy đủ hàng đêm, bắt lỗi do sự trôi dạt hạ tầng và chứng chỉ hết hạn thay vì thay đổi mã.

Một lưu ý về thời gian: theo tài liệu về tác vụ theo lịch trình, các tác vụ theo lịch trình được thiết kế để chạy trên một runner tự lưu trữ, với Apidog Cloud có thể lựa chọn khi khả năng sẵn có được triển khai. Nếu bạn cần thực thi theo lịch trình ngay hôm nay và không thể chờ đợi khả năng sẵn có trên đám mây cho gói của mình, runner là con đường đáng tin cậy.

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

Tôi có cần runner nếu tôi đã sử dụng Apidog CLI trong CI không?

Chúng trả lời các câu hỏi khác nhau. CI cho bạn biết "thay đổi này có làm hỏng API không?" tại thời điểm đẩy mã. Runner cho bạn biết "API có khỏe mạnh ngay bây giờ không?" theo một chu kỳ cố định, bắt các lỗi do mã thông báo hết hạn, các phụ thuộc bị hỏng hoặc sự trôi dạt hạ tầng mà không có commit nào đính kèm. Nhiều nhóm chạy cả hai; xem hướng dẫn thiết lập kiểm thử API hàng đêm của chúng tôi để biết phần CI theo lịch trình của mô hình.

Runner có thể tiếp cận API mạng nội bộ không?

Có, và đây là lý do chính để nó tồn tại. Runner thực hiện các yêu cầu từ máy mà nó được triển khai. Đặt nó bên trong VPC hoặc mạng văn phòng của bạn và nó có thể kiểm thử các máy chủ *.internal mà không dịch vụ đám mây nào có thể phân giải. Nó chỉ cần quyền truy cập HTTPS và WebSocket ra ngoài đến máy chủ Apidog để nhận tác vụ và tải báo cáo lên.

Thông số kỹ thuật máy chủ tối thiểu là gì?

Hai lõi CPU, 4 GB RAM, 30 GB đĩa và Docker 20.10.0 trở lên. Đối với các nhóm chạy các tác vụ theo lịch trình đồng thời, hãy chuyển sang 4+ lõi và 8 GB. Một VM nhỏ hoặc một hộp dự phòng trong tủ rack văn phòng đều hoạt động; ràng buộc là thời gian hoạt động, không phải mã lực.

Tôi cần gói dịch vụ nào cho các tác vụ theo lịch trình trên một runner tự lưu trữ?

Hạn ngạch chạy tác vụ theo lịch trình thay đổi tùy theo cấp độ gói đăng ký, vì vậy hãy kiểm tra giới hạn hiện tại trên trang giá Apidog trước khi bạn lên kế hoạch cho một lịch trình tần suất cao. Nếu bạn đang đánh giá các tùy chọn thực thi giữa các công cụ, so sánh Apidog CLI với Postman CLI của chúng tôi sẽ xem xét những gì phía test-runner của mỗi nền tảng bao gồm.