Cách sử dụng Apidog CLI trong GitHub Copilot

Chế độ tác nhân (agent mode) của GitHub Copilot hoạt động theo một vòng lặp: chỉnh sửa tệp, chạy lệnh terminal, đọc đầu ra, rồi quyết định bước tiếp theo. Nếu kiểm thử API chỉ nằm trong giao diện Apidog, Copilot sẽ không tự chạy chúng. Bằng cách đưa lệnh Apidog CLI vào hướng dẫn của repository, bạn có thể biến kiểm thử API thành một phần của vòng lặp edit-test-fix của Copilot.

Dùng thử Apidog ngay hôm nay

Giải pháp cần một tệp cấu hình. Apidog CLI là gói npm apidog-cli, cho phép chạy các kịch bản kiểm thử đã tạo trong Apidog từ terminal. Khi CLI đã được cài đặt và Copilot biết lệnh cần chạy, agent mode có thể thực thi kịch bản, đọc exit code và tiếp tục sửa mã nếu kiểm thử thất bại.

Trước khi tiếp tục, hãy bảo đảm CLI đã sẵn sàng:

apidog --version

Nếu chưa cài đặt hoặc chưa đăng nhập, hãy xem Cách cài đặt Apidog CLI với tác nhân mã hóa AI. Bài viết này giả định lệnh trên in ra phiên bản CLI và tài khoản Apidog đã được xác thực.

Bài viết này áp dụng cho Copilot nào?

Bài viết tập trung vào Agent mode trong VS Code: giao diện Copilot có thể chỉnh sửa nhiều tệp, chạy terminal command và lặp lại đến khi hoàn thành tác vụ.

Trong VS Code:

1. Mở Copilot Chat.
2. Chuyển menu chọn chế độ sang Agent.
3. Khi Copilot đề xuất chạy lệnh, xem lại lệnh và xác nhận trước khi thực thi.

Các giao diện liên quan khác:

• Copilot coding agent chạy bất đồng bộ trong GitHub Actions và tạo pull request.
• Copilot CLI là ứng dụng terminal riêng.

Cả hai đều có thể chạy lệnh, nhưng Agent mode trong VS Code phù hợp nhất cho vòng lặp chỉnh sửa, kiểm thử và sửa lỗi. Thiết lập bên dưới cũng có thể được đọc bởi Copilot coding agent. Để tìm hiểu thêm về mô hình này, xem tác nhân mã hóa mới của GitHub Copilot.

Bước 1: Thêm quy tắc Apidog vào hướng dẫn của Copilot

Copilot đọc hướng dẫn cấp repository từ tệp:

.github/copilot-instructions.md

Theo tài liệu GitHub về hướng dẫn tùy chỉnh kho lưu trữ, Agent mode, Copilot Chat, code review và Copilot coding agent đều có thể tự động tải tệp này.

Tạo tệp nếu chưa tồn tại:

mkdir -p .github
touch .github/copilot-instructions.md

Sau đó thêm khối hướng dẫn sau:

## Kiểm thử API với Apidog CLI

Khi bạn thay đổi một điểm cuối API, hãy xác minh nó bằng Apidog CLI trước khi
tuyên bố tác vụ hoàn thành. Chạy:

    apidog run -t 812345 -e 671234 -r cli

- `apidog run` thoát với mã 0 khi mọi xác nhận (assertion) đều thành công, và khác 0 khi có bất kỳ lỗi nào.
  Coi mã thoát khác 0 là một kiểm thử thất bại, ngay cả khi văn bản tóm tắt trông ổn.
- Máy đã được xác thực qua `apidog login`. KHÔNG thêm cờ `--access-token` và không bao giờ đặt mã thông báo (token) vào tệp này.
- Nếu bạn gặp lỗi "unknown option" (tùy chọn không xác định), hãy chạy `apidog run --help` và sử dụng các cờ thực. Đừng đoán.

Thay các giá trị -t và -e bằng ID kịch bản và môi trường thực tế của bạn.

Đặt lệnh trong tệp hướng dẫn thay vì chỉ gửi trong chat. Nội dung chat có thể biến mất khi phiên kết thúc, trong khi .github/copilot-instructions.md được dùng lại cho đồng đội, phiên Agent mode mới và pull request do coding agent tạo.

Nếu quy tắc chỉ áp dụng cho một nhóm tệp, GitHub cũng hỗ trợ hướng dẫn theo đường dẫn trong:

.github/instructions/NAME.instructions.md

Tuy nhiên, một tệp hướng dẫn cấp repository thường là đủ cho lệnh kiểm thử API.

