DEV Community

Cover image for Cách sử dụng Apidog CLI trong Windsurf
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

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

#ai #api #cli #testing

Cascade của Windsurf 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 các bài kiểm thử API chỉ nằm trong giao diện Apidog và chỉ chạy khi ai đó nhấp chuột, Cascade sẽ không thể dùng chúng để xác minh thay đổi mã của mình.

Dùng thử Apidog ngay hôm nay

Cách tích hợp là dùng apidog-cli, gói npm cho phép chạy các kịch bản kiểm thử đã tạo trong Apidog từ terminal. Khi Cascade biết lệnh này, nó có thể chạy kiểm thử API tương tự kiểm thử đơn vị: thực thi lệnh, đọc mã thoát và sửa mã khi kiểm thử thất bại.

Trước khi tiếp tục, hãy bảo đảm CLI đã được cài đặt và xác thực:

apidog --version
Enter fullscreen mode Exit fullscreen mode

Nếu chưa cài đặt, 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 và máy đã được xác thực qua apidog login.

Windsurf và Cascade là gì?

Windsurf là IDE tác nhân của Codeium; tác nhân tích hợp là Cascade. Cascade có thể đọc kho mã, sửa tệp và chạy lệnh shell trong terminal tích hợp, tùy theo cài đặt phê duyệt hoặc tự động thực thi của bạn.

Nếu chưa thiết lập Windsurf, bắt đầu với cách tải xuống và cài đặt Windsurf.

Mục tiêu là lưu hướng dẫn chạy Apidog CLI thành quy tắc cấp dự án. Nhờ đó, Cascade có thể dùng cùng một lệnh qua nhiều phiên làm việc và cho mọi thành viên trong repository.

Bước 1: Tạo quy tắc Apidog trong .windsurf/rules

Cascade đọc quy tắc dự án từ các tệp Markdown trong thư mục:

.windsurf/rules/
Enter fullscreen mode Exit fullscreen mode

Tạo tệp sau tại thư mục gốc của repository:

.windsurf/rules/apidog.md
Enter fullscreen mode Exit fullscreen mode

Thêm nội dung:

# 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.
Enter fullscreen mode Exit fullscreen mode

Windsurf vẫn hỗ trợ tệp .windsurfrules cũ ở thư mục gốc workspace và tệp quy tắc toàn cục ~/.codeium/windsurf/memories/global_rules.md. Tuy nhiên, với cấu hình riêng cho repository, .windsurf/rules/ là vị trí phù hợp.

Xem thêm tài liệu quy tắc và bộ nhớ của Windsurf.

Không nên chỉ gửi ID kịch bản trong chat với Cascade. Chat sẽ mất ngữ cảnh khi kết thúc phiên, trong khi .windsurf/rules/apidog.md được lưu trong Git và dùng lại cho mọi phiên.

Bước 2: Sao chép lệnh thực tế từ Apidog

Không tự đoán <scenario_id> hoặc <env_id>. Apidog có thể tạo đúng lệnh cho kịch bản của bạn.

  1. Mở kịch bản kiểm thử trong Apidog.
  2. Chuyển đến tab CI/CD.
  3. Sao chép lệnh apidog run được tạo sẵn.
  4. Thay dòng lệnh mẫu trong .windsurf/rules/apidog.md.

Ví dụ, thay:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

bằng lệnh Apidog cung cấp cho dự án của bạn.

Lệnh được tạo sẵn đã chứa đúng ID kịch bản, ID môi trường và các cờ báo cáo cần thiết. Xem thêm tài liệu tham khảo lệnh apidog run.

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

Mở Cascade trong repository sau khi đã thêm quy tắc. Cascade sẽ tải .windsurf/rules/apidog.md khi bắt đầu phiên.

Sau khi sửa phần mã liên quan đến API, yêu cầu Cascade:

Run the Apidog scenario and tell me the exit code.
Enter fullscreen mode Exit fullscreen mode

Cascade sẽ dùng lệnh apidog run đã định nghĩa trong quy tắc.

Việc lệnh có chạy tự động hay cần phê duyệt phụ thuộc vào cấu hình thực thi của Windsurf:

  • Disabled: mọi lệnh cần phê duyệt.
  • Allowlist Only: chỉ lệnh trong danh sách cho phép được tự động chạy.
  • Auto: Windsurf tự đánh giá mức độ an toàn.
  • Turbo: tự chạy mọi lệnh trừ lệnh trong danh sách chặn.

Nếu muốn cho phép apidog run chạy tự động mà không bật quyền quá rộng, thêm apidog vào allowlist:

windsurf.cascadeCommandsAllowList
Enter fullscreen mode Exit fullscreen mode

Mở Command Palette → Open Settings, sau đó thêm:

apidog
Enter fullscreen mode Exit fullscreen mode

Danh sách chặn tương ứng là:

windsurf.cascadeCommandsDenyList
Enter fullscreen mode Exit fullscreen mode

Nếu một lệnh khớp cả allowlist lẫn denylist, denylist sẽ được ưu tiên. Tham khảo tài liệu terminal của Windsurf.

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

Với reporter cli, Apidog in kết quả trực tiếp vào terminal của Cascade:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Đầu ra bao gồm:

  • Từng yêu cầu được chạy.
  • Từng assertion.
  • Assertion thành công hoặc 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 giúp Cascade xác định lỗi, sửa mã và chạy lại kịch bản.

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

apidog run -t <scenario_id> -e <env_id> -r cli,html
Enter fullscreen mode Exit fullscreen mode

Reporter html ghi báo cáo vào:

./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Nên giữ cli để Cascade vẫn đọc được đầu ra nội tuyến trong terminal. Để xem các reporter khác, bao gồm JUnit cho CI, tham khảo:

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

Khi quy tắc đã tồn tại, quy trình làm việc có thể trở thành:

  1. Cascade sửa một handler hoặc endpoint.
  2. Cascade chạy apidog run với môi trường staging.
  3. Cascade đọc mã thoát và đầu ra assertion.
  4. Nếu kiểm thử thành công, Cascade tiếp tục.
  5. Nếu kiểm thử thất bại, Cascade đọc lỗi, sửa mã và chạy lại.

Ví dụ, khi Cascade thay đổi 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 không đúng.
  • Trường bắt buộc bị thiếu.
  • Giá trị phản hồi không khớp.
  • Dữ liệu không đúng định dạng.

Kiểm thử API lúc này là một phần của vòng lặp sửa mã → kiểm thử → sửa lỗi, thay vì là bước thủ công sau cùng.

Đây là mô hình ủy quyền rồi xác minh: Cascade thực thi lệnh và đọc kết quả, còn bạn vẫn thiết kế và quản lý kịch bản trực quan trong Apidog. Xem thêm:

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

Không nên chỉ tin vào phần tóm tắt của tác nhân. Hãy kiểm tra theo ba bước.

1. Kiểm tra lệnh đã được thực thi

Trong terminal của Cascade, tìm lệnh:

apidog run ...
Enter fullscreen mode Exit fullscreen mode

và đầu ra ngay bên dưới nó.

Nếu Cascade nói đã chạy kiểm thử 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 mã thoát

Hỏi trực tiếp:

What was the exit code of that apidog run command?
Enter fullscreen mode Exit fullscreen mode

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

0       = tất cả assertion thành công
khác 0 = có ít nhất một assertion thất bại
Enter fullscreen mode Exit fullscreen mode

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

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

Nếu nhận lỗi scenario not found, Cascade có thể đang dùng sai ID hoặc tự đoán ID.

Đối chiếu lại:

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

Tệp quy tắc trong repository phải là nguồn tham chiếu mà Cascade sử dụng.

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

apidog run trong quy tắc đã đáp ứng phần lớn nhu cầu kiểm thử. Nếu muốn Cascade đọc đặc tả API khi viết mã, bạn có thể kết nối MCP.

Windsurf hỗ trợ Model Context Protocol và đọc cấu hình máy chủ từ:

~/.codeium/windsurf/mcp_config.json
Enter fullscreen mode Exit fullscreen mode

Bạn có thể chỉnh sửa trực tiếp tệp này hoặc quản lý qua bảng điều khiển Cascade MCP. Xem tài liệu MCP của Windsurf và cách thiết lập máy chủ MCP trong Windsurf.

Máy chủ Apidog MCP giúp Cascade truy cập đặc tả API qua MCP.

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

Apidog CLI  -> chạy kịch bản kiểm thử
Apidog MCP  -> cung cấp đặc tả API cho tác nhân
Enter fullscreen mode Exit fullscreen mode

Xử lý lỗi thiết lập thường gặp

Cascade bỏ qua quy tắc

Kiểm tra:

  • Tệp nằm đúng tại .windsurf/rules/apidog.md.
  • Tệp có phần mở rộng .md.
  • Thư mục .windsurf/ nằm ở gốc repository.
  • Nội dung quy tắc ngắn gọn; mỗi tệp quy tắc có giới hạn 12.000 ký tự.

Khởi động lại Cascade để buộc tải lại quy tắc.

Cascade thêm access token vào lệnh

Máy đã xác thực qua:

apidog login
Enter fullscreen mode Exit fullscreen mode

Không thêm access token vào lệnh và không commit token vào tệp quy tắc. Nếu Cascade vẫn thêm token, nhấn mạnh lại điều này trong apidog.md.

Xem hướng dẫn xác thực Apidog CLI.

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

Lỗi unknown option thường có nghĩa Cascade đã đoán cờ sai. Yêu cầu nó kiểm tra phiên bản CLI đang cài:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Sau đó chỉ dùng các cờ xuất hiện trong đầu ra của lệnh này.

Cascade báo thành công dù lệnh thất bại

Luôn dùng mã thoát làm nguồn xác minh cuối cùng:

exit code 0       -> thành công
exit code khác 0  -> thất bại
Enter fullscreen mode Exit fullscreen mode

Nếu tóm tắt của Cascade và mã thoát không khớp, mã thoát là kết quả đúng.

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

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

  1. Cài apidog-cli theo hướng dẫn cài đặt.
  2. Thêm lệnh apidog run thực tế vào .windsurf/rules/apidog.md.
  3. Yêu cầu Cascade chạy kịch bản và báo cáo mã thoát.

Sau đó, Cascade có thể chạy kiểm thử API trong cùng vòng lặp mà nó dùng để chỉnh sửa mã. Lỗi endpoint được phát hiện ngay khi Cascade vẫn đang xử lý thay đổi, thay vì sau khi đã triển khai.

Bạn vẫn xây dựng kịch bản trực quan trong Apidog, nhưng Cascade có thể thực thi chúng từ terminal vào đúng thời điểm. Khi lệnh đã chạy ổn định ở máy cục bộ, bạn có thể đưa cùng lệnh đó vào CI bằng Apidog CLI trong GitHub Actions.

Tải Apidog, tạo một kịch bản, thêm lệnh apidog run vào quy tắc Windsurf và để Cascade dùng nó ở lần thay đổi API tiếp theo.

Top comments (0)