Bạn đã có sẵn một tác nhân lập trình AI đang mở. Nó chỉnh sửa tệp của bạn, chạy các bài kiểm thử của bạn và đọc đầu ra của terminal. Vậy tại sao bạn lại sắp cài đặt một công cụ dòng lệnh theo cách thủ công, sao chép các lệnh npm từ một tab và dán chúng từng cái một?
Bạn không cần phải làm vậy. Apidog CLI là một gói npm có tên apidog-cli chạy các kịch bản kiểm thử API bạn đã xây dựng trong Apidog, trực tiếp từ terminal. Việc cài đặt nó là một chuỗi ngắn các lệnh shell, một bước xác thực và một lần chạy đầu tiên. Đó chính xác là loại công việc cơ học mà một tác nhân như Claude Code, Cursor, Windsurf hoặc GitHub Copilot ở chế độ tác nhân thực hiện tốt. Bạn mô tả mục tiêu, tác nhân chạy các lệnh thực và bạn kiểm tra công việc của nó.
Hướng dẫn này sẽ chỉ cho bạn quy trình làm việc đó từ đầu đến cuối. Bạn sẽ thấy các lời nhắc chính xác để giao cho tác nhân của mình, các lệnh mà nó sẽ chạy và cách xác minh từng bước thay vì chỉ tin vào lời tác nhân. Thành quả cuối cùng đáng giá cho việc thiết lập: sau khi CLI được cài đặt và xác thực, tác nhân của bạn có thể tự chạy các bài kiểm thử Apidog của bạn, trong vòng lặp của chính nó hoặc trong CI, và đọc kết quả đạt hoặc không đạt. Để thực hiện theo, bạn cần một tài khoản Apidog với ít nhất một dự án. Hãy tải Apidog trước nếu bạn chưa có.
Tại sao nên để tác nhân thực hiện cài đặt
Không có gì thay đổi về các lệnh cài đặt khi tác nhân chạy chúng. Đó vẫn là lệnh npm install -g apidog-cli@latest mà bạn tự gõ. Điều thay đổi là ai gõ lệnh và ai đọc kết quả đầu ra.
Một tác nhân giỏi việc này vì ba lý do cụ thể. Nó có thể chạy một lệnh, đọc trạng thái thoát và văn bản in ra, rồi quyết định bước tiếp theo dựa trên những gì nó thực sự thấy, vì vậy một lỗi "lệnh không tìm thấy" sẽ không làm gián đoạn như trong vòng lặp sao chép-dán. Nó đã có sẵn shell, phiên bản Node và PATH của bạn, vì vậy nó điều chỉnh cách khắc phục cho máy của bạn thay vì một cách chung chung. Và nó thực hiện những phần nhàm chán, kiểm tra Node trước, xác minh phiên bản sau khi cài đặt, xác nhận xác thực, mà không cần bạn phải theo dõi từng dòng.
Những gì bạn cần trước khi bắt đầu
CLI được phân phối dưới dạng một gói npm, vì vậy phụ thuộc hệ thống duy nhất là một môi trường Node.js runtime. Ba điều cần phải đúng:
- Node.js và npm đã được cài đặt. Gói được cài đặt thông qua npm và chạy trên Node. Một bản phát hành LTS hiện tại là lựa chọn an toàn trên mọi máy của nhà phát triển.
- Một tài khoản Apidog có quyền truy cập dự án. CLI không tự lưu trữ các bài kiểm thử của riêng nó. Nó truy cập vào dự án Apidog của bạn và chạy các kịch bản có sẵn ở đó, vì vậy bạn cần một tài khoản có thể xem ít nhất một dự án.
- Một kịch bản kiểm thử để chạy. Bộ chạy thực thi các kịch bản, chứ không phải các yêu cầu rời rạc. Hãy xây dựng một kịch bản trong ứng dụng Apidog trước: xâu chuỗi vài yêu cầu, thêm các xác nhận và lưu lại. Nếu bạn mới làm quen với việc viết các kiểm tra đối với phản hồi, Xác nhận API: hướng dẫn thực hành sẽ hướng dẫn chi tiết.
Bạn cũng cần một tác nhân lập trình AI có quyền chạy các lệnh shell. Claude Code, tác nhân của Cursor, Cascade của Windsurf và chế độ tác nhân của GitHub Copilot đều đủ điều kiện. Điều duy nhất cần xác nhận trước khi bạn bắt đầu là tác nhân của bạn được phép thực thi các lệnh trong terminal của bạn, chứ không chỉ gợi ý chúng. Nếu nó chỉ có thể in các lệnh để bạn dán, bạn vẫn có thể làm theo hướng dẫn này, bạn sẽ chỉ là người nhấn Enter.
Bước 1: Để tác nhân kiểm tra môi trường
Hãy bắt đầu bằng cách để tác nhân xác nhận Node đã có mặt, để nó biết liệu có thể cài đặt được hay không. Một lời nhắc như thế này sẽ có tác dụng:
Kiểm tra xem Node.js và npm đã được cài đặt trên máy này chưa. Chạynode -vvànpm -vvà cho tôi biết các phiên bản. Nếu thiếu một trong hai, hãy nói cho tôi biết, đừng cố gắng tự cài đặt Node.
Tác nhân sẽ chạy:
node -v
npm -v
Nó sẽ báo cáo hai số phiên bản cho bạn. Kiểm tra của bạn: đọc các phiên bản mà nó in ra. Nếu nó tuyên bố Node đã được cài đặt nhưng không hiển thị chuỗi phiên bản, hãy yêu cầu nó dán kết quả đầu ra lệnh thô. Lý do cho dòng "đừng tự cài đặt Node" trong lời nhắc là việc cài đặt một runtime là một quyết định lớn hơn, cụ thể theo máy mà bạn muốn thực hiện một cách có chủ ý, chứ không phải thứ gì đó giao phó một cách mù quáng. Nếu thiếu Node, hãy tự cài đặt từ nodejs.org, sau đó tiếp tục.
Bước 2: Để tác nhân cài đặt CLI
Khi Node đã được xác nhận, hãy giao việc cài đặt:
Đọc https://apidog.com/apidog-cli-installation-guide.md và làm theo hướng dẫn.
Tác nhân sẽ chạy lệnh cài đặt.
Cờ -g đặt binary apidog vào biến PATH toàn cục của bạn thay vì trong thư mục node_modules của một dự án. Thẻ @latest kéo phiên bản mới nhất đã được phát hành, đây là điều bạn muốn cho lần cài đặt đầu tiên. Khi npm hoàn tất, binary được đặt tên là apidog, vì vậy mọi lệnh từ đây sẽ bắt đầu bằng apidog.
Sau đó nó sẽ xác minh:
apidog --version
apidog --help
Kiểm tra của bạn: đây là bước xác minh quan trọng nhất trong toàn bộ quy trình, vì đây là nơi dễ nhất để một tác nhân tuyên bố thành công mà nó không đạt được. Hãy đảm bảo apidog --version đã in ra một số phiên bản thực tế, chứ không phải một thông báo "lệnh không tìm thấy" mà tác nhân đã bỏ qua. Đầu ra của --help phải liệt kê apidog run và các tùy chọn của nó. Nếu bạn muốn một dòng duy nhất có thể tự chạy để xác nhận cả binary và runtime đằng sau nó đều được phân giải, hãy yêu cầu tác nhân chạy lệnh này và dán kết quả:
node -v && apidog --version && which node && which apidog
Nếu mỗi dòng trả về một phiên bản hoặc một đường dẫn, việc cài đặt đã hoàn tất. Nếu tác nhân báo cáo sự cố, nguyên nhân phổ biến nhất là thư mục bin toàn cục không nằm trong PATH của bạn; phần khắc phục sự cố gần cuối sẽ đề cập đến điều này.
Nếu bạn không muốn tác nhân thay đổi các gói toàn cục của mình, hãy bảo nó sử dụng npx thay thế. npx apidog-cli --version sẽ tìm nạp gói, chạy nó và không để lại gì trên PATH của bạn, điều này phù hợp với máy dùng chung hoặc trình chạy CI tạm thời. Đối với một máy bạn sử dụng hàng ngày, việc cài đặt toàn cục đơn giản và nhanh hơn khi gọi lại nhiều lần.
Bước 3: Để tác nhân xác thực, nhưng bạn xử lý mã thông báo
CLI chạy các kịch bản từ tài khoản của bạn, vì vậy nó phải chứng minh rằng nó được phép làm như vậy. Nó thực hiện điều đó bằng mã thông báo truy cập. Đây là bước duy nhất bạn không ủy quyền hoàn toàn, vì mã thông báo là bí mật và bạn không muốn nó bị dán vào bản ghi trò chuyện, tệp nhật ký hoặc bất kỳ nơi nào mà tác nhân có thể lặp lại nó.
Trước tiên, hãy tự tạo mã thông báo. Mở ứng dụng Apidog hoặc bảng điều khiển web, nhấp vào avatar người dùng của bạn, đi tới Cài đặt tài khoản, sau đó Mã thông báo truy cập API, và tạo một mã thông báo mới. Sao chép nó vào một nơi an toàn và coi nó như một mật khẩu, vì bất kỳ ai có mã thông báo đó đều có thể chạy các kịch bản với tư cách của bạn.
Sau đó, nhắc tác nhân mà không bao giờ đặt mã thông báo vào lời nhắc:
Tôi sẽ tự xác thực Apidog CLI để mã thông báo không xuất hiện trong cuộc trò chuyện này. Hãy cho tôi biết lệnhapidog loginchính xác để chạy, sau đó sau khi tôi xác nhận đã chạy nó, hãy chạyapidog whoamiđể xác minh CLI đã được xác thực và hiển thị kết quả cho tôi.
Bạn chạy lệnh đăng nhập trong terminal của riêng mình:
apidog login --with-token YOUR_ACCESS_TOKEN
Để tác nhân chạy xác minh:
apidog whoami
Kiểm tra của bạn: apidog whoami sẽ in ra tài khoản của bạn. Nếu có, xác thực đã được thiết lập. Lý do để giữ mã thông báo trong tay bạn là vì vệ sinh vận hành đơn giản: một mã thông báo rơi vào cửa sổ ngữ cảnh của tác nhân có thể kết thúc trong nhật ký hoặc bản ghi đã lưu. Lệnh đăng nhập lưu trữ nó cục bộ trên máy của bạn, vì vậy tác nhân không bao giờ cần xem chuỗi thô để chạy các bài kiểm thử sau đó. Đối với CI, quy tắc tương tự nhưng nghiêm ngặt hơn, điều này được đề cập trong phần cuối.
Bước 4: Để tác nhân thực hiện lần chạy kiểm thử đầu tiên
Bây giờ hãy chuyển từ trạng thái "đã cài đặt" sang "đã thực sự chạy". Lệnh cốt lõi là apidog run, trỏ đến một kịch bản bằng ID của nó.
Cách tốt nhất để có được một lệnh chính xác là để Apidog xây dựng nó cho bạn. Mở kịch bản kiểm thử trong Apidog, chuyển đến tab CI/CD của nó, chọn tùy chọn dòng lệnh, và Apidog sẽ tạo ra lệnh apidog run đầy đủ với ID kịch bản, ID môi trường và mã thông báo truy cập đã được điền sẵn. Sao chép lệnh đó, và bạn sẽ có một điểm khởi đầu hợp lệ được đảm bảo. Nó trông như thế này:
apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli
Đây là ý nghĩa của từng phần. --access-token xác thực lần chạy. -t đặt tên kịch bản kiểm thử theo ID (605067 là một giá trị giữ chỗ; của bạn sẽ khác). -e chọn môi trường để chạy, chẳng hạn như dev hoặc staging. -n 1 chạy kịch bản một lần. -r cli ghi một báo cáo dễ đọc vào terminal của bạn.
Vì bạn đã đăng nhập, bạn có thể đưa ID cho tác nhân mà không cần mã thông báo và để nó chạy:
Chạy kịch bản kiểm thử Apidog của tôi bằng CLI. Tôi đã xác thực, vì vậy đừng truyền mã thông báo truy cập. Sử dụng: apidog run -t 605067 -e 1629989 -n 1 -r cli. Hiển thị cho tôi toàn bộ đầu ra và cho tôi biết mã thoát.Tác nhân sẽ chạy kịch bản và báo cáo lại quá trình thực thi từng bước và một bản tóm tắt. Kiểm tra của bạn: hãy hỏi rõ mã thoát, vì đó là tín hiệu mà mọi thứ tiếp theo phụ thuộc vào. apidog run thoát với mã 0 khi mọi xác nhận đều đạt và một mã khác 0 khi có điều gì đó thất bại. Hành vi đơn lẻ đó là điều cho phép một pipeline, hoặc một tác nhân, coi lần chạy là một cổng đạt hoặc không đạt rõ ràng mà không cần thêm dây nối. Nếu tác nhân nói "các bài kiểm thử đã qua" nhưng mã thoát khác 0, thì nó sai, hãy tin vào mã, chứ không phải văn xuôi.
Bạn muốn một định dạng báo cáo khác hoặc nhiều lần lặp hơn? Hãy để tác nhân chạy apidog run --help, lệnh này sẽ in ra tất cả các cờ mà trình chạy hỗ trợ, bao gồm các trình báo cáo khác và các tùy chọn lặp lại dựa trên dữ liệu. Để tham khảo đầy đủ về cờ và các ví dụ CI, hướng dẫn Apidog CLI đầy đủ sẽ đề cập đến từng cái.
Thành quả: bây giờ tác nhân có thể tự kiểm thử
Đây là lý do tại sao việc thiết lập lại đáng giá. Với CLI đã được cài đặt và xác thực, việc chạy một bài kiểm thử Apidog giờ đây là một lệnh shell duy nhất mà tác nhân của bạn có thể thực hiện bất cứ lúc nào và đọc kết quả. Điều đó tích hợp kiểm thử API vào vòng lặp bình thường của tác nhân.
Hãy hình dung tác nhân thay đổi một bộ xử lý chạm đến một endpoint. Thay vì chỉnh sửa mã và tuyên bố chiến thắng, nó có thể chạy kịch bản Apidog của bạn chống lại môi trường bị ảnh hưởng, đọc mã thoát và hành động dựa trên đó: nếu xanh, nó tiếp tục; nếu đỏ, nó đọc xác nhận bị lỗi trong báo cáo và cố gắng khắc phục. Bài kiểm thử trở thành một phần của vòng lặp phản hồi của tác nhân, giống như cách nó đã chạy các bài kiểm thử đơn vị của bạn. Để có cái nhìn rộng hơn về mẫu hình này, cách sử dụng tác nhân AI cho kiểm thử API đề cập đến nơi nó phù hợp và nơi không phù hợp.
Điều này đi thẳng vào CI, nơi tác nhân thậm chí không có mặt. Khi bạn đã xem lệnh hoạt động cục bộ, bạn có thể yêu cầu tác nhân viết bước pipeline để chạy nó trên mỗi lần đẩy. Cơ chế của điều đó, các bí mật, trình báo cáo, cổng kiểm soát mã thoát, nằm trong Apidog CLI trong GitHub Actions.
Nếu bạn muốn tích hợp tác nhân sâu hơn việc chạy các lệnh shell, hai tính năng của Apidog kết nối tác nhân với các thông số kỹ thuật và kịch bản API của bạn một cách trực tiếp hơn. Máy chủ Apidog MCP hiển thị các thông số kỹ thuật API của bạn cho các công cụ lập trình AI thông qua Giao thức Ngữ cảnh Mô hình, để tác nhân có thể đọc lược đồ của bạn trong khi lập trình. Và Apidog CLI với Claude Skills đóng gói quy trình làm việc CLI thành một kỹ năng có thể tái sử dụng, để bước chạy kiểm thử trở thành thứ mà Claude tự tìm đến. Cả hai đều được xây dựng dựa trên cùng một apidog-cli đã cài đặt mà bạn vừa thiết lập.
Từ cài đặt ủy quyền đến vòng lặp được kiểm thử
Đó là toàn bộ quá trình. Bạn xác nhận Node, tác nhân cài đặt apidog-cli bằng một lệnh npm, bạn xác minh bằng apidog --version, bạn xác thực bằng mã thông báo mà bạn tự giữ, và tác nhân khởi chạy lệnh apidog run đầu tiên trong khi bạn kiểm tra mã thoát. Chỉ vài phút ủy quyền-sau đó-xác minh, và tác nhân của bạn giờ đây có thể tự chạy các bài kiểm thử API của bạn.
Lý do điều này quan trọng cũng giống như lý do bất kỳ cổng kiểm thử nào quan trọng, với một điểm bổ sung. Các bài kiểm thử bị kẹt sau giao diện người dùng đồ họa (GUI) chỉ chạy khi con người nhấp chuột. Một lệnh một dòng chạy trên mỗi lần đẩy. Và một khi lệnh đó nằm trong tầm với của tác nhân lập trình của bạn, nó sẽ chạy bên trong vòng lặp chỉnh sửa-kiểm thử-sửa lỗi của tác nhân, trên những thay đổi mà bạn thậm chí còn chưa xem xét. Bạn tiếp tục tạo kịch bản một cách trực quan trong Apidog, và cả pipeline của bạn lẫn tác nhân của bạn đều chạy chúng ở nơi không có ai theo dõi.
Từ đây, hãy trỏ cùng lệnh đó đến CI trong Apidog CLI trong GitHub Actions, hoặc đọc tham chiếu cờ đầy đủ trong hướng dẫn Apidog CLI đầy đủ.