Agent của Cursor đã chỉnh sửa các tệp, chạy terminal của bạn, đọc đầu ra và khắc phục những lỗi nó gây ra. Bước tiếp theo là đưa các bài kiểm tra API của bạn vào vòng lặp đó: để Cursor chạy các kịch bản Apidog thực tế của bạn, đọc kết quả đạt hoặc không đạt và tiếp tục. Phần làm cho điều này hoạt động là một công cụ chạy dòng lệnh mà Cursor có thể gọi.
Công cụ chạy đó là Apidog CLI, một gói npm có tên `apidog-cli`. Nó chạy các kịch bản kiểm thử bạn đã xây dựng trực quan trong Apidog từ một terminal và thoát với mã trạng thái mà Cursor có thể xử lý. Hướng dẫn này bao gồm phần dành riêng cho Cursor: tệp quy tắc hướng dẫn Cursor quy trình làm việc của bạn, lời nhắc chạy một bài kiểm thử, cách chạy này hòa nhập vào vòng lặp chỉnh sửa-kiểm thử-sửa lỗi của nó, và máy chủ MCP tùy chọn cung cấp cho Cursor đặc tả API của bạn khi nó viết mã.
Nếu CLI chưa được cài đặt, hãy bắt đầu với cách cài đặt Apidog CLI với tác nhân mã hóa AI, hướng dẫn Cursor cài đặt và xác thực. Hãy quay lại khi `apidog --version` in ra một số. Bạn cũng cần một tài khoản Apidog với ít nhất một kịch bản kiểm thử đã lưu. Tải xuống Apidog nếu bạn chưa có.
“Sử dụng CLI trong Cursor” nghĩa là gì
Không có plugin Apidog cho Cursor, và bạn cũng không cần. Agent của Cursor đã chạy các lệnh shell trong terminal dự án của bạn. Vì vậy, việc sử dụng Apidog CLI trong Cursor có ba ý nghĩa:
- Dạy Cursor quy trình làm việc một lần bằng một quy tắc dự án, để nó biết lệnh, các cờ và mã thoát là nguồn đáng tin cậy.
- Để Agent chạy
apidog runnhư một bước bình thường trong vòng lặp của nó, giống như nó chạy các bài kiểm thử đơn vị của bạn. - Tùy chọn kết nối máy chủ Apidog MCP, để Cursor có thể đọc đặc tả API của bạn trong khi nó viết mã mà các bài kiểm thử đó kiểm tra.
Quy tắc này là điều khiến hướng dẫn này mang hình dạng của Cursor thay vì một hướng dẫn chung chung “mở terminal và gõ lệnh”.
Bước 1: Thêm quy tắc dự án
Cursor đọc các quy tắc dự án từ thư mục .cursor/rules tại thư mục gốc của repo của bạn. Mỗi quy tắc là một tệp .mdc với một khối frontmatter nhỏ, được kiểm soát phiên bản cùng với mã của bạn để toàn bộ nhóm có được hành vi tương tự.
Có hai cách để tạo một quy tắc: gõ /create-rule trong chat và mô tả những gì bạn muốn, hoặc mở Cursor Settings > Rules, Commands, nhấp vào + Add Rule. Bằng cách nào đó bạn sẽ nhận được một tệp trong .cursor/rules.
Lưu tệp này dưới dạng .cursor/rules/apidog-cli.mdc:
---
description: Cách chạy các bài kiểm thử API Apidog từ terminal
alwaysApply: false
---
# Chạy các bài kiểm thử API Apidog
Dự án này có các kịch bản kiểm thử API trong Apidog. Chạy chúng bằng
apidog-cli, đã được cài đặt toàn cục và đã được xác thực.
- Lệnh là `apidog run`. Thực thi nhị phân là `apidog`.
- Chạy một kịch bản duy nhất theo ID: `apidog run -t <scenarioId> -e <environmentId> -n 1 -r cli`
- `-t` là ID kịch bản kiểm thử, `-e` là ID môi trường.
- `-n 1` chạy một lần. `-r cli` in báo cáo dễ đọc ra terminal.
- Không truyền `--access-token`. Xác thực được xử lý bởi một lệnh `apidog login` trước đó.
- Mã thoát là nguồn đáng tin cậy: `0` nghĩa là mọi xác nhận đều vượt qua,
khác không nghĩa là thất bại. Báo cáo mã thoát, không chỉ là một bản tóm tắt.
- Nếu một cờ không xác định, hãy chạy `apidog run --help` và sử dụng cờ chính xác từ đó.
Không bao giờ đoán tên cờ.
- Sau khi thay đổi mã liên quan đến một điểm cuối, hãy chạy kịch bản liên quan
và đọc kết quả trước khi khẳng định thay đổi hoạt động.
Frontmatter rất quan trọng. description cùng với alwaysApply: false biến đây thành một quy tắc áp dụng thông minh: Cursor sẽ kéo nó vào khi cuộc trò chuyện liên quan đến việc chạy các bài kiểm thử, thay vì tiêu tốn ngữ cảnh trong mọi cuộc trò chuyện. Đặt alwaysApply: true để giữ nó luôn trong phạm vi. Để giới hạn nó trong một loại tệp, hãy bỏ mô tả và thêm một dòng globs, và Cursor sẽ tự động đính kèm nó khi một tệp phù hợp được mở.
Nội dung thực hiện công việc thực sự. Nó xác định hình dạng lệnh, cho biết nguồn xác thực đến từ đâu và nêu rõ dòng giữ cho tác nhân trung thực: mã thoát thắng mọi lời văn. Các tác nhân đôi khi đọc một báo cáo lỗi và gọi nó là “trông tốt”. Việc viết quy tắc đó xuống một lần có nghĩa là bạn không phải tự mình bắt lỗi.
Bước 2: Lấy lệnh từ Apidog
Trước khi bạn yêu cầu Agent chạy bất cứ điều gì, hãy lấy một lệnh đã biết là tốt. Đừng để Cursor đoán ID.
Mở kịch bản kiểm thử của bạn trong Apidog, chuyển đến tab CI/CD của nó và chọn tùy chọn dòng lệnh. Apidog sẽ xây dựng lệnh apidog run hoàn chỉnh với ID kịch bản, ID môi trường và mã truy cập đã được điền sẵn:
apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli
605067 là ID kịch bản kiểm thử và 1629989 là ID môi trường; của bạn sẽ khác. Vì bạn đã xác thực CLI trong quá trình cài đặt, hãy bỏ phần --access-token và giữ lại các ID. Đó là lệnh mà quy tắc của bạn đã chỉ dẫn Cursor sử dụng.
Bước 3: Để Agent chạy kiểm thử
Mở Agent của Cursor (chế độ chat chạy các lệnh terminal, không phải chỉnh sửa nội tuyến). Với quy tắc đã được thiết lập, lời nhắc sẽ ngắn gọn:
Chạy kịch bản kiểm thử Apidog của tôi và Hiển thị cho tôi toàn bộ đầu ra và cho tôi biết mã thoát.
Cursor đề xuất lệnh và, sau khi bạn chấp thuận, nó chạy lệnh trong terminal tích hợp:
apidog run -t 605067 -e 1629989 -n 1 -r cli
Theo mặc định, Cursor hỏi trước khi thực hiện một lệnh terminal, vì vậy bạn thấy chính xác những gì nó sắp chạy. Chấp thuận nó, và Agent sẽ chạy kịch bản, sau đó đọc lại quá trình thực thi và một bản tóm tắt.
Kiểm tra của bạn: hãy xem mã thoát, không phải bản tóm tắt. apidog run thoát với mã 0 khi mọi khẳng định đều vượt qua và khác 0 khi một cái thất bại. Hành vi đó là toàn bộ lý do điều này hoạt động như một cổng chặn, cho CI và cho Agent. Nếu Cursor nói “kiểm thử đã vượt qua” nhưng mã thoát khác 0, thì nó sai; hãy tin vào mã. Đây chính xác là thất bại mà quy tắc Bước 1 ngăn chặn.
Để có định dạng báo cáo khác hoặc nhiều lần lặp hơn, hãy yêu cầu Agent chạy apidog run --help để nó đọc danh sách cờ thực tế cho phiên bản đã cài đặt của bạn. Hướng dẫn Apidog CLI đầy đủ ghi lại mọi cờ, bao gồm các trình báo cáo html, json và junit cùng với lặp lại theo hướng dữ liệu.
Bước 4: Đọc báo cáo trong Cursor
Trình báo cáo -r cli in kết quả ra terminal mà Cursor đã đọc, điều này làm cho nó phù hợp cho công việc của Agent. Agent nhìn thấy các dòng giống như bạn: kịch bản nào đã chạy, mỗi yêu cầu, mỗi xác nhận và số lượng vượt qua hoặc thất bại cuối cùng.
Khi một lần chạy bị lỗi (màu đỏ), báo cáo sẽ nêu tên xác nhận bị lỗi, giá trị dự kiến và những gì điểm cuối trả về. Vì văn bản đó nằm trong ngữ cảnh của Agent, bạn có thể tiếp tục trong cùng một cuộc trò chuyện:
Kịch bản thất bại. Đọc xác nhận bị lỗi trong báo cáo, tìm trình xử lý tạo ra trường đó và đề xuất một bản sửa lỗi. Sau đó chạy lại kịch bản và cho tôi xem mã thoát mới.
Bây giờ bài kiểm thử là một phần của vòng lặp. Cursor chỉnh sửa trình xử lý, chạy lại apidog run, đọc mã thoát mới và tiếp tục hoặc thử lại. Các kiểm tra API của bạn nằm trong cùng một chu trình chỉnh sửa-kiểm thử-sửa lỗi mà Cursor sử dụng cho các bài kiểm thử đơn vị, ngoại trừ những bài kiểm thử này chạy chống lại các điểm cuối thực. Để biết mô hình rộng hơn, cách sử dụng tác nhân AI để kiểm thử API bao gồm nơi nó phù hợp và nơi không.
Tùy chọn: kết nối máy chủ Apidog MCP
CLI cho phép Cursor chạy các bài kiểm thử của bạn. Máy chủ Apidog MCP cho phép Cursor đọc đặc tả API của bạn trong khi nó viết mã. Hai thứ này chồng lên nhau: máy chủ MCP cung cấp lược đồ của bạn cho Cursor để nó tạo ra mã khớp với hợp đồng, và CLI xác minh mã đó dựa trên các kịch bản thực tế.
Cursor hỗ trợ các máy chủ MCP thông qua cấu hình JSON. Đặt các máy chủ có phạm vi dự án trong .cursor/mcp.json tại thư mục gốc của repo của bạn, hoặc các máy chủ toàn cục trong ~/.cursor/mcp.json. Cấu trúc là một đối tượng mcpServers được khóa bằng một tên, mỗi đối tượng có một command, một mảng args và các giá trị env tùy chọn:
{
"mcpServers": {
"apidog": {
"command": "npx",
"args": ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"],
"env": {
"APIDOG_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
}
}
}
}
Hai lưu ý. MCP bị khóa sau một công tắc trong một số cài đặt, vì vậy hãy mở Cài đặt Cursor, tìm phần Giao thức Ngữ cảnh Mô hình và xác nhận rằng máy chủ Apidog được bật. Và nếu bạn cam kết .cursor/mcp.json, đừng mã hóa cứng token; hãy tham chiếu một biến môi trường. Để thiết lập đầy đủ, bao gồm nơi lấy ID dự án và token, hãy xem hướng dẫn máy chủ Apidog MCP. Để có một quy trình làm việc đóng gói, có thể tái sử dụng thay vì tự cài đặt thủ công, hướng dẫn Apidog CLI với Claude Skills cho thấy phiên bản dựa trên kỹ năng.
Từ vòng lặp cục bộ đến CI
Khi Cursor đã chạy kịch bản cục bộ và xử lý mã thoát, bạn đã xác thực chính xác lệnh mà pipeline của bạn sẽ sử dụng. Việc chuyển sang CI là nhỏ: cùng một lệnh apidog run, với token được truyền dưới dạng một bí mật được che giấu thay vì đăng nhập đã lưu trữ. Bạn thậm chí có thể yêu cầu Cursor viết bước này, vì nó biết lệnh từ quy tắc của bạn:
Cơ chế của bước đó (bí mật, trình báo cáo, kiểm soát bằng mã thoát) có trong Apidog CLI trong GitHub Actions. Cùng một lệnh bây giờ chạy ở ba nơi, terminal của bạn, vòng lặp Agent của Cursor và CI, tất cả đều tin tưởng cùng một mã thoát.
Các vấn đề thường gặp
Quy tắc không áp dụng. Với description và alwaysApply: false, Cursor chỉ tải quy tắc khi nó đánh giá cuộc trò chuyện liên quan. Nếu một phiên kiểm thử không nhận ra nó, hãy đề cập đến nó bằng @apidog-cli trong chat, hoặc chuyển sang alwaysApply: true.
Agent không thể chạy lệnh. Nếu nó chỉ đề xuất lệnh thay vì chạy chúng, bạn có thể đang ở chế độ chỉnh sửa chứ không phải Agent, hoặc bạn đã bỏ lỡ lời nhắc phê duyệt. Xác nhận bạn đang ở trong cuộc trò chuyện của Agent và phê duyệt khi Cursor yêu cầu. Nếu các lần chạy terminal thất bại hoàn toàn, đó thường là vấn đề PATH apidog: command not found mà hướng dẫn cài đặt đã đề cập.
apidog whoami cho thấy bạn chưa được xác thực. Đăng nhập được lưu trữ trên máy của bạn, không phải trong Cursor. Tự chạy apidog login --with-token với một token mới từ Apidog, sau đó yêu cầu Agent xác nhận bằng apidog whoami. Giữ token không xuất hiện trong chat.
Nó tự ý tạo ra một cờ. Nếu một lần chạy thất bại với lỗi “tùy chọn không xác định”, Agent đã đoán một cờ không tồn tại trong phiên bản của bạn. Hãy yêu cầu nó chạy apidog run --help và sao chép chính xác cờ đó.
Tổng kết
Thiết lập Cursor bao gồm một tệp và một thói quen: một quy tắc .cursor/rules/apidog-cli.mdc xác định lệnh, nguồn xác thực và quy tắc mã thoát, cộng với thói quen để Agent chạy apidog run và tự bạn kiểm tra mã thoát. Thêm máy chủ Apidog MCP và Cursor cũng có thể đọc đặc tả của bạn trong khi nó viết mã.
Bạn vẫn tiếp tục tạo các kịch bản trực quan trong Apidog; Cursor chỉ đơn giản là chạy chúng. Từ đây, hãy trỏ cùng một lệnh vào pipeline của bạn với Apidog CLI trong GitHub Actions, hoặc đọc tài liệu tham khảo cờ đầy đủ trong hướng dẫn Apidog CLI đầy đủ.