Tác nhân Cascade của Windsurf chạy một vòng lặp: nó chỉnh sửa tệp, chạy lệnh terminal, đọc đầu ra và quyết định làm gì tiếp theo. Vậy tại sao các bài kiểm thử API của bạn không nằm trong vòng lặp đó? Chúng nằm trong Apidog phía sau giao diện người dùng đồ họa và chỉ chạy khi ai đó nhớ nhấp chuột. Cascade không bao giờ chạm đến chúng.
Cách khắc phục chỉ là một khối cấu hình. 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. Một khi CLI được cài đặt và Cascade biết nó tồn tại, Windsurf 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: kích hoạt lệnh, đọc mã thoát, sửa code nếu nó báo lỗi.
Nếu bạn chưa cài đặt CLI, hãy làm điều đó trước tiên. Bài viết Cách cài đặt Apidog CLI với tác nhân mã hóa AI hướng dẫn quá trình cài đặt npm, xác thực và lần chạy đầu tiên, với một tác nhân thực hiện thao tác gõ. Bài viết này giả định rằng apidog --version in ra một số và tài khoản Apidog của bạn đã được xác thực.
Đây là Windsurf nào
Windsurf là IDE tác nhân của Codeium, và tác nhân tích hợp của nó được gọi là Cascade. Cascade chạy cục bộ, đọc kho lưu trữ của bạn, chỉnh sửa tệp và thực thi các lệnh shell trong terminal tích hợp, yêu cầu phê duyệt dựa trên cài đặt tự động thực thi của bạn. Đây là trình chỉnh sửa và tác nhân của nó, không phải tiện ích mở rộng trình duyệt hay plugin tự động hoàn thành.
Nếu bạn chưa thiết lập nó, hãy bắt đầu với cách tải xuống và cài đặt Windsurf. Một khi Cascade được mở trong dự án của bạn, bạn có thể dạy nó về Apidog CLI thông qua cơ chế quy tắc riêng của nó, biến một lệnh "chạy bài kiểm thử của tôi" một lần thành thứ mà Cascade tự động tìm đến.
Bước 1: Thêm quy tắc Apidog vào .windsurf/rules
Cascade đọc các quy tắc dự án từ các tệp Markdown trước khi nó bắt đầu hoạt động. Đặt chúng trong thư mục .windsurf/rules/ tại thư mục gốc của kho lưu trữ, mỗi quy tắc một tệp. Windsurf vẫn đọc một tệp .windsurfrules đơn lẻ cũ tại thư mục gốc của không gian làm việc, và một tệp ~/.codeium/windsurf/memories/global_rules.md toàn cục áp dụng cho mọi dự án, nhưng đối với hướng dẫn theo từng dự án, thư mục .windsurf/rules/ là nơi thích hợp. Điều này được ghi lại trong tài liệu tham khảo về quy tắc và bộ nhớ của Windsurf.
Tạo .windsurf/rules/apidog.md với một khối như sau:
# Apidog API tests
This project has Apidog test scenarios. Run them with the Apidog CLI:
apidog run -t <scenario_id> -e <env_id> -r cli
Rules:
- Use the exact command above; do not invent flags. Run `apidog run --help` if unsure.
- `apidog run` exits 0 when every assertion passes, non-zero when any fails.
Treat exit 0 as pass and non-zero as fail. Report the real exit code.
- The machine is already authenticated via `apidog login`. Never add an
access token to the command or commit one to this file.
- After you change code that touches the API, run the scenario and act on the result.
Tại sao lại là một tệp quy tắc thay vì một tin nhắn trò chuyện? Một ID kịch bản được gõ vào trò chuyện sẽ biến mất khi phiên làm việc kết thúc. Một ID trong .windsurf/rules/apidog.md sẽ có sẵn cho mọi đồng đội và mọi phiên Cascade từ giờ trở đi. Nó được duy trì, được lập phiên bản trong Git, và Cascade tự động tải nó vào ngữ cảnh khi khởi động.
Bước 2: Lấy lệnh từ Apidog
Các giá trị <scenario_id> và <env_id> trong khối đó không phải là các chỗ giữ chỗ mà bạn phải đoán. Apidog sẽ tạo ra lệnh chính xác cho bạn.
Mở kịch bản kiểm thử trong Apidog, vào tab CI/CD của nó, và sao chép lệnh apidog run đã được tạo sẵn. Nó đã có sẵn ID kịch bản, ID môi trường và các cờ báo cáo chính xác. Dán lệnh đó vào tệp .windsurf/rules/apidog.md của bạn thay thế cho dòng ví dụ. Bây giờ quy tắc sẽ chứa một lệnh thực sự hoạt động với dự án của bạn, chứ không phải là một mẫu.
Để biết cấu trúc đầy đủ của lệnh đó và mọi cờ mà nó chấp nhận, hãy xem tài liệu tham khảo lệnh apidog run.
Bước 3: Yêu cầu Cascade chạy bài kiểm thử
Với quy tắc đã được thiết lập, hãy mở Cascade trong kho lưu trữ của bạn. Nó tải .windsurf/rules/apidog.md khi khởi động, vì vậy nó đã biết CLI có ở đó. 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 scenario and tell me the exit code.
Cascade phát hành lệnh apidog run từ quy tắc của bạn. Việc nó có chạy mà không cần nhắc nhở hay không phụ thuộc vào cài đặt tự động thực thi của bạn. Windsurf cung cấp bốn cấp độ: Disabled (mọi lệnh cần được phê duyệt), Allowlist Only (chỉ các lệnh khớp với danh sách cho phép của bạn mới tự động chạy), Auto (một phán đoán mô hình cao cấp), và Turbo (mọi thứ tự động chạy trừ các lệnh trong danh sách cấm). Ở chế độ Turbo, một lệnh apidog run đơn giản sẽ tự thực thi; ở các chế độ nghiêm ngặt hơn, Cascade sẽ tạm dừng và hỏi trước.
Nếu bạn muốn apidog run tự động thực thi mà không làm lỏng lẻo mọi thứ, hãy thêm nó vào danh sách cho phép của bạn. Cài đặt là windsurf.cascadeCommandsAllowList, có thể truy cập từ Bảng lệnh (Command Palette) trong phần Open Settings; thêm apidog và Cascade sẽ chạy lệnh mà không hỏi. Cài đặt danh sách cấm tương ứng là windsurf.cascadeCommandsDenyList, và danh sách cấm sẽ thắng khi một lệnh khớp với cả hai. Cả hai đều được đề cập trong tài liệu terminal của Windsurf. Một kịch bản chỉ đọc đối với môi trường staging chính xác là loại lệnh an toàn, trong không gian làm việc mà một mục trong danh sách cho phép được xây dựng cho.
Bước 4: Đọc báo cáo bên trong Windsurf
Khi một lần chạy báo lỗi, báo cáo sẽ có câu trả lời. Bộ báo cáo -r cli sẽ in kết quả từng bước và tóm tắt ngay trong terminal của Cascade: mỗi yêu cầu, mỗi 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 đủ để Cascade tìm ra cách khắc phục trong lần chạy tiếp theo.
Để có 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 bộ báo cáo HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
Bộ báo cáo html ghi một tệp độc lập vào ./apidog-reports. Giữ cli trong danh sách để Cascade 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 bộ báo cáo, bao gồm cả định dạng JUnit mà các bảng điều khiển CI phân tích cú pháp, hãy xem hướng dẫn đầy đủ về Apidog CLI và cách đọc báo cáo kiểm thử Apidog CLI.
Kiểm thử Windsurf trong vòng lặp riêng của nó
Điểm chính là điều gì xảy ra khi bạn ngừng hỏi và Cascade tự chạy kịch bản vì quy tắc đã yêu cầu nó làm vậy.
Hãy hình dung Cascade đ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 code, sau đó, thay vì tuyên bố thành công, nó chạy kịch bản Apidog của bạn đối với môi trường staging, đọc mã thoát và hành động dựa trên đó. Nếu xanh, nó tiếp tục. Nế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ử một bản sửa lỗi, và chạy lại. Bài kiểm thử API trở thành một phần của cùng vòng lặp chỉnh sửa-kiểm thử-sửa lỗi mà Cascade đã chạy các bài kiểm thử đơn vị của bạn. Bạn đã viết một quy tắc và Cascade đã tích hợp lệnh đó vào cách nó hoạt động.
Đây là mô hình ủy quyền-sau đó-xác minh giúp mọi quy trình làm việc của tác nhân an toàn. Cascade 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 xem tác nhân 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 tác nhân AI để kiểm thử API và khung kiểm thử AI Apidog.
Xác minh Cascade thực sự đang chạy CLI
Các tác nhân báo cáo thành công mà họ không thực sự đạt được, và Cascade cũng không ngoại lệ. Ba kiểm tra, theo thứ tự tần suất chúng phát hiện vấn đề.
Đầu tiên, xác nhận rằng lệnh đã chạy. Cascade hiển thị các lệnh nó thực thi và đầu ra của chúng trực tiếp trong terminal. Hãy tìm dòng apidog run ... và kết quả bên dưới nó. Nếu Cascade nói nó đã chạy các bài kiểm thử nhưng bạn không thấy lệnh, thì nó đã tóm tắt một điều gì đó mà nó chưa từng 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, cái quan trọng. Hỏi trực tiếp:
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à khác 0 khi có bất kỳ lỗi nào. Hành vi đơn lẻ đó cho phép Cascade, hoặc một pipeline, coi lần chạy đó như một cổng an toàn. Khi văn bản của Cascade 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 tế. Nếu một lần chạy thất bại với thông báo "scenario not found" (không tìm thấy kịch bản), Cascade có thể đã tự tạo hoặc nhớ nhầm ID. Kiểm tra lại các giá trị -t và -e so với tệp quy tắc của bạn và lệnh Apidog đã tạo trong tab CI/CD. Các ID trong .windsurf/rules/apidog.md là sự thật.
Tùy chọn: kết nối máy chủ Apidog MCP
Chạy apidog run từ một quy tắc bao gồm hầu hết những gì bạn cần. Để đi xa hơn một bước, hãy kết nối máy chủ MCP.
Cascade hỗ trợ Giao thức Ngữ cảnh Mô hình (Model Context Protocol). Windsurf đọc danh sách máy chủ của nó từ ~/.codeium/windsurf/mcp_config.json, bạn có thể chỉnh sửa trực tiếp hoặc quản lý thông qua bảng điều khiển Cascade MCP; định dạng được tài liệu hóa trong tài liệu tham khảo MCP của Windsurf, và cách thiết lập máy chủ MCP trong Windsurf hướng dẫn thông qua bảng điều khiển. Máy chủ Apidog MCP hiển thị các đặc tả API của bạn qua MCP, vì vậy Cascade có thể đọc lược đồ của bạn trong khi nó viết mã, chứ không phải chỉ sau đó. Việc phân chia công việc rõ ràng: CLI chạy các bài kiểm thử, và MCP cung cấp đặc tả cho tác nhân.
Khi Windsurf mắc lỗi
Một vài lỗi thường xuất hiện trong quá trình thiết lập.
Nó bỏ qua quy tắc. Nếu Cascade chạy một lệnh chung hoặc không chạy lệnh nào cả, có thể quy tắc không được tải. Xác nhận tệp nằm trong .windsurf/rules/ tại thư mục gốc của kho lưu trữ của bạn và có phần mở rộng .md. Mỗi tệp quy tắc được giới hạn ở 12.000 ký tự, vì vậy hãy giữ khối Apidog ngắn gọn. Khởi động lại Cascade sẽ buộc nó đọc lại từ đầu.
Nó vẫn truyền một mã thông báo truy cập. Nếu Cascade cố gắng thêm một mã thông báo truy cập vào lệnh, nó đang đoán từ các ví dụ công khai. Quy tắc của bạn đã bảo nó không làm vậy, vì máy đã được xác thực thông qua apidog login. Hãy củng cố dòng đó, và không bao giờ đặt một mã thông báo thực sự vào một tệp quy tắc mà bị commit. Để biết cách xác thực thực sự hoạt động, hãy xem hướng dẫn xác thực Apidog CLI.
Nó tự tạo ra một cờ. Lỗi "unknown option" có nghĩa là Cascade đã đoán một cờ mà phiên bản của bạn không có. Hãy yêu cầu nó chạy apidog run --help và sao chép cờ chính xác từ đó, điều 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 trong một lần chạy lỗi. Đây là lỗi tốn kém nhất, và là lý do tại sao quy tắc mã thoát có mặt trong cả tệp quy tắc của bạn và bước xác minh của bạn. Khi tóm tắt và mã thoát không khớp, mã thoát sẽ là đúng.
Từ tác nhân hàng ngày đến vòng lặp được kiểm thử
Đó là 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 quy tắc Apidog ngắn vào thư mục .windsurf/rules/ của kho lưu trữ, và Cascade 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 điểm cuối bị lỗi sẽ được phát hiện trong khi Cascade vẫn đang thực hiện thay đổi, chứ không phải sau khi nó đã triển khai.
Một bài kiểm thử phía sau giao diện người dùng đồ họa chỉ chạy khi con người nhấp chuột; một lệnh một dòng sẽ chạy bất cứ khi nào Cascade 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à tác nhân của bạn chạy chúng ở nơi bạn không quan sát. Để chạy cùng một lệnh trong một pipeline khi nó hoạt động cục bộ, bài viết Apidog CLI trong GitHub Actions đề cập đến các bí mật, bộ báo cáo và cổng mã thoát. Tải Apidog, xây dựng một kịch bản, thả lệnh apidog run của nó vào một quy tắc Windsurf, và xem Cascade sẽ tiếp nhận nó ở lần thay đổi tiếp theo.