Hướng dẫn sử dụng Apidog CLI trong Cline

Cline hoạt động theo một vòng lặp: lập kế hoạch thay đổi, chỉnh sửa tệp, chạy lệnh, đọc đầu ra rồi quyết định bước tiếp theo. Nếu kịch bản kiểm thử API của bạn chỉ nằm trong giao diện Apidog, Cline không thể đưa chúng vào vòng lặp này. Bằng cách chạy kịch bản qua apidog-cli, bạn có thể để Cline kiểm thử API ngay sau khi sửa mã và dùng mã thoát để quyết định có cần tiếp tục sửa hay không.

Dùng thử Apidog ngay hôm nay

Apidog CLI là gói npm apidog-cli, cho phép chạy trực tiếp các kịch bản kiểm thử đã tạo trong Apidog từ terminal. Khi CLI đã được cài đặt và Cline biết lệnh cần chạy, tác nhân có thể thực hiện kiểm thử API tương tự cách nó chạy unit test: chạy lệnh, kiểm tra mã thoát và xử lý lỗi nếu lần chạy thất bại.

Trước khi bắt đầu, xác nhận CLI đã sẵn sàng:

apidog --version

Bạn cũng cần xác thực tài khoản Apidog trước. Nếu chưa thiết lập, xem cách cài đặt Apidog CLI với tác nhân mã hóa AI.

Cline được dùng trong bài này là gì?

Cline là tác nhân mã hóa mã nguồn mở, thường chạy dưới dạng tiện ích mở rộng VS Code; nó cũng có bản dựng JetBrains và CLI. Cline có thể đọc repository, lập kế hoạch trong chế độ Plan, chuyển sang Act để chỉnh sửa tệp và chạy shell command.

Điểm quan trọng là Cline có cơ chế nạp quy tắc cấp dự án. Thay vì phải nhắc “hãy chạy kiểm thử API” trong mọi cuộc trò chuyện, bạn có thể khai báo lệnh kiểm thử một lần trong .clinerules/.

Nếu bạn mới dùng Cline, xem cách sử dụng Cline.

Bước 1: Thêm lệnh Apidog vào .clinerules/

Cline nạp các quy tắc trong thư mục .clinerules/ ở thư mục gốc workspace trước khi bắt đầu tác vụ. Các tệp .md và .txt trong thư mục này được đưa vào ngữ cảnh hướng dẫn của Cline.

Tạo tệp sau tại root của repository:

.clinerules/apidog.md

Thêm nội dung:

# Kiểm thử API với Apidog

- Để kiểm thử API, hãy chạy Apidog CLI, không dùng curl hoặc script ad-hoc.
- Lệnh: apidog run -t <scenario_id> -e <env_id> -r cli
- ID kịch bản và ID môi trường lấy từ tab CI/CD của Apidog. Luôn dùng đúng các giá trị này.
- Mã thoát 0 nghĩa là mọi khẳng định đều vượt qua. Mã khác 0 nghĩa là thất bại; mã thoát là nguồn chân lý.
- Máy đã được xác thực qua `apidog login`. Không thêm `--access-token` và không đặt token trong tệp này.
- Nếu một cờ không được nhận diện, chạy `apidog run --help` và dùng đúng cờ được hiển thị.

Đưa cấu hình vào repository thay vì tin nhắn chat có hai lợi ích:

1. Cline nạp lại quy tắc cho mọi tác vụ mới.
2. Cả nhóm dùng chung lệnh, ID kịch bản và quy ước kiểm thử qua version control.

Chi tiết về cơ chế này có trong tài liệu quy tắc của Cline.

Bước 2: Lấy lệnh chính xác từ Apidog

Không đoán ID kịch bản hoặc ID môi trường. Trong Apidog:

1. Mở kịch bản kiểm thử cần chạy.
2. Chuyển đến tab CI/CD.
3. Sao chép lệnh apidog run được tạo sẵn.

Ví dụ:

apidog run -t 8291 -e 42 -r cli

Trong đó:

• -t 8291: ID kịch bản kiểm thử.
• -e 42: ID môi trường.
• -r cli: in kết quả trực tiếp trong terminal.

