Sebastian Petrus

Posted on Jul 14 • Originally published at apidog.com

Cách sử dụng Apidog CLI trong Trae

Trae hoạt động theo một vòng lặp: Agent Builder đọc kho lưu trữ, chỉnh sửa tệp, chạy lệnh trong terminal và phân tích đầu ra để quyết định bước tiếp theo. Nếu các bài kiểm thử API vẫn nằm trong giao diện đồ họa của Apidog và chỉ chạy khi có người nhấp chuột, chúng sẽ không tham gia vào vòng lặp đó. Kết quả là Builder không thể tự xác minh thay đổi API của bạn.

Dùng thử Apidog ngay hôm nay

Cách tích hợp là dùng một khối cấu hình dự án. 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 ngay từ terminal. Khi CLI đã được cài đặt và Trae biết lệnh cần chạy, Builder có thể thực thi kịch bản Apidog như kiểm thử đơn vị: chạy lệnh, đọc mã thoát và xử lý lỗi nếu kiểm thử thất bại.

Nếu chưa cài đặt CLI, hãy thực hiện bước đó trước. Bài viết Cách cài đặt Apidog CLI với một AI coding agent hướng dẫn cài đặt npm, xác thực và chạy lần đầu. Bài viết này giả định rằng lệnh sau hoạt động:

apidog --version

Tài khoản Apidog trên máy cũng cần được xác thực.

Bài viết này nói về Trae nào?

Trae là IDE AI của ByteDance, được xây dựng trên VS Code. Chế độ agent Builder có thể chỉnh sửa tệp và chạy lệnh trong terminal. Bạn có thể xem thông tin sản phẩm trên trang web chính thức của Trae.

Bài viết này áp dụng cho IDE desktop Trae, không phải dự án nghiên cứu trae-agent trên GitHub. Nếu bạn thấy bảng chat bên cạnh trình soạn thảo và có thể chuyển agent sang Builder, bạn đang dùng đúng sản phẩm.

Sự khác biệt này quan trọng vì Trae có cơ chế riêng để tải quy tắc dự án. Với quy tắc đó, yêu cầu “chạy kiểm thử API” có thể trở thành hành vi mặc định của Builder thay vì một lời nhắc chỉ tồn tại trong chat. Nếu cần tìm hiểu Apidog CLI độc lập với Trae, hãy xem hướng dẫn Apidog CLI đầy đủ.

Bước 1: Thêm tệp quy tắc dự án

Trae đọc tệp quy tắc trước khi Builder bắt đầu làm việc. Theo tài liệu quy tắc của Trae, tệp quy tắc cấp dự án nằm tại:

.trae/rules/project_rules.md

Tệp user_rules.md cũng có thể áp dụng quy tắc cho mọi dự án của bạn. Tuy nhiên, với quy trình kiểm thử API theo từng repo, hãy dùng project_rules.md.

Tạo tệp .trae/rules/project_rules.md tại thư mục gốc của repository, sau đó thêm quy tắc sau:

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

Khi bạn thay đổi mã liên quan đến một endpoint API, hãy xác minh nó bằng cách chạy
kịch bản kiểm thử Apidog, không chỉ các bài kiểm thử đơn vị.

Lệnh:
  apidog run -t <scenario_id> -e <env_id> -r cli

Quy tắc:
- `apidog run` thoát với mã 0 khi mọi xác nhận đều thành công và khác 0 nếu 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 bản tóm tắt trông ổn.
- Máy này đã được xác thực thông qua `apidog login`. Không bao giờ thêm
  cờ `--access-token` và không bao giờ đặt mã thông báo vào tệp này.
- Nếu một cờ không xác định, hãy chạy `apidog run --help` và sử dụng chính xác cờ từ đó.

Đặt lệnh trong project_rules.md thay vì chỉ gửi trong chat giúp quy trình có tính bền vững:

ID kịch bản không bị mất khi phiên chat kết thúc.
Đồng đội dùng cùng repository cũng nhận được cùng quy tắc.
Mọi phiên Builder sau này đều biết cách chạy kiểm thử API.
Với monorepo, bạn có thể đặt thư mục .trae/rules/ riêng trong từng dịch vụ để dùng quy tắc khác nhau.

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

Không cần tự đoán ID kịch bản hoặc ID môi trường.

Mở kịch bản kiểm thử trong Apidog.
Chuyển đến tab CI/CD.
Sao chép lệnh apidog run được Apidog tạo sẵn.
Thay <scenario_id> và <env_id> trong project_rules.md bằng các giá trị thực tế.