Bước 2: Lấy lệnh từ Apidog

Không cần tự viết lệnh apidog run. Apidog có thể tạo lệnh với ID kịch bản và môi trường chính xác.

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

Ví dụ:

apidog run -t 812345 -e 671234 -r cli

Dán chính xác lệnh đó vào .github/copilot-instructions.md.

Các ID trong tab CI/CD là nguồn chân lý. Nếu ID trong tệp hướng dẫn không khớp với lệnh Apidog tạo ra, hãy cập nhật tệp hướng dẫn. Xem thêm danh sách cờ và reporter tại tài liệu tham khảo lệnh apidog run.

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

Sau khi thêm hướng dẫn:

1. Mở Copilot Chat trong VS Code.
2. Chọn chế độ Agent.
3. Thực hiện thay đổi liên quan đến API.
4. Yêu cầu Copilot chạy kiểm thử:

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

Copilot sẽ lấy lệnh apidog run từ tệp hướng dẫn. Trước khi chạy, Agent mode hiển thị lệnh trong terminal và yêu cầu xác nhận. Hãy kiểm tra để bảo đảm lệnh dùng đúng kịch bản, môi trường và reporter, sau đó phê duyệt.

Với reporter -r cli, terminal tích hợp sẽ hiển thị từng yêu cầu, assertion và bản tóm tắt kết quả.

Bạn cần kiểm tra hai điểm:

• Lệnh apidog run thực sự đã được chạy.
• Copilot báo cáo cả kết quả lẫn exit code.

Nếu VS Code ghi nhớ quyền thực thi lệnh cho workspace, các lần chạy apidog run sau có thể không cần xác nhận lại. Chỉ nên cho phép điều này với kịch bản chỉ đọc chạy trên đúng môi trường staging.

Bước 4: Đọc báo cáo trong Copilot

Khi kiểm thử thất bại, reporter cli cung cấp đầu ra để Copilot phân tích:

• Yêu cầu nào đã chạy.
• Assertion nào thất bại.
• Giá trị mong đợi và giá trị thực tế.
• Mã trạng thái hoặc trường dữ liệu gây lỗi.

Thông tin này thường đủ để Copilot xác định vị trí cần sửa, cập nhật mã và chạy lại kiểm thử.

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

apidog run -t 812345 -e 671234 -r cli,html

Reporter html tạo tệp báo cáo trong:

./apidog-reports

Giữ cli trong danh sách reporter để Copilot vẫn nhận được đầu ra trực tiếp trong terminal và sử dụng nó cho vòng lặp tiếp theo.

Xem thêm:

• Hướng dẫn Apidog CLI đầy đủ
• Cách đọc báo cáo kiểm thử Apidog CLI

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

Sau khi thiết lập, vòng lặp làm việc có thể trở thành:

1. Copilot chỉnh sửa handler hoặc endpoint.
2. Copilot chạy apidog run trên môi trường staging.
3. Copilot đọc exit code và đầu ra assertion.
4. Nếu exit code là 0, Copilot tiếp tục.
5. Nếu exit code khác 0, Copilot đọc lỗi, sửa mã và chạy lại.

Ví dụ, khi Copilot sửa handler tạo phản hồi thanh toán, kịch bản Apidog có thể phát hiện:

• Mã trạng thái trả về không đúng.
• Một trường bắt buộc bị thiếu.
• Giá trị phản hồi khác dữ liệu mong đợi.

Kiểm thử API lúc này không còn là thao tác thủ công trong GUI. Nó trở thành một phần của quy trình edit-test-fix mà Copilot thực hiện khi thay đổi mã.

Đây vẫn là mô hình ủy quyền rồi xác minh: Copilot chạy lệnh và diễn giải kết quả, còn bạn tiếp tục quản lý kịch bản trực quan trong Apidog và kiểm tra ngẫu nhiên đầu ra thực tế. Xem thêm cách sử dụng tác nhân AI để kiểm thử API và công cụ kiểm thử AI của Apidog.

Xác minh Copilot thực sự chạy CLI

Không nên chỉ tin vào phần tóm tắt của agent. Kiểm tra theo thứ tự sau.

1. Kiểm tra lệnh và đầu ra terminal

Tìm lệnh thực tế trong terminal:

apidog run ...

Nếu Copilot nói kiểm thử đã chạy nhưng không có lệnh hoặc đầu ra terminal, yêu cầu nó chạy lại và hiển thị đầu ra thô.

2. Kiểm tra exit code

Hỏi trực tiếp:

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