Cập nhật các giá trị này vào .clinerules/apidog.md. Tham khảo đầy đủ các cờ trong tài liệu lệnh apidog run.

Bước 3: Yêu cầu Cline chạy kiểm thử

Sau khi tạo quy tắc, bắt đầu một tác vụ mới trong Cline. Ví dụ, sau khi Cline thay đổi handler hoặc endpoint API, gửi yêu cầu:

Chạy kịch bản kiểm thử Apidog và cho tôi biết kết quả.

Cline sẽ đọc .clinerules/, sau đó chạy lệnh đã khai báo:

apidog run -t 8291 -e 42 -r cli

Việc Cline có yêu cầu phê duyệt trước khi chạy hay không phụ thuộc vào cấu hình auto-approve của bạn. Với kiểm thử chỉ đọc trên môi trường staging, bạn có thể phê duyệt lệnh và cấu hình phù hợp để các lần chạy sau ít bị gián đoạn hơn.

Bước 4: Dùng đầu ra CLI để sửa lỗi

Với -r cli, Cline nhận được đầu ra trực tiếp trong terminal, bao gồm:

• Từng request đã chạy.
• Từng assertion.
• Assertion thất bại.
• Giá trị kỳ vọng và giá trị thực tế.
• Mã thoát của tiến trình.

Khi lần chạy thất bại, hãy để Cline đọc lỗi cụ thể thay vì chỉ dựa vào bản tóm tắt. Ví dụ, lỗi có thể chỉ ra:

• Sai HTTP status code.
• Thiếu trường trong response.
• Giá trị response không đúng.
• Request không khớp môi trường hoặc dữ liệu test.

Nếu cần báo cáo để mở trên trình duyệt hoặc chia sẻ với đồng đội, thêm reporter HTML:

apidog run -t 8291 -e 42 -r cli,html

Reporter html ghi báo cáo vào thư mục:

./apidog-reports

Giữ cli trong danh sách reporter để Cline vẫn có đầu ra nội tuyến phục vụ vòng lặp tự động sửa lỗi. Xem thêm hướng dẫn Apidog CLI đầy đủ và hướng dẫn báo cáo kiểm thử Apidog CLI.

Đưa kiểm thử API vào vòng lặp sửa mã của Cline

Khi quy tắc đã tồn tại trong .clinerules/, quy trình có thể trở thành:

1. Cline sửa endpoint hoặc business logic.
2. Cline chạy apidog run.
3. Cline kiểm tra mã thoát.
4. Nếu mã thoát là 0, Cline tiếp tục tác vụ.
5. Nếu mã thoát khác 0, Cline đọc assertion thất bại.
6. Cline sửa mã và chạy lại kiểm thử.

Ví dụ với một handler tạo phản hồi thanh toán:

Sửa handler thanh toán để bổ sung trường `transactionId`,
sau đó chạy kịch bản Apidog để xác minh response.

Thay vì chỉ tuyên bố đã hoàn thành thay đổi, Cline có thể xác minh thay đổi đó bằng kịch bản API thực tế trên môi trường staging.

Đây là mô hình “ủy quyền rồi xác minh”: Cline chạy lệnh và đọc kết quả; bạn vẫn thiết kế và quản lý kịch bản trực quan trong Apidog. Xem thêm cách sử dụng tác nhân AI để kiểm thử API và bộ công cụ kiểm thử AI Apidog.

Xác minh Cline thực sự đã chạy CLI

Không chỉ dựa vào câu “kiểm thử đã vượt qua” của tác nhân. Kiểm tra theo ba bước sau.

1. Xác nhận lệnh đã xuất hiện trong terminal

Trong task view của Cline, tìm đúng dòng:

apidog run ...

Và kiểm tra đầu ra ngay bên dưới. Nếu Cline nói đã chạy kiểm thử nhưng không có lệnh hoặc đầu ra, hãy yêu cầu nó chạy lại và hiển thị output thô.

2. Kiểm tra mã thoát

Hỏi Cline trực tiếp:

Mã thoát của lệnh apidog run đó là gì?

Quy ước cần giữ nhất quán:

• Mã thoát 0: mọi assertion đều vượt qua.
• Mã thoát khác 0: ít nhất một assertion thất bại.

Nếu phần mô tả nói “đã vượt qua” nhưng mã thoát khác 0, hãy tin mã thoát.

3. Xác nhận đúng kịch bản và môi trường

Nếu lỗi báo không tìm thấy kịch bản, Cline có thể đã dùng sai ID. So sánh lại:

• Giá trị -t và -e trong .clinerules/apidog.md.
• Lệnh được Apidog tạo trong tab CI/CD.

Các ID trong lệnh CI/CD là giá trị cần dùng.

Tùy chọn: Kết nối Apidog MCP Server

.clinerules/ và apidog run đã đủ để Cline chạy kiểm thử. Nếu muốn Cline đọc API specification trong lúc viết mã, bạn có thể kết nối Apidog MCP Server.

Trong VS Code:

1. Mở bảng Cline.
2. Chọn biểu tượng MCP Servers.
3. Chọn Configure.
4. Chọn Configure MCP Servers để mở cline_mcp_settings.json.
5. Thêm server vào đối tượng mcpServers.

Bạn cũng có thể cài server từ MCP Marketplace trong Cline, theo tài liệu MCP của Cline.

Apidog MCP Server giúp Cline truy cập API specification qua MCP. Vai trò của hai thành phần là khác nhau:

• Apidog CLI: chạy kiểm thử.
• Apidog MCP Server: cung cấp ngữ cảnh về API specification cho tác nhân.

Cline là công cụ tương tác, không phải headless test runner. Nếu cần chạy apidog run trong pipeline CI/CD không có Cline, xem Apidog CLI trong GitHub Actions và hướng dẫn pipeline CI/CD của Apidog CLI.

Xử lý các lỗi thiết lập phổ biến

Cline bỏ qua tệp quy tắc

Kiểm tra:

• Thư mục phải có tên chính xác là .clinerules.
• Thư mục phải nằm tại root workspace.
• Tệp quy tắc phải có đuôi .md hoặc .txt.

Sau khi thay đổi quy tắc, bắt đầu một tác vụ Cline mới để buộc nạp lại cấu hình.

Cline thêm --access-token

Nếu Cline tự thêm --access-token, nó có thể đang suy đoán từ ví dụ công khai. Giữ rõ quy tắc sau trong .clinerules/apidog.md:

Máy đã được xác thực qua `apidog login`.
Không bao giờ thêm `--access-token`.
Không đặt token vào repository.

Xem hướng dẫn xác thực Apidog CLI để kiểm tra cấu hình đăng nhập.

Cline tự tạo cờ không tồn tại

Nếu nhận lỗi “tùy chọn không xác định”, yêu cầu Cline chạy:

apidog run --help

Sau đó dùng chính xác cờ được hiển thị bởi phiên bản CLI đã cài đặt.

Cline báo pass nhưng lần chạy thực tế fail

Ưu tiên mã thoát hơn phần tóm tắt. Quy tắc đơn giản là:

exit code = 0  -> pass
exit code != 0 -> fail

Đưa quy tắc này vào .clinerules/ và kiểm tra nó trong output của mỗi lần chạy quan trọng.

Kết luận

Thiết lập thực tế chỉ gồm ba phần:

1. Cài apidog-cli và xác thực bằng apidog login.
2. Lấy lệnh apidog run từ tab CI/CD của kịch bản Apidog.
3. Lưu lệnh và quy tắc kiểm tra mã thoát trong .clinerules/apidog.md.

Sau đó, Cline có thể chạy kiểm thử API trong cùng vòng lặp nó dùng để sửa mã. Endpoint lỗi được phát hiện khi tác nhân vẫn đang làm việc trên thay đổi, thay vì sau khi triển khai.

Bạn tiếp tục tạo và quản lý kịch bản trực quan trong Apidog; Cline chạy chúng từ terminal khi cần. Tải xuống Apidog, tạo kịch bản, thêm lệnh vào .clinerules/apidog.md, rồi để Cline đưa kiểm thử API vào quy trình phát triển hằng ngày.