Ví dụ:

apidog run -t your_scenario_id -e your_env_id -r cli

Lệnh được tạo từ tab CI/CD đã chứa ID chính xác cho kịch bản và môi trường của bạn. Điều này tránh việc Builder hoặc bạn tự tạo ID không hợp lệ.

Để xem đầy đủ cờ lệnh và chức năng, hãy xem tài liệu tham khảo lệnh apidog run.

Bước 3: Cho Builder chạy kiểm thử

Sau khi cập nhật project_rules.md:

Mở repository trong Trae.
Chuyển agent sang chế độ Builder.
Thực hiện một thay đổi liên quan đến API, hoặc yêu cầu Builder chạy kiểm thử.

Ví dụ prompt:

Run the Apidog test scenario and tell me the exit code.

Builder sẽ đọc project_rules.md khi khởi tạo và đề xuất lệnh apidog run. Theo mô hình phê duyệt của Trae, bạn cần nhấp Run để cho phép lệnh shell thực thi trong terminal.

Sau khi chạy, Builder có thể đọc đầu ra và báo cáo:

Kết quả của từng yêu cầu.
Kết quả từng assertion.
Bản tóm tắt kiểm thử.
Mã thoát của lệnh.

Cờ -r cli giúp hiển thị kết quả trực tiếp trong terminal, nơi Builder có thể phân tích để quyết định bước tiếp theo.

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

Khi một lần chạy thất bại, đầu ra CLI là nguồn thông tin để Builder xử lý lỗi. Với -r cli, terminal hiển thị:

Từng request đã chạy.
Từng assertion.
Assertion 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 đủ để Builder xác định phần mã cần sửa.

Nếu cần một báo cáo có thể mở trong trình duyệt hoặc gửi cho đồng đội, hãy thêm trình báo cáo HTML:

apidog run -t <scenario_id> -e <env_id> -r cli,html

Trình báo cáo html ghi tệp độc lập vào thư mục:

./apidog-reports

Giữ cli trong danh sách reporter để Builder vẫn nhận đầu ra nội tuyến trong terminal. Để tìm hiểu các định dạng khác như JSON và JUnit cho CI, xem hướng dẫn về báo cáo kiểm thử Apidog CLI.

Trae kiểm thử trong vòng lặp riêng của nó

Điểm quan trọng là Builder có thể tự chạy kịch bản khi quy tắc dự án yêu cầu, thay vì chờ bạn nhắc lại trong mỗi phiên làm việc.

Ví dụ, Builder đang chỉnh sửa handler tạo phản hồi thanh toán. Quy trình có thể trở thành:

Builder chỉnh sửa mã endpoint.
Builder chạy kịch bản Apidog trên môi trường staging.
Builder đọc mã thoát.
Nếu mã thoát là 0, Builder tiếp tục.
Nếu mã thoát khác 0, Builder đọc assertion thất bại.
Builder thử sửa lỗi và chạy lại kiểm thử.

Khi đó, kiểm thử API trở thành một phần của vòng lặp sửa mã → kiểm thử → khắc phục tương tự như kiểm thử đơn vị.

Đây là mô hình ủy quyền rồi xác minh: Builder chạy lệnh và đọc kết quả, còn bạn tiếp tục thiết kế kịch bản trực quan trong Apidog và kiểm tra ngẫu nhiên việc agent có diễn giải mã thoát chính xác hay không.

Để tìm hiểu quy trình rộng hơn, xem:

Xác minh Trae thực sự đang chạy CLI

Agent có thể báo cáo thành công mà không thực sự hoàn thành công việc. Hãy kiểm tra theo ba bước sau.

1. Xác nhận lệnh đã chạy

Trae hiển thị lệnh Builder đã thực thi cùng đầu ra terminal. Tìm dòng lệnh apidog run và kiểm tra kết quả ngay bên dưới.

Nếu Builder nói rằng kiểm thử đã chạy nhưng bạn không thấy lệnh thực tế trong terminal, hãy yêu cầu nó chạy lại và hiển thị đầu ra thô.

2. Xác nhận mã thoát

Dùng prompt sau:

What was the exit code of that apidog run command?

Quy tắc cần nhớ:

Mã thoát 0: mọi assertion thành công.
Mã thoát khác 0: có ít nhất một assertion thất bại.

