Hướng dẫn sử dụng Apidog CLI trong mã Claude

Claude Code hoạt động theo một vòng lặp: chỉnh sửa tệp, chạy lệnh terminal, đọc kết quả và 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 có người nhấp chuột, chúng sẽ nằm ngoài vòng lặp đó. Bằng cách đưa apidog run vào quy tắc dự án, Claude Code có thể chạy kịch bản API, kiểm tra mã thoát và sửa lỗi giống như khi chạy unit test.

Dùng thử Apidog ngay hôm nay

Apidog CLI là gói npm apidog-cli, cho phép chạy các kịch bản kiểm thử đã tạo trong Apidog ngay từ terminal. Hướng dẫn này tập trung vào phần tích hợp với Claude Code: cấu hình CLAUDE.md, quyền chạy lệnh và cách dùng kết quả kiểm thử trong vòng lặp sửa mã.

Trước khi bắt đầu, hãy bảo đảm CLI đã được cài đặt, đăng nhập và hoạt động:

apidog --version

Nếu chưa thiết lập, xem Cách cài đặt Apidog CLI với một agent mã hóa AI.

Đây là Claude Code nào?

Bài viết này nói về Claude Code CLI của Anthropic: agent chạy trong terminal hoặc ứng dụng desktop, có thể đọc repository, chỉnh sửa tệp và chạy lệnh shell theo cơ chế quyền hạn.

Nếu bạn chạy:

claude

và nhận được một agent tương tác có thể đề xuất thay đổi cũng như chạy lệnh, bạn đang dùng đúng công cụ.

Claude Code học quy tắc dự án từ các slash command và tệp hướng dẫn. Xem thêm các lệnh gạch chéo của Claude Code. Với Apidog CLI, tệp quan trọng là CLAUDE.md.

Bước 1: Thêm lệnh Apidog vào CLAUDE.md

Claude Code đọc CLAUDE.md khi bắt đầu phiên. Đây là cơ chế tương đương vai trò của AGENTS.md trong Codex, nhưng Claude Code đọc CLAUDE.md, không phải AGENTS.md. Theo tài liệu memory của Claude Code, bạn có thể tham chiếu một tệp AGENTS.md sẵn có bằng @AGENTS.md nếu dự án dùng tệp đó cho agent khác.

Nếu bạn đã cấu hình Apidog CLI trong Codex, quy trình tương tự, chỉ khác tên tệp.

Tạo một trong các tệp sau:

• ./CLAUDE.md tại thư mục gốc repository — khuyến nghị cho dự án.
• ./.claude/CLAUDE.md — cấu hình cấp dự án.
• ~/.claude/CLAUDE.md — cấu hình mặc định cá nhân.

Claude Code tìm CLAUDE.md từ thư mục hiện tại đi lên các thư mục cha. Vì vậy, đặt tệp tại root repository giúp mọi phiên trong dự án đều dùng chung quy tắc.

Thêm khối sau vào CLAUDE.md:

## Kiểm thử API với Apidog CLI

Dự án này có các kịch bản kiểm thử Apidog. Sau khi thay đổi API hoặc mã liên quan đến API, hãy chạy:

`apidog run -t <scenario_id> -e <env_id> -r cli`

- Mã thoát `0` nghĩa là mọi xác nhận đều thành công.
- Mã thoát khác `0` nghĩa là có lỗi; hãy đọc báo cáo, sửa lỗi và chạy lại trước khi tiếp tục.
- Máy đã được xác thực bằng `apidog login`. Không thêm cờ `--access-token` và không đặt token vào tệp này.
- Nếu một cờ không được nhận diện, chạy `apidog run --help` và dùng đúng cờ được CLI hỗ trợ.

Đừng chỉ gửi ID kịch bản trong một cuộc trò chuyện với Claude Code. Nội dung cuộc trò chuyện sẽ mất khi phiên kết thúc, còn lệnh trong CLAUDE.md sẽ được nạp trong các phiên sau và dùng chung cho cả nhóm.

Bước 2: Lấy lệnh chạy từ Apidog

Không tự đoán <scenario_id> hoặc <env_id>.

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. Dán nguyên các giá trị -t, -e và -r cli vào CLAUDE.md.

Ví dụ:

apidog run -t <scenario_id> -e <env_id> -r cli

Reporter cli in chi tiết yêu cầu, xác nhận và phần tóm tắt trực tiếp vào terminal. Đây là đầu ra Claude Code có thể đọc để quyết định sửa gì tiếp theo.

Tham khảo thêm:

