Trae là một vòng lặp. Agent Builder của nó đọc kho lưu trữ của bạn, chỉnh sửa tệp, chạy lệnh trong terminal và đọc kết quả đầu ra để quyết định bước tiếp theo. Vậy tại sao các bài kiểm thử API của bạn lại không nằm trong vòng lặp đó? Chúng nằm trong Apidog phía sau giao diện đồ họa (GUI) và chỉ chạy khi ai đó nhớ nhấp chuột. Agent của bạn không bao giờ chạm tới chúng.
Cách khắc phục là một khối cấu hình duy nhất. Apidog CLI là một gói npm, apidog-cli, chạy các kịch bản kiểm thử bạn đã xây dựng trong Apidog trực tiếp từ terminal. Khi CLI được cài đặt và Trae biết nó tồn tại, Builder sẽ chạy một kịch bản Apidog giống như cách nó chạy các bài kiểm thử đơn vị của bạn: thực thi lệnh, đọc mã thoát, và sửa mã nếu nó báo lỗi (màu đỏ).
nút
Nếu bạn chưa cài đặt CLI, hãy làm điều đó 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à lần chạy đầu tiên, với agent thực hiện việc nhập liệu. Bài viết này giả định rằng apidog --version in ra một con số và tài khoản Apidog của bạn đã được xác thực.
Bài viết này nói về Trae nào
Trae là một IDE AI của ByteDance, được xây dựng trên VS Code, với chế độ agent gọi là Builder có khả năng tự chỉnh sửa tệp và chạy lệnh terminal. Bạn có thể đọc chi tiết sản phẩm trên trang web chính thức của Trae. Bài viết này nói về IDE dành cho máy tính để bàn, không phải dự án nghiên cứu trae-agent độc lập trên GitHub. Nếu bạn mở Trae, thấy một bảng chat bên cạnh trình soạn thảo của mình và có thể chuyển agent sang Builder, bạn đã đúng chỗ rồi đó.
Sự khác biệt này quan trọng vì Trae có cách riêng để học các quy tắc dự án, và cơ chế đó biến một lần “chạy kiểm thử của tôi” thành một thứ mà Builder tự động thực hiện. Cơ chế đó là một tệp quy tắc dự án. Nếu bạn muốn phiên bản độc lập với công cụ của quy trình làm việc này trước, hướng dẫn Apidog CLI đầy đủ sẽ đề cập đến CLI một cách riêng.
Bước 1: Thêm tệp quy tắc dự án
Trae đọc các tệp quy tắc trước khi Builder bắt đầu làm việc. Tệp cấp dự án nằm tại .trae/rules/project_rules.md tại thư mục gốc của kho lưu trữ của bạn, theo tài liệu quy tắc của Trae. Agent tải các quy tắc này trong quá trình khởi tạo và tham chiếu chúng khi nó tạo và chỉnh sửa mã. Ngoài ra còn có tệp user_rules.md cấp người dùng áp dụng cho tất cả các dự án của bạn; đối với quy trình làm việc này, một tệp dự án tại thư mục gốc của repo là đủ.
Tạo .trae/rules/project_rules.md và thêm một khối ngắn để đặt tên cho CLI, lệnh kịch bản chính xác và các quy tắc giúp Builder hoạt động đáng tin cậy:
## 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ừ đó.
Đây là lý do tại sao bạn viết CLI vào project_rules.md thay vì đề cập nó trong chat. Một ID kịch bản được gõ vào bảng chat sẽ biến mất khi phiên làm việc kết thúc. Một ID trong .trae/rules/project_rules.md sẽ tồn tại cho mọi đồng đội và mọi lần chạy Builder từ bây giờ. Trae cũng đọc các thư mục .trae/rules/ trong các thư mục con, do đó một monorepo có thể giữ các quy tắc riêng cho từng dịch vụ bên cạnh mỗi dịch vụ.
Bước 2: Lấy lệnh từ Apidog
Bạn không cần phải đoán lệnh. Mở kịch bản kiểm thử trong Apidog, chuyển đến tab CI/CD của nó và sao chép dòng apidog run đã được tạo. Nó đã có sẵn ID kịch bản thực sau -t và ID môi trường sau -e, vì vậy bạn đang dán một lệnh mà Apidog biết là hợp lệ thay vì tự tạo ID.
Thêm các ID chính xác đó vào khối trong .trae/rules/project_rules.md, thay thế các chỗ giữ chỗ <scenario_id> và <env_id>. Để biết đầy đủ các cờ và chức năng của chú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ử
Khi khối đã được thêm vào, hãy chuyển agent của Trae sang Builder và khởi động nó trong repo của bạn. Builder tải project_rules.md khi khởi tạo, vì vậy nó đã biết CLI tồn tại. Hãy thực hiện một thay đổi liên quan đến API của bạn, hoặc chỉ yêu cầu nó chạy kiểm tra:
Run the Apidog test scenario and tell me the exit code.
Builder thực thi lệnh apidog run từ tệp quy tắc của bạn. Mô hình phê duyệt của Trae rất quan trọng ở đây: khi agent muốn chạy một lệnh shell, nó sẽ đề xuất lệnh và hiển thị nút Run, và lệnh chỉ được thực thi trong terminal của Trae sau khi bạn nhấp vào. Khi nó chạy, Builder tự động đọc và phân tích đầu ra. Vì vậy, bạn chỉ cần phê duyệt apidog run một lần, và agent sẽ xử lý kết quả từ đó.
Trình báo cáo -r cli in ra kết quả từng bước và một bản tóm tắt ngay trong terminal, nơi Builder đọc từng yêu cầu và xác nhận khi chúng xảy ra. Bạn muốn thấy quá trình chạy được thực thi và Builder báo cáo lại cả bản tóm tắt lẫn mã thoát.
Bước 4: Đọc báo cáo bên trong Trae
Khi một lần chạy báo lỗi (màu đỏ), báo cáo sẽ có câu trả lời. Với -r cli, Builder nhận được một bản phân tích dễ đọc trong terminal của Trae: từng yêu cầu, từng xác nhận, và cái nào đã thất bại với giá trị mong đợi so với giá trị thực tế. Xác nhận thất bại sẽ nêu tên trường hoặc mã trạng thái chính xác, điều này thường đủ để Builder tìm ra cách khắc phục.
Đối với một báo cáo bạn 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 một tệp độc lập vào ./apidog-reports. Giữ cli trong danh sách để Builder vẫn nhận được đầu ra nội tuyến mà nó đọc để quyết định bước tiếp theo. Đối với mọi trình báo cáo, bao gồm định dạng JSON và JUnit mà các bảng điều khiển CI phân tích, hãy 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ều quan trọng là điều gì xảy ra khi bạn ngừng yêu cầu và Builder tự động chạy kịch bản vì project_rules.md đã yêu cầu nó.
Hãy hình dung Builder đang chỉnh sửa một trình xử lý xây dựng phản hồi thanh toán. Vòng lặp của nó thay đổi: nó chỉnh sửa mã, sau đó, thay vì tuyên bố chiến thắng, nó chạy kịch bản Apidog của bạn trên môi trường staging, đọc mã thoát và hành động dựa trên đó. Nếu thành công (màu xanh), nó sẽ tiếp tục. Nếu thất bại (màu đỏ), nó mở báo cáo, đọc xem xác nhận nào đã thất bại (mã trạng thái, trường bị thiếu, giá trị sai), thử khắc phục và chạy lại. Kiểm thử API trở thành một phần của vòng lặp sửa-kiểm thử-khắc phục mà Builder đã thực hiện với các bài kiểm thử đơn vị của bạn. Bạn đã viết một hướng dẫn và Builder đã tích hợp lệnh đó vào cách nó đã hoạt động.
Đây là mô hình ủy quyền-rồi-xác minh giúp mọi quy trình làm việc của agent trở nên an toàn. Builder chạy lệnh và đọc kết quả; bạn tiếp tục tạo kịch bản một cách trực quan trong Apidog và kiểm tra ngẫu nhiên xem agent có đọc mã thoát một cách trung thực hay không. Để biết mẫu rộng hơn, hãy xem cách sử dụng agent AI để kiểm thử API và khung kiểm thử AI của Apidog.
Xác minh Trae thực sự đang chạy CLI
Các agent báo cáo thành công mà chúng không thực sự đạt được, và Builder cũng không ngoại lệ. Có ba cách kiểm tra, theo thứ tự mức độ thường xuyên chúng phát hiện vấn đề.
Đầu tiên, xác nhận lệnh đã chạy. Trae hiển thị các lệnh mà Builder đã thực thi và kết quả đầu ra của chúng trong terminal. Tìm dòng apidog run theo nghĩa đen và kết quả bên dưới nó. Nếu Builder nói rằng nó đã chạy các bài kiểm thử nhưng bạn không thấy lệnh, điều đó có nghĩa là nó đã tóm tắt một cái gì đó mà nó chưa bao giờ làm. Yêu cầu nó chạy lại và hiển thị đầu ra thô.
Thứ hai, xác nhận mã thoát:
What was the exit code of that apidog run command?
apidog run thoát với mã 0 khi mọi xác nhận đều thành công và mã khác 0 khi có bất kỳ lỗi nào. Hành vi đơn giản đó cho phép Builder, hoặc một pipeline, coi lần chạy là một cổng kiểm tra sạch. Khi văn xuôi của Builder nói “kiểm thử đã vượt qua” nhưng mã thoát khác 0, thì mã thoát mới là đúng.
Thứ ba, xác nhận nó đã sử dụng kịch bản thực. Nếu một lần chạy thất bại với lỗi “không tìm thấy kịch bản,” Builder có thể đã tự tạo hoặc nhớ sai ID. Kiểm tra lại các giá trị -t và -e so với project_rules.md và lệnh Apidog đã tạo trong tab CI/CD. Các ID trong tệp quy tắc của bạn là sự thật.
Tùy chọn: kết nối máy chủ Apidog MCP
Chạy apidog run từ project_rules.md bao gồm hầu hết những gì bạn cần. Kết nối một máy chủ MCP tiến thêm một bước nữa. Các agent của Trae hoạt động như các client MCP, vì vậy Builder có thể gọi các công cụ mà máy chủ MCP cung cấp.
Để thêm một máy chủ, hãy mở cài đặt của Trae, chuyển đến tab MCP, và chọn một máy chủ từ marketplace hoặc chọn Add Manually và dán một khối JSON với command, args, và env của máy chủ, theo hướng dẫn của Trae về việc thêm máy chủ MCP. Máy chủ Apidog MCP hiển thị các đặc tả API của bạn qua MCP, vì vậy Builder có thể đọc lược đồ của bạn trong khi nó viết mã, chứ không chỉ sau khi hoàn thành. Sự phân công lao động rõ ràng: CLI chạy các bài kiểm thử, và MCP cung cấp đặc tả cho agent.
Khi Trae mắc lỗi
Một vài lỗi thường xuyên xuất hiện trong quá trình thiết lập.
Nó bỏ qua tệp quy tắc. Nếu Builder chạy một lệnh chung hoặc không chạy lệnh nào, tệp có thể không được tải. Xác nhận rằng nó nằm tại .trae/rules/project_rules.md ở thư mục gốc của kho lưu trữ của bạn và thư mục được đặt tên là rules, không phải rule. Khởi động lại phiên làm việc sẽ buộc đọc lại các quy tắc.
Nó vẫn truyền mã thông báo truy cập. Nếu Builder cố gắng thêm --access-token, nó đang đoán từ các ví dụ công khai. Khối đã nói với nó không làm như vậy, vì máy đã được xác thực qua apidog login. Củng cố dòng đó, và không bao giờ đặt mã thông báo thực vào project_rules.md. Để biết cách CLI xử lý thông tin xác thực trong sử dụng tương tác và trong CI, hãy xem xác thực Apidog CLI.
Nó tự tạo một cờ (flag). Lỗi “tùy chọn không xác định” có nghĩa là Builder đã đoán một cờ mà phiên bản của bạn không có. Hãy bảo nó chạy apidog run --help và sao chép cờ chính xác từ đó, cờ này luôn đúng với phiên bản đã cài đặt của bạn.
Nó báo cáo thành công một lần chạy thất bại. Đây là lỗi tốn kém nhất, và là lý do tại sao quy tắc mã thoát nằm trong project_rules.md của bạn và là bước xác minh của bạn. Khi bản tóm tắt và mã thoát không khớp, mã thoát sẽ là yếu tố quyết định.
Từ agent hàng ngày đến vòng lặp được kiểm thử
Đó là cách thiết lập. Cài đặt apidog-cli một lần theo hướng dẫn cài đặt, thêm một khối Apidog ngắn vào .trae/rules/project_rules.md, và Builder sẽ biết cách chạy các bài kiểm thử API của bạn và đọc kết quả bên trong cùng một vòng lặp mà nó đã sử dụng để chỉnh sửa mã. Một endpoint bị hỏng sẽ được phát hiện trong khi Builder vẫn đang làm việc trên thay đổi, chứ không phải sau khi nó được triển khai.
Một bài kiểm thử phía sau giao diện đồ họa (GUI) chỉ chạy khi con người nhấp chuột; một lệnh một dòng chạy bất cứ khi nào Builder quyết định. Bạn tiếp tục xây dựng các kịch bản một cách trực quan trong Apidog, và agent của bạn sẽ chạy chúng mà bạn không cần phải giám sát. Tải xuống Apidog, xây dựng một kịch bản, đặt lệnh apidog run của nó vào .trae/rules/project_rules.md, và xem Builder thực hiện nó ở lần thay đổi tiếp theo. Khi bạn sẵn sàng chạy cùng một kịch bản mà không có agent, Apidog CLI trong GitHub Actions bao gồm các bí mật, trình báo cáo và kiểm soát mã thoát cho CI.