Bài viết này giới thiệu cách kết hợp Apidog CLI với Claude Skills để xây dựng một quy trình làm việc hiệu quả cho kiểm thử tự động API dựa trên ngôn ngữ tự nhiên.
Trong quy trình làm việc này, bạn chỉ cần nói một câu duy nhất cho Claude Code trong terminal của mình, ví dụ:
"Chạy thử nghiệm luồng đặt hàng người dùng trong môi trường dev."
Claude Code sẽ tự động hiểu ý định của bạn, định vị kịch bản kiểm thử hoặc bộ kiểm thử tương ứng, thực thi các bài kiểm thử, sau đó tóm tắt và giải thích kết quả cho bạn.
Tổng quan công cụ
Quy trình làm việc này bao gồm ba công cụ:
1. Apidog CLI
Giao diện dòng lệnh do Apidog cung cấp. Nó được sử dụng để thực hiện các bài kiểm thử tự động API từ terminal và tạo báo cáo kiểm thử.
2. Claude Code
Một trợ lý AI dòng lệnh do Anthropic phát hành. Nó có thể thao tác với các tệp, chạy lệnh, thực thi tập lệnh và tương tác với môi trường phát triển cục bộ của bạn.
3. Claude Skills
Còn được gọi là Agent Skills, một cơ chế mở rộng của Claude Code. Một Skill định nghĩa cách Claude nên hoàn thành một tác vụ cụ thể, về cơ bản hoạt động như một tập hợp các hướng dẫn vận hành có thể thực thi.
Trong quy trình làm việc này, Claude Code chịu trách nhiệm hiểu các hướng dẫn bằng ngôn ngữ tự nhiên. Khi yêu cầu của người dùng khớp với một Claude Skill được định nghĩa trước, Claude sẽ tự động thực thi các lệnh Apidog CLI tương ứng và phân tích kết quả.
Quy trình làm việc này có thể làm gì
Dưới đây là một số tình huống thực tế để minh họa cách quy trình làm việc này có thể được sử dụng trong thực tế.
Chạy một bài kiểm thử đơn lẻ
Nếu bạn muốn chạy một kịch bản kiểm thử cụ thể, bạn có thể nêu tên rõ ràng. Ví dụ:
"Chạy các bài kiểm thử đăng nhập trong môi trường dev."
Sau khi kiểm thử hoàn tất, Claude phân tích kết quả và cung cấp một bản tóm tắt.
Liệt kê tất cả các bài kiểm thử có sẵn
Để xem các kịch bản kiểm thử hoặc bộ kiểm thử nào có sẵn, bạn có thể nói:
"Hiển thị cho tôi các bài kiểm thử có sẵn."
Claude sẽ thực thi tập lệnh liên quan và liệt kê tất cả các bài kiểm thử.
Chạy tất cả các bài kiểm thử cho một mô-đun nghiệp vụ
Nếu bạn muốn thực hiện tất cả các bài kiểm thử cho một lĩnh vực nghiệp vụ cụ thể—chẳng hạn như các bài kiểm thử liên quan đến thanh toán—bạn có thể nói:
"Chạy tất cả các bài kiểm thử thanh toán trong môi trường test."
Claude sẽ tự động định vị tất cả các tệp kiểm thử liên quan và thực thi chúng theo trình tự hoặc song song.
So sánh kết quả kiểm thử giữa các môi trường
Để so sánh kết quả giữa các môi trường, bạn có thể nói:
"Chạy các bài kiểm thử đăng nhập trong môi trường dev và test."
Claude sẽ thực thi các bài kiểm thử trong cả hai môi trường và phân tích sự khác biệt trong kết quả.
Chạy các bài kiểm thử dựa trên thay đổi mã
Sau khi có thay đổi mã, bạn có thể yêu cầu Claude chỉ chạy các bài kiểm thử bị ảnh hưởng:
"Dựa trên các thay đổi mã gần đây, hãy chạy các bài kiểm thử API bị ảnh hưởng trong môi trường dev."
Claude sẽ phân tích các thay đổi của Git, xác định các kịch bản hoặc bộ kiểm thử bị ảnh hưởng, và chỉ thực thi các bài kiểm thử đó—giúp tiết kiệm thời gian và tài nguyên.
Nhiều kịch bản khác đang chờ bạn khám phá.
Tiếp theo, chúng ta sẽ xem xét cách cài đặt và cấu hình Apidog CLI, Claude Code, và Claude Skills, cũng như cách kết hợp chúng thành một quy trình làm việc hoàn chỉnh.
Chuẩn bị
Yêu cầu môi trường
Đảm bảo Node.js được cài đặt trên máy của bạn. Xác minh nó trong terminal của bạn:
node -v
npm -vCài đặt Apidog CLI (Cài đặt qua npm):
npm install -g apidog-cli
Xác minh việc cài đặt:
apidog --versionNếu một số phiên bản được hiển thị, việc cài đặt đã thành công.
Bạn có thể sao chép một lệnh CLI cho một kịch bản kiểm thử hoặc bộ kiểm thử từ Apidog → Tests → CI/CD, thêm Access Token của bạn, và chạy nó trong terminal.
Nếu đầu ra kiểm thử xuất hiện, Apidog CLI đang hoạt động chính xác.
Cài đặt Claude Code
Cài đặt qua npm:
npm install -g @anthropic-ai/claude-codeXác minh:
claude --versionKhi chạy lần đầu, bạn cần đăng nhập:
claude
Làm theo các bước ủy quyền. Cần có tài khoản Claude. Sau khi đăng nhập, bạn sẽ vào giao diện tương tác và có thể hỏi các câu hỏi cơ bản.
Tại thời điểm này, Claude vẫn chưa biết cách chạy các bài kiểm thử Apidog. Tiếp theo, chúng ta sẽ dạy nó sử dụng Claude Skills.
Xây dựng Claude Skills
Hiểu cách các Skill hoạt động
Khi sử dụng Claude Code, bạn không tự chọn Skill. Bạn chỉ cần mô tả những gì bạn muốn làm bằng ngôn ngữ tự nhiên.
Nếu yêu cầu của bạn khớp với mô tả của một Skill, Claude sẽ tự động tải Skill đó và thực thi quy trình làm việc được định nghĩa.
Bước 1: Tạo thư mục Skill
Tất cả các cấu hình Skill nằm trong thư mục .claude/skills/. Mỗi Skill có thư mục con riêng.
Tạo một thư mục Skill tối thiểu cho kiểm thử tự động Apidog trong thư mục gốc của dự án:
mkdir -p .claude/skills/apidog-tests
Cấu trúc kết quả:
.claude/skills/apidog-tests/Chúng ta sẽ dần thêm các tệp đầu vào và tập lệnh vào đây.
Bước 2: Tạo tệp SKILL.md
Mỗi Skill yêu cầu một tệp SKILL.md định nghĩa cách Claude nên thực hiện tác vụ một khi Skill được kích hoạt.
Tệp bắt đầu bằng siêu dữ liệu YAML được bao quanh bởi ---. Các trường name và description là bắt buộc.
Trường description đặc biệt quan trọng—nó xác định khi nào Claude nên kích hoạt Skill này.
Bên dưới khối YAML, nội dung Markdown định nghĩa logic thực thi, quy tắc quyết định, tập lệnh để gọi và các ràng buộc.
Ví dụ SKILL.md cho kiểm thử tự động Apidog
---
name: apidog-tests
description: Thực thi và giải thích các bài kiểm thử API tự động của Apidog thông qua Apidog CLI. Kích hoạt Skill này bất cứ khi nào người dùng yêu cầu rõ ràng chạy các bài kiểm thử, trường hợp kiểm thử, kịch bản kiểm thử hoặc bộ kiểm thử, bao gồm các yêu cầu thực thi kiểm thử trong một môi trường cụ thể như dev, test hoặc prod, để xác minh hành vi API sau khi thay đổi mã, để thực hiện kiểm thử hồi quy hoặc tiền phát hành, hoặc để chạy kiểm tra API trước khi git commit, push hoặc merge. Ngay cả khi người dùng không đề cập rõ ràng "Apidog" hoặc "API", hãy giả định các yêu cầu này đề cập đến các bài kiểm thử tự động của Apidog khi việc thực thi kiểm thử được ngụ ý. Skill nên chọn kịch bản kiểm thử hoặc bộ kiểm thử phù hợp, thực thi các bài kiểm thử và giải thích kết quả mà không sửa đổi các định nghĩa hoặc lệnh kiểm thử.
---
# Kiểm thử Apidog
Thực thi các bài kiểm thử tự động của Apidog và giải thích kết quả.
## Quy trình làm việc
1. **Chọn bài kiểm thử**:
- Nếu người dùng cung cấp rõ ràng:
- Đường dẫn tệp kiểm thử
- Tên tệp kiểm thử
- Hoặc một tên kiểm thử rõ ràng, duy nhất
- Sử dụng bài kiểm thử đó trực tiếp mà không cần lựa chọn tự động.
- Nếu thông tin không rõ ràng, ưu tiên chạy tập lệnh `node ./.claude/skills/apidog-tests/scripts/list-tests.js` để nhanh chóng lấy tất cả các đường dẫn tệp kiểm thử và mô tả.
- Tránh tìm kiếm toàn cục mù quáng trong các thư mục dự án lớn; thay vào đó, hãy định vị thư mục tệp kiểm thử `./.claude/skills/apidog-tests/tests/` dành riêng cho skill này.
2. **Quy tắc thực thi nhiều bài kiểm thử**
- Theo mặc định, chỉ thực thi một bài kiểm thử, nhưng cung cấp tùy chọn thực thi hàng loạt.
- Nếu người dùng nêu rõ:
- "Chạy vài bài này"
- "Chạy tất cả chúng"
- Chuyển sang **Chế độ thực thi hàng loạt**.
Trong Chế độ thực thi hàng loạt:
- Liệt kê rõ ràng các bài kiểm thử sẽ được thực thi.
- **Hỏi phương pháp thực thi**: Để người dùng chọn giữa "Thực thi tuần tự" (dễ đọc hơn) hoặc "Thực thi song song" (nhanh hơn).
- **Thực thi tuần tự**: Chạy từng bài kiểm thử một và phân tích ngay lập tức, phù hợp để gỡ lỗi.
- **Thực thi song song**: Bắt đầu nhiều bài kiểm thử đồng thời (sử dụng `&` hoặc các tập lệnh đồng thời), phù hợp để hồi quy nhanh, mặc dù nhật ký có thể xen kẽ.
- Yêu cầu người dùng xác nhận phương pháp thực thi và danh sách kiểm thử (Có / Không).
- Thực thi các bài kiểm thử theo phương pháp đã chọn.
- Cuối cùng, tóm tắt hoặc giải thích riêng kết quả của từng bài kiểm thử.
3. **Xác nhận môi trường**:
- Các môi trường được hỗ trợ bao gồm:
- `dev`
- `test`
- `prod`
- Nếu người dùng chưa chỉ định môi trường:
- Liệt kê tên các môi trường trên.
- Yêu cầu người dùng xác nhận môi trường nào sẽ sử dụng.
4. **Thực thi bài kiểm thử**:
- Thực thi bài kiểm thử khi các thông tin sau đã rõ ràng:
- Đường dẫn tệp kiểm thử
- Tên môi trường (dev / test / prod)
```bash
node ./.claude/skills/apidog-tests/scripts/run-cli.js <test_file_path> <env_name>
```
5. **Giải thích kết quả**: Phân tích đầu ra của Apidog CLI và giải thích nguyên nhân thất bại.
## Xử lý lỗi
- Không sửa đổi các tệp kiểm thử.
- Không sửa đổi các lệnh thực thi.
- Giải thích lý do thất bại dựa trên tên kiểm thử, ngữ nghĩa API và đầu ra CLI.
Bước 3: Các tệp hỗ trợ
Trong các bước trước, chúng ta đã tạo tệp SKILL.md, tệp này định nghĩa các điều kiện kích hoạt và quy trình làm việc tổng thể cho Skill này.
Dựa trên nền tảng này, tất cả các tệp còn lại chỉ đóng vai trò là thành phần hỗ trợ cho SKILL.md. Các tệp bổ sung được giới thiệu theo yêu cầu, chỉ khi quy trình làm việc yêu cầu thông tin bổ sung—chẳng hạn như môi trường thời gian chạy, lệnh thực thi hoặc định nghĩa kiểm thử.
Cấu trúc thư mục cuối cùng:
.claude/skills/apidog-tests/
├── SKILL.md
├── env/
│ ├── dev.env
│ ├── test.env
│ └── prod.env
├── scripts/
│ ├── list-tests.js
│ └── run-cli.js
└── tests/
├── payment-flow.md
└── refund-flow.md
Dưới đây, chúng ta sẽ xem xét từng tệp hỗ trợ, giải thích mục đích của nó và cung cấp các ví dụ.
Cấu hình môi trường (env)
Thư mục env/ được sử dụng để lưu trữ các cấu hình biến môi trường, chẳng hạn như Apidog access token và environment ID.
Bằng cách trích xuất ID môi trường thành một biến, chúng ta có thể nhanh chóng chuyển đổi môi trường thực thi kiểm thử (ví dụ: phát triển, kiểm thử, sản xuất) mà không cần sửa đổi bất kỳ lệnh hoặc tập lệnh nào.
Ví dụ, tạo một tệp dev.env trong thư mục env/:
APIDOG_ACCESS_TOKEN=APS-your-access-token
APIDOG_ENV_ID=your-environment-idNếu cần nhiều môi trường, bạn có thể tạo các tệp bổ sung theo cùng một cách:
test.envprod.env- …
Mỗi tệp chỉ cần duy trì các biến cho môi trường tương ứng của nó.
ID môi trường tương ứng với giá trị số được truyền cho tham số -e trong lệnh Apidog CLI. Mỗi môi trường thời gian chạy (như phát triển, kiểm thử hoặc sản xuất) đều có một ID môi trường duy nhất trong Apidog.
.env trong thư mục env/ chứa access token, là thông tin nhạy cảm và không được commit vào Git.Tập lệnh thực thi (scripts)
Thư mục scripts/ chứa các tập lệnh có thể thực thi chịu trách nhiệm chuyển đổi định nghĩa kiểm thử thành các lệnh Apidog CLI thực tế có thể chạy được, chèn biến môi trường và thực thi các bài kiểm thử.
Trong Skill này, Node.js được chọn vì hai lý do chính:
- Bản thân Apidog CLI phụ thuộc vào Node.js Việc tái sử dụng cùng một môi trường runtime giúp tránh phải cài đặt thêm các môi trường runtime khác như Python.
- Giảm chi phí ngữ cảnh và tiêu thụ token Bằng cách xử lý phân tích cú pháp lệnh, chèn biến và logic thực thi bên trong các tập lệnh, Claude không cần phải lặp lại việc xây dựng các lệnh CLI đầy đủ trong suốt cuộc hội thoại, điều này giúp giảm đáng kể việc sử dụng ngữ cảnh.
Nếu bạn không quen với việc viết tập lệnh, bạn có thể chọn không sử dụng tập lệnh nào cả. Thay vào đó, bạn có thể để Claude tự lắp ráp và thực thi các lệnh CLI trực tiếp trong SKILL.md.
Tuy nhiên, cách tiếp cận này đi kèm với chi phí ngữ cảnh và token cao hơn.
Tạo tệp run-cli.js trong thư mục scripts/. Các trách nhiệm cốt lõi của nó là:
- Trích xuất lệnh Apidog CLI từ một tệp kiểm thử Markdown được chỉ định
- Tải tệp
.envtương ứng dựa trên môi trường được chọn (ví dụ:dev/test) - Chèn biến môi trường và thực thi bài kiểm thử
Một tập lệnh ví dụ sẵn sàng sử dụng được hiển thị dưới đây:
import fs from "fs";
import path from "path";
import { execSync } from "child_process";
import dotenv from "dotenv";
import { fileURLToPath } from "url";
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
// args
const mdPath = process.argv[2];
const envName = process.argv[3] || "local";
if (!mdPath) {
console.error("❌ Missing test .md file path");
process.exit(1);
}
// env path: always relative to the skill folder
const envPath = path.join(__dirname, "..", "env", `${envName}.env`);
if (!fs.existsSync(envPath)) {
console.error(`❌ Environment configuration not found: ${envPath}`);
process.exit(1);
}
dotenv.config({ path: envPath });
// Read markdown file
const content = fs.readFileSync(mdPath, "utf-8");
const match = content.match(/```bash([\s\S]*?)```/);
if (!match) {
console.error("❌ Bash command block not found");
process.exit(1);
}
let command = match[1].trim();
// Variable replacement
command = command
.replaceAll("$APIDOG_ACCESS_TOKEN", process.env.APIDOG_ACCESS_TOKEN)
.replaceAll("$APIDOG_ENV_ID", process.env.APIDOG_ENV_ID);
console.log(`▶ Running (${envName})`);
console.log(command);
// Execute
try {
execSync(command, { stdio: "inherit" });
} catch (e) {
// Apidog CLI returns exit code 1 when tests fail
process.exit(1);
}
Cũng tạo tệp list-tests.js trong thư mục scripts/. Nó được sử dụng để:
- Quét đệ quy thư mục
tests/ - Định vị tất cả các tệp kiểm thử Markdown
- Trích xuất mô tả từ dòng đầu tiên
- Xuất ra danh sách tất cả các bài kiểm thử tự động Apidog có sẵn
Một tập lệnh ví dụ sẵn sàng sử dụng được hiển thị dưới đây:
import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const testsDir = path.join(__dirname, "..", "tests");
function scan(dir, relativePath = "") {
const items = fs.readdirSync(dir, { withFileTypes: true });
for (const item of items) {
const fullPath = path.join(dir, item.name);
const relPath = path.join(relativePath, item.name);
if (item.isfolder()) {
scan(fullPath, relPath);
} else if (item.name.endsWith(".md")) {
try {
const content = fs.readFileSync(fullPath, "utf-8");
const firstLine = content.split("\n")[0].trim();
const description = firstLine.startsWith(">")
? firstLine.replace(/^>\s*/, "").trim()
: "No description";
const displayPath = path.join(
"./.claude/skills/apidog-tests/tests",
relPath
);
console.log(`[${displayPath}] - ${description}`);
} catch (err) {
console.log(`[${relPath}] - (Unable to read file)`);
}
}
}
}
console.log("🔍 Các bài kiểm thử tự động Apidog có sẵn:");
if (fs.existsSync(testsDir)) {
scan(testsDir);
} else {
console.log("❌ Không tìm thấy thư mục tests");
}Định nghĩa kiểm thử (tests)
Thư mục tests/ lưu trữ các định nghĩa kiểm thử được viết bằng Markdown.
Nguyên tắc thiết kế: Mỗi tệp Markdown tương ứng với một kịch bản kiểm thử hoặc bộ kiểm thử Apidog. Bạn có thể trực tiếp tái sử dụng cấu trúc thư mục hiện có, tên kịch bản kiểm thử, tên bộ kiểm thử và mô tả từ kiểm thử tự động Apidog.
Mỗi tệp Markdown chỉ cần chứa hai phần:
- Một mô tả kiểm thử ngắn gọn
- Một lệnh Apidog CLI duy nhất có thể được thực thi trực tiếp
Trong lệnh Apidog CLI:
- Access token được thay thế bằng
$APIDOG_ACCESS_TOKEN - ID môi trường được truyền cho
-eđược thay thế bằng$APIDOG_ENV_ID
Cả hai biến này đều được cấu hình tập trung trong các tệp .env. Cách tiếp cận này ngăn chặn rò rỉ token và cho phép chuyển đổi môi trường một cách linh hoạt.
Ví dụ: login-auth-flow.md
> Xác minh các API cốt lõi như đăng nhập, làm mới token và đăng xuất.
```bash
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564xxx -e $APIDOG_ENV_ID -n 1 -r html,cli
```
Tại thời điểm này, Skill đã được xây dựng hoàn chỉnh. Bạn có thể xem lại cấu trúc thư mục và so sánh nó với việc triển khai của riêng bạn để xác định bất kỳ sự khác biệt nào.
Sử dụng quy trình làm việc trong Claude Code
Chạy claude trong thư mục dự án. Claude tự động quét .claude/skills/ và tải Skill apidog-tests.
Bạn có thể liệt kê các Skill đã tải bằng cách sử dụng /skills.
Sau đó, hãy thử một lệnh bằng ngôn ngữ tự nhiên:
"Chạy các bài kiểm thử đăng nhập trong môi trường dev."
Claude sẽ định vị bài kiểm thử, thực thi nó thông qua Apidog CLI, phân tích đầu ra và tóm tắt kết quả.
Tóm tắt
Bài viết này đã minh họa cách xây dựng một quy trình kiểm thử API tự động sử dụng Claude Code, Apidog CLI, và Claude Skills.
Ý tưởng cốt lõi là biến Claude thành cầu nối giữa con người và công cụ:
- Bạn mô tả ý định bằng ngôn ngữ tự nhiên
- Claude hiểu và gọi các tập lệnh
- Các tập lệnh thực thi Apidog CLI
- Claude phân tích và trình bày kết quả theo cách dễ đọc đối với con người
Để quy trình làm việc này thực sự hiệu quả, bạn nên điều chỉnh nó cho phù hợp với dự án của mình—tổ chức kiểm thử, chiến lược môi trường và logic phân tích kết quả đều có thể được tùy chỉnh.
Nếu nhóm của bạn thường xuyên chạy kiểm thử API và muốn có trải nghiệm tự động và thông minh hơn, cách tiếp cận này rất đáng để thử. Nó đòi hỏi một số thiết lập ban đầu, nhưng một khi đã thiết lập, nó có thể cải thiện đáng kể hiệu quả—và tiếp tục tốt hơn khi bạn tinh chỉnh nó.