Quy tắc cần nhớ:

• Exit code 0: tất cả assertion thành công.
• Exit code khác 0: có ít nhất một lỗi.

Nếu Copilot nói “kiểm thử đã vượt qua” nhưng exit code khác 0, hãy tin exit code.

3. Kiểm tra đúng kịch bản và môi trường

Nếu lệnh báo lỗi như:

scenario not found

Copilot có thể đã dùng sai hoặc tự đoán ID. So sánh các giá trị -t và -e giữa:

• .github/copilot-instructions.md
• Lệnh trong tab CI/CD của Apidog

ID do Apidog tạo ra là nguồn chân lý.

Tùy chọn: Kết nối máy chủ Apidog MCP

Lệnh apidog run trong tệp hướng dẫn đã đủ cho phần thực thi kiểm thử. Nếu muốn Copilot có thêm ngữ cảnh về API khi viết mã, hãy kết nối máy chủ Apidog MCP.

Agent mode trong VS Code đọc cấu hình MCP từ:

.vscode/mcp.json

Theo tài liệu GitHub về việc mở rộng Copilot với MCP, cấu hình này thuộc workspace tại thư mục gốc của repository.

Máy chủ Apidog MCP cung cấp đặc tả API qua MCP để Copilot có thể đọc schema trong lúc viết mã.

Phân chia trách nhiệm nên rõ ràng:

• Apidog CLI: chạy kiểm thử và trả exit code.
• Apidog MCP: cung cấp API spec cho tác nhân.

Nếu dùng Copilot coding agent trong GitHub Actions thay vì VS Code, cấu hình MCP nằm trong phần cài đặt repository, dưới Copilot và Cloud agent. Các bí mật cần được lưu dưới dạng Actions secrets với tiền tố:

COPILOT_MCP_

Tệp .vscode/mcp.json dành cho Agent mode chạy trong trình soạn thảo.

Khắc phục lỗi thường gặp

Copilot bỏ qua tệp hướng dẫn

Kiểm tra:

• Tệp có đúng tên .github/copilot-instructions.md.
• Tệp nằm trong thư mục .github ở gốc repository.
• Hướng dẫn tùy chỉnh được bật trong cài đặt VS Code.

Sai đường dẫn đồng nghĩa Copilot không tải tệp.

Copilot thêm --access-token

Nếu Copilot tự thêm:

--access-token

hãy nhắc lại trong hướng dẫn rằng máy đã xác thực qua:

apidog login

Không đặt token thật trong repository. Xem xác thực Apidog CLI để biết mô hình xác thực.

Copilot tự đoán cờ CLI

Lỗi sau cho thấy cờ không tồn tại trong phiên bản CLI hiện tại:

unknown option

Yêu cầu Copilot chạy:

apidog run --help

Sau đó chỉ sử dụng các cờ hiển thị trong đầu ra của phiên bản đã cài đặt.

Copilot báo thành công cho lần chạy thất bại

Đây là lỗi quan trọng nhất. Khi phần tóm tắt và exit code mâu thuẫn, luôn ưu tiên exit code.

Checklist triển khai

Trước khi dùng thiết lập này trong dự án, xác nhận:

• [ ] apidog --version chạy thành công.
• [ ] Máy đã đăng nhập bằng apidog login.
• [ ] Kịch bản Apidog có lệnh CI/CD với ID -t và -e chính xác.
• [ ] .github/copilot-instructions.md chứa lệnh apidog run.
• [ ] Hướng dẫn yêu cầu Copilot kiểm tra exit code.
• [ ] Reporter cli được giữ lại để Copilot đọc đầu ra.
• [ ] Bạn đã xác minh terminal thực sự chạy lệnh.

Cài đặt apidog-cli một lần, thêm lệnh Apidog vào .github/copilot-instructions.md, và Copilot có thể chạy kiểm thử API trong cùng vòng lặp mà nó dùng để sửa mã. Điều này giúp phát hiện endpoint lỗi trong khi agent vẫn đang xử lý thay đổi, thay vì chỉ sau khi mã đã được triển khai.

Bạn vẫn xây dựng kịch bản trực quan trong Apidog, còn Copilot chạy chúng từ terminal khi cần. Tải Apidog, tạo một kịch bản, thêm lệnh apidog run vào hướng dẫn repository và kiểm tra hành vi của agent trong thay đổi API tiếp theo.

Khi sẵn sàng chạy cùng lệnh trong pipeline mà không cần Copilot, xem Apidog CLI trong GitHub Actions để cấu hình secrets, reporter và exit-code gate.