Claude Code là một vòng lặp: nó chỉnh sửa tệp, chạy lệnh trong terminal của bạn, đọc kết quả và quyết định hành động 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, sau một giao diện người dùng đồ 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 đến chúng.
Giải pháp là một khối cấu hình đơn giản. 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. Sau khi CLI được cài đặt và Claude Code biết nó tồn tại, agent của bạn 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, sửa mã nếu nó báo lỗi.
Hướng dẫn này bao gồm phần dành riêng cho Claude Code mà hướng dẫn cài đặt chung bỏ qua: dòng chính xác cho tệp CLAUDE.md của bạn, cách Claude Code chạy apidog run theo mô hình quyền hạn của nó, và cách đọc kết quả bên trong vòng lặp chỉnh sửa-kiểm thử-sửa lỗi của chính nó.
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 agent mã hóa AI hướng dẫn qua quá trình cài đặt npm và lần chạy đầu tiên, với agent thực hiện việc gõ lệnh. 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.
Đây là Claude Code nào
Đây là Claude Code CLI, agent mã hóa của Anthropic chạy trong terminal (hoặc ứng dụng desktop) của bạn. Nó đọc kho lưu trữ của bạn, chỉnh sửa tệp và chạy các lệnh shell, yêu cầu phê duyệt dựa trên chế độ quyền hạn của bạn. Nó không phải là ứng dụng trò chuyện Claude và không phải là một lệnh gọi API đơn thuần. Nếu bạn chạy claude trong một kho lưu trữ và nhận được một agent tương tác đề xuất các chỉnh sửa và chạy lệnh, bạn đang ở đúng chỗ. Các lệnh bạn viết cho terminal nằm trong các lệnh gạch chéo của Claude Code và tệp quy tắc của nó, và tệp quy tắc đó là nơi Apidog CLI thuộc về.
Sự phân biệt này quan trọng vì Claude Code có cách riêng để học các quy tắc dự án, và cơ chế đó biến một lệnh "chạy kiểm thử của tôi" một lần thành thứ mà Claude tự động thực hiện. Cơ chế đó là CLAUDE.md.
Bước 1: Thêm khối Apidog vào CLAUDE.md
Claude Code đọc các tệp CLAUDE.md khi bắt đầu mỗi phiên. Đây là phần tương ứng trực tiếp với AGENTS.md cho Codex; thực tế tài liệu của Anthropic lưu ý rằng Claude Code đọc CLAUDE.md, không phải AGENTS.md, và gợi ý nhập một AGENTS.md hiện có bằng @AGENTS.md nếu bạn có một tệp như vậy cho một agent khác. Nếu bạn đã thiết lập Apidog CLI trong Codex, đây là ý tưởng tương tự với tên tệp khác.
Đặt một tệp CLAUDE.md tại thư mục gốc của kho lưu trữ của bạn (Claude Code cũng chấp nhận ./.claude/CLAUDE.md, và một tệp ~/.claude/CLAUDE.md toàn cục cho các cài đặt mặc định cá nhân). Claude Code đi lên cây thư mục từ nơi bạn khởi chạy nó và tải mọi tệp CLAUDE.md mà nó tìm thấy, vì vậy một tệp tại thư mục gốc của kho lưu trữ sẽ có hiệu lực cho mọi phiên. Thêm một khối ngắn như sau:
## Kiểm thử API với Apidog CLI
Dự án này có các kịch bản kiểm thử Apidog. Để kiểm tra API, hãy chạy:
`apidog run -t <scenario_id> -e <env_id> -r cli`
- Mã thoát 0 có nghĩa là mọi xác nhận đều thành công. Mã khác 0 có nghĩa là có lỗi; hãy mở báo cáo và sửa lỗi trước khi tiếp tục.
- Máy đã được xác thực qua `apidog login`. Không bao giờ thêm cờ `--access-token` và không bao giờ đặt mã token 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 cờ chính xác từ đó.
Đây là lý do tại sao bạn viết CLI vào CLAUDE.md thay vì đề cập trong cuộc trò chuyện. Một ID kịch bản được gõ vào một phiên sẽ biến mất khi phiên đó kết thúc. Một ID trong CLAUDE.md sẽ tồn tại cho mọi thành viên nhóm và mọi lần chạy Claude Code từ bây giờ. Tệp được tải hoàn toàn khi khởi chạy và tồn tại sau lệnh /compact, vì vậy hướng dẫn vẫn hoạt động trong toàn bộ phiên.
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 giá trị bạn đoán. Mở kịch bản kiểm thử của bạn trong Apidog, chuyển đến tab CI/CD và sao chép lệnh apidog run ... đã được tạo. Nó đã có sẵn ID kịch bản thực, ID môi trường và trình báo cáo -r cli được điền. Dán chính xác các ID đó vào khối CLAUDE.md của bạn.
Trình báo cáo -r cli in ra kết quả từng bước và tóm tắt ngay trong terminal, đây chính xác là đầu ra mà Claude Code đọc để quyết định bước tiếp theo. Để biết chi tiết đầy đủ về mọi cờ, hãy xem hướng dẫn Apidog CLI hoàn chỉnh và tham chiếu lệnh apidog run.
Bước 3: Yêu cầu Claude Code chạy kiểm thử
Với khối đã được đặt vào vị trí, hãy khởi động Claude Code trong kho lưu trữ của bạn:
claude
Claude Code tải CLAUDE.md khi nó 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. Claude Code sẽ phát hành lệnh apidog run từ CLAUDE.md của bạn.
Ở đây, mô hình quyền hạn trở nên quan trọng. Trong chế độ mặc định, Claude Code sẽ hỏi trước khi chạy một lệnh shell mà nó chưa thấy được phê duyệt. Hãy phê duyệt lệnh apidog run khi nó nhắc. Để không bị hỏi về một lệnh mà bạn tin tưởng, hãy thêm một quy tắc quyền hạn để CLI chạy mà không cần nhắc: chạy /permissions trong phiên, hoặc thêm một quy tắc cho phép đối với Bash(apidog run *) trong .claude/settings.json. Một kịch bản kiểm thử chỉ đọc đối với môi trường staging là một lệnh an toàn để cho phép. Đối với các lần chạy không giám sát, có --dangerously-skip-permissions, bỏ qua hoàn toàn lời nhắc; hãy lưu cái đó cho CI, không phải cho công việc hàng ngày của bạn.
Bạn muốn thấy quá trình chạy được thực thi và Claude Code báo cáo lại cả tóm tắt và mã thoát, chứ không chỉ một câu khẳng định thành công.
Bước 4: Đọc báo cáo bên trong Claude Code
Khi một lần chạy báo lỗi, báo cáo sẽ có câu trả lời. Với -r cli, Claude Code nhận được một bản phân tích dễ đọc trong terminal: mỗi yêu cầu, mỗi xác nhận và xác nhận 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 đủ để Claude Code tìm ra cách sửa lỗi.
Để có một báo cáo bạn có thể mở trong trình duyệt hoặc gửi cho đồng nghiệp, 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 để Claude Code 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 định dạng JUnit mà bảng điều khiển CI phân tích và các trình báo cáo khác, hãy xem báo cáo kiểm thử Apidog CLI.
Claude Code kiểm thử bên trong vòng lặp của chính nó
Vấn đề là điều gì xảy ra khi bạn ngừng yêu cầu và Claude Code tự chạy kịch bản vì CLAUDE.md đã bảo nó làm vậy.
Hãy hình dung Claude Code 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 đối với 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ó tiếp tục. Nếu thất bại (màu đỏ), nó mở báo cáo, đọc xác nhận nào đã thất bại (mã trạng thái, trường bị thiếu, giá trị sai), thử 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à Claude Code đã chạy các bài kiểm thử đơn vị của bạn. Bạn đã viết một hướng dẫn và Claude đã 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 agent trở nên an toàn. Claude Code 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 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 cho kiểm thử API và bộ công cụ kiểm thử AI của Apidog.
Xác minh Claude Code có thực sự chạy CLI hay không
Các agent báo cáo thành công mà chúng không đạt được, và Claude Code 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 lệnh có chạy hay không. Claude Code hiển thị các lệnh nó đã thực thi và đầu ra của chúng trực tiếp. Tìm dòng apidog run ... và kết quả bên dưới. Nếu Claude nói nó đã chạy các bài kiểm thử nhưng bạn không thấy lệnh, nó đã tóm tắt một cái gì đó mà nó chưa bao giờ làm. Hãy 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: “Mã thoát của lệnh apidog run đó là gì?” 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 Claude Code, hoặc một pipeline, coi lần chạy đó là một cổng kiểm soát sạch sẽ. Khi văn bản của Claude nói “kiểm thử đã vượt qua” nhưng mã thoát khác 0, 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 thông báo “không tìm thấy kịch bản,” Claude có thể đã tự tạo hoặc nhớ sai một ID. Hãy kiểm tra lại các giá trị -t và -e so với CLAUDE.md và lệnh mà Apidog đã tạo trong tab CI/CD. Các ID trong CLAUDE.md là sự thật.
Tùy chọn: kết nối máy chủ Apidog MCP
Chạy apidog run từ CLAUDE.md bao gồm hầu hết những gì bạn cần. Để tiến xa hơn một bước, hãy kết nối một máy chủ MCP để Claude Code có thể đọc đặc tả API của bạn trong khi nó viết mã, chứ không chỉ kiểm thử sau khi hoàn thành.
Claude Code hỗ trợ Giao thức Ngữ cảnh Mô hình (Model Context Protocol). Bạn thêm một máy chủ bằng claude mcp add ... hoặc bằng cách commit một tệp .mcp.json tại thư mục gốc dự án của bạn và chọn --scope project để toàn bộ nhóm đều nhận được nó. Máy chủ Apidog MCP hiển thị các đặc tả API của bạn qua MCP, vì vậy Claude đọc schema của bạn khi nó mã hóa. Hãy nghĩ về nó như sự phân công lao động: CLI chạy các bài kiểm thử, MCP cung cấp đặc tả cho agent.
Khi Claude Code làm sai
Một vài lỗi thường xuất hiện trong quá trình thiết lập.
Nó bỏ qua khối CLAUDE.md. Nếu Claude chạy một lệnh chung hoặc không chạy lệnh nào, khối đó có thể không được tải. Xác nhận tệp được đặt tên chính xác là CLAUDE.md và nằm ở thư mục gốc của kho lưu trữ hoặc thư mục cha của thư mục hiện tại của bạn. Chạy /memory trong phiên để liệt kê các tệp mà Claude thực sự đã tải; nếu tệp của bạn không có ở đó, Claude không thể nhìn thấy nó. Khởi động lại phiên sẽ buộc đọc lại từ đầu.
Nó vẫn truyền một mã truy cập. Nếu Claude 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 điều đó, vì máy đã được xác thực qua apidog login. Củng cố lại dòng đó, và không bao giờ đặt mã token thực vào CLAUDE.md. Để biết cách máy xác thực một lần, hãy xem xác thực Apidog CLI.
Nó tự tạo ra một cờ. Lỗi “unknown option” có nghĩa là Claude đã đ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 chính xác 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 cho một lần chạy thất bại. Đây là lỗi tốn kém nhất, và là lý do quy tắc mã thoát nằm trong CLAUDE.md 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 là đúng.
Từ một agent hàng ngày đến một vòng lặp đã được kiểm thử
Đó là phần 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 tệp CLAUDE.md của kho lưu trữ của bạn, và Claude Code 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 vòng lặp mà nó đã sử dụng để chỉnh sửa mã. Một điểm cuối bị hỏng sẽ bị phát hiện khi Claude vẫn đang làm việc trên thay đổi, không phải sau khi nó được triển khai.
Một bài kiểm thử đằng sau giao diện người dùng đồ họa (GUI) 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 Claude 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 chạy chúng ở nơi bạn không theo dõi. Tải xuống Apidog, xây dựng một kịch bản, thả lệnh apidog run của nó vào CLAUDE.md, và xem Claude chọn nó trong thay đổi tiếp theo. Khi bạn sẵn sàng chạy cùng một lệnh trong một pipeline mà không có Claude, Apidog CLI trong GitHub Actions bao gồm các khóa bí mật, trình báo cáo và kiểm soát mã thoát.