• Hướng dẫn Apidog CLI hoàn chỉnh
• Tham chiếu lệnh apidog run

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

Mở Claude Code từ repository:

claude

Vì CLAUDE.md được nạp khi khởi động, Claude Code đã biết lệnh kiểm thử. Bạn có thể yêu cầu trực tiếp, ví dụ:

Hãy chạy kiểm thử API Apidog sau thay đổi này, đọc mã thoát và sửa các lỗi nếu có.

Hoặc để Claude tự tuân theo quy tắc, hãy ghi rõ trong CLAUDE.md rằng agent phải chạy kiểm thử sau các thay đổi liên quan đến API.

Cấu hình quyền chạy lệnh

Ở chế độ mặc định, Claude Code có thể yêu cầu phê duyệt trước khi chạy một lệnh shell mới. Khi thấy lời nhắc, hãy phê duyệt apidog run.

Nếu đây là lệnh đáng tin cậy và bạn muốn tránh phê duyệt lặp lại:

1. Chạy /permissions trong phiên Claude Code; hoặc
2. Thêm quy tắc cho phép vào .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(apidog run *)"
    ]
  }
}

Một kịch bản chỉ đọc chạy trên môi trường staging thường phù hợp để cho phép trước.

Claude Code cũng có cờ --dangerously-skip-permissions, nhưng cờ này bỏ qua toàn bộ lời nhắc quyền hạn. Chỉ nên dùng trong CI hoặc môi trường không giám sát, không nên dùng cho công việc hàng ngày.

Mục tiêu là thấy rõ:

• Lệnh apidog run ... đã được thực thi.
• Đầu ra kiểm thử thô.
• Phần tóm tắt.
• Mã thoát cuối cùng.

Đừng chỉ dựa vào câu “kiểm thử đã thành công” của agent.

Bước 4: Đọc báo cáo trong Claude Code

Khi chạy với -r cli, terminal sẽ hiển thị:

• Từng request.
• Từng assertion.
• Assertion thất bại.
• Giá trị kỳ vọng và giá trị thực tế.
• Mã thoát của lệnh.

Ví dụ, một assertion có thể chỉ ra:

• Mã trạng thái thực tế khác kỳ vọng.
• Trường JSON bắt buộc bị thiếu.
• Giá trị phản hồi không đúng.
• Header hoặc schema không khớp.

Claude Code có thể dùng trực tiếp đầu ra này để xác định tệp cần sửa, áp dụng thay đổi và chạy lại kịch bản.

Tạo thêm báo cáo HTML

Nếu cần mở kết quả trong trình duyệt hoặc gửi cho đồng nghiệp, thêm reporter html:

apidog run -t <scenario_id> -e <env_id> -r cli,html

Reporter html tạo báo cáo độc lập trong thư mục:

./apidog-reports

Giữ cli trong danh sách reporter để Claude Code vẫn nhận đầu ra nội tuyến.

Để dùng JUnit hoặc các định dạng khác cho CI, xem báo cáo kiểm thử Apidog CLI.

Đưa kiểm thử API vào vòng lặp sửa lỗi của Claude Code

Sau khi cấu hình, quy trình làm việc trở thành:

1. Claude Code chỉnh sửa endpoint hoặc business logic.
2. Claude Code chạy apidog run.
3. CLI trả về mã thoát và chi tiết assertion.
4. Nếu mã thoát là 0, agent tiếp tục.
5. Nếu mã thoát khác 0, agent đọc lỗi, sửa mã và chạy lại.

Ví dụ, Claude Code thay đổi handler tạo phản hồi thanh toán. Thay vì kết luận thay đổi đã xong, agent chạy kịch bản Apidog trên staging. Nếu kiểm thử báo thiếu trường phản hồi hoặc sai status code, agent có dữ liệu cụ thể để sửa trước khi bạn triển khai.

Đây là mô hình ủy quyền rồi xác minh:

• Bạn xây dựng và duy trì kịch bản trực quan trong Apidog.
• Claude Code thực thi lệnh đã được cho phép.
• Mã thoát và báo cáo là nguồn xác thực kết quả.

Xem thêm:

• Cách sử dụng agent AI cho kiểm thử API
• Bộ công cụ kiểm thử AI của Apidog

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

Agent có thể tóm tắt sai hoặc nói rằng một tác vụ đã hoàn thành dù lệnh chưa chạy. Kiểm tra theo ba bước sau.

1. Kiểm tra lệnh và đầu ra thô

Tìm trong lịch sử phiên Claude Code:

apidog run ...