Nếu phần tóm tắt của Builder nói “kiểm thử đã vượt qua” nhưng mã thoát khác 0, hãy tin mã thoát.

3. Xác nhận Builder dùng đúng kịch bản

Nếu lần chạy báo lỗi kiểu “không tìm thấy kịch bản”, Builder có thể đã dùng sai ID.

Kiểm tra lại:

Giá trị sau cờ -t.
Giá trị sau cờ -e.
Lệnh trong .trae/rules/project_rules.md.
Lệnh Apidog tạo tại tab CI/CD.

Các ID trong tệp quy tắc dự án phải là nguồn chính xác để Builder sử dụng.

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

Chạy apidog run từ project_rules.md đã bao phủ phần lớn nhu cầu kiểm thử. Nếu cần Builder truy cập đặc tả API trong lúc viết mã, bạn có thể kết nối máy chủ MCP.

Agent Trae hoạt động như MCP client, vì vậy Builder có thể gọi công cụ do MCP server cung cấp.

Để thêm server:

Mở cài đặt Trae.
Chuyển đến tab MCP.
Chọn server từ marketplace, hoặc chọn Add Manually.
Dán cấu hình JSON chứa command, args và env.

Xem thêm trong hướng dẫn của Trae về việc thêm máy chủ MCP.

Máy chủ Apidog MCP cung cấp đặc tả API thông qua MCP. Điều này cho phép Builder đọc schema khi viết mã, thay vì chỉ chạy kiểm thử sau khi hoàn thành.

Phân công trách nhiệm rõ ràng:

Apidog CLI: chạy kịch bản kiểm thử.
Apidog MCP: cung cấp đặc tả API cho agent.

Khi Trae mắc lỗi

Dưới đây là các lỗi thường gặp và cách xử lý.

Builder bỏ qua tệp quy tắc

Nếu Builder chạy lệnh chung chung hoặc không chạy lệnh nào, tệp quy tắc có thể chưa được tải.

Kiểm tra:

.trae/rules/project_rules.md

Đảm bảo:

Tệp nằm ở thư mục gốc repository.
Thư mục tên là rules, không phải rule.
Bạn khởi động lại phiên Builder để buộc Trae đọc lại quy tắc.

Builder vẫn truyền access token

Nếu Builder cố thêm --access-token, nó có thể đang suy đoán từ ví dụ công khai.

Nhắc lại trong quy tắc rằng máy đã xác thực qua:

apidog login

Không đặt access token thật vào project_rules.md.

Để hiểu cách CLI xử lý thông tin xác thực trong môi trường tương tác và CI, xem xác thực Apidog CLI.

Builder tự tạo cờ lệnh

Lỗi “tùy chọn không xác định” thường có nghĩa Builder đã dùng một cờ không tồn tại trong phiên bản CLI đang cài đặt.

Yêu cầu Builder chạy:

apidog run --help

Sau đó dùng đúng tên cờ được hiển thị trong kết quả trợ giúp.

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

Đây là lỗi nghiêm trọng nhất. Vì vậy, quy tắc về mã thoát cần tồn tại trong project_rules.md.

Khi phần tóm tắt và mã thoát không khớp, luôn dùng mã thoát làm kết luận cuối cùng.

Từ agent hằng ngày đến vòng lặp được kiểm thử

Thiết lập gồm ba phần:

Cài đặt apidog-cli theo hướng dẫn cài đặt.
Thêm lệnh Apidog vào .trae/rules/project_rules.md.
Cho Builder chạy và phân tích kết quả trong cùng vòng lặp chỉnh sửa mã.

Sau đó, Builder có thể phát hiện endpoint hỏng trong lúc vẫn đang thực hiện thay đổi, thay vì đợi đến sau khi triển khai.

Một kiểm thử chỉ nằm trong GUI cần con người chủ động chạy. Một lệnh apidog run trong quy tắc dự án có thể được Builder thực thi khi cần. Bạn vẫn xây dựng kịch bản trực quan trong Apidog, còn agent có thể chạy chúng như một phần của quy trình phát triển.

Tải xuống Apidog, tạo một kịch bản, thêm lệnh apidog run vào .trae/rules/project_rules.md, rồi để Builder sử dụng nó ở thay đổi API tiếp theo.

Khi cần chạy cùng kịch bản trong CI mà không dùng agent, hãy xem Apidog CLI trong GitHub Actions để thiết lập secrets, reporter và kiểm soát mã thoát.

DEV Community