Phải có đầu ra ngay sau lệnh đó. Nếu Claude nói đã chạy kiểm thử nhưng không có lệnh thực thi, hãy yêu cầu:

Chạy lại lệnh Apidog từ CLAUDE.md và hiển thị toàn bộ đầu ra thô.

2. Kiểm tra mã thoát

Hỏi trực tiếp:

Mã thoát của lệnh apidog run là gì?

Quy tắc cần nhớ:

0      = mọi assertion đều thành công
khác 0 = có ít nhất một lỗi

Nếu phần tóm tắt của Claude nói “đã 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

Lỗi như “không tìm thấy kịch bản” thường cho thấy agent đã đoán sai ID.

So sánh các giá trị sau:

• -t <scenario_id> trong lệnh.
• -e <env_id> trong lệnh.
• Lệnh trong CLAUDE.md.
• Lệnh được Apidog tạo trong tab CI/CD.

Các ID trong CLAUDE.md nên là nguồn sự thật của dự án.

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

apidog run trong CLAUDE.md đã đáp ứng phần lớn nhu cầu kiểm thử. Nếu muốn Claude Code đọc đặc tả API trong lúc viết mã, hãy kết nối máy chủ MCP.

Claude Code hỗ trợ Model Context Protocol (MCP). Bạn có thể thêm máy chủ bằng claude mcp add ..., hoặc commit tệp .mcp.json tại root dự án và dùng scope project để chia sẻ cấu hình cho cả nhóm.

Máy chủ Apidog MCP cung cấp đặc tả API qua MCP, giúp Claude Code đọc schema khi tạo hoặc sửa mã.

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

• Apidog CLI: chạy kịch bản kiểm thử.
• Apidog MCP: cung cấp đặc tả API cho agent trong lúc mã hóa.

Khắc phục lỗi thường gặp

Claude Code bỏ qua CLAUDE.md

Kiểm tra:

• Tên tệp phải đúng là CLAUDE.md.
• Tệp nằm ở root repository, .claude/CLAUDE.md hoặc một thư mục cha của thư mục hiện tại.
• Bạn đã khởi động Claude Code từ đúng repository.

Chạy lệnh sau trong Claude Code để xem các tệp hướng dẫn đã được nạp:

/memory

Nếu CLAUDE.md không xuất hiện, Claude Code không nhìn thấy tệp. Khởi động lại phiên để buộc đọc lại cấu hình.

Claude Code thêm --access-token

Không đặt token thật trong CLAUDE.md. Nếu máy đã xác thực bằng:

apidog login

thì khối hướng dẫn nên cấm rõ việc dùng --access-token.

Xem xác thực Apidog CLI để biết quy trình xác thực một lần trên máy.

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

Lỗi unknown option nghĩa là agent đã đoán một cờ không được phiên bản CLI hiện tại hỗ trợ.

Yêu cầu agent chạy:

apidog run --help

Sau đó chỉ dùng các cờ được liệt kê trong đầu ra của phiên bản đã cài đặt.

Claude Code báo thành công dù kiểm thử thất bại

Đây là lỗi nghiêm trọng nhất. Khi phần diễn giải của agent và mã thoát không khớp, mã thoát là kết quả đáng tin cậy.

Vì vậy, luôn giữ quy tắc này trong CLAUDE.md:

Mã thoát khác 0 nghĩa là kiểm thử thất bại. Đọc báo cáo, sửa lỗi và chạy lại trước khi tiếp tục.

Từ agent hằng ngày đến vòng lặp đã được kiểm thử

Quy trình thiết lập gồm bốn phần:

1. Cài apidog-cli.
2. Đăng nhập bằng apidog login.
3. Sao chép lệnh CI/CD từ Apidog vào CLAUDE.md.
4. Yêu cầu Claude Code chạy lệnh sau các thay đổi liên quan đến API.

Sau đó, Claude Code có thể đưa API test vào cùng vòng lặp chỉnh sửa–kiểm thử–sửa lỗi mà nó dùng cho unit test. Endpoint hỏng sẽ được phát hiện khi agent vẫn đang làm việc trên thay đổi, thay vì chỉ sau khi triển khai.

Bạn vẫn tạo kịch bản trực quan trong Apidog, còn Claude Code chạy chúng từ terminal khi cần. Tải xuống Apidog, tạo một kịch bản, thêm lệnh apidog run vào CLAUDE.md và kiểm tra nó trong thay đổi API tiếp theo.

Khi cần chạy cùng lệnh trong pipeline không có Claude Code, xem Apidog CLI trong GitHub Actions để cấu hình secrets, reporter và kiểm soát mã thoát.