Apifox CLI + Claude Skills：将接口自动化测试融入研发工作流

本文旨在介绍如何将 Apifox CLI 与 Claude Skills 结合，实现 「自然语言触发接口自动化测试」 的高效工作流。

在这套工作流中，你只需要在终端里对 Claude Code 说一句话，例如："用开发环境跑一下支付流程的测试"。

Claude Code 就会自动识别你的意图，定位对应的"测试场景"或"测试套件"来执行测试。测试完成后，它会对执行结果进行整理和解读。

这套流程由三个工具组成：

Apifox CLI： Apifox 的命令行工具。用于在终端中执行 CLI 命令，并生成测试报告。
Claude Code： Anthropic 推出的命令行 AI 助手。可以在终端操作文件、运行命令、执行脚本等。
Claude Skills： 也称 Agent Skills，是 Claude Code 的扩展功能。它可以定义 Claude 如何完成特定任务，相当于一份可执行的操作说明。

在这套流程中，Claude Code 负责理解自然语言指令，若"指令"匹配到本工作流中预置的 Claude Skills 后，就会自动执行 Apifox CLI 命令并分析执行结果。

这套流程能做什么

下面通过几个实际操作场景，直观了解这套工作流的使用方式：

执行单个测试

如果想执行特定的测试场景，可以直接指定。例如，在 Claude Code 输入："帮我跑一下登录功能的测试，用开发环境"，测试完成后 Claude 会分析结果并给出总结。

如果测试失败，Claude 会分析失败原因。

查看所有可用测试

如果想知道有哪些测试场景或测试套件，可以问："有哪些测试可以执行？"。Claude 就会运行相关的脚本，把所有测试列出来。

执行某个业务模块的所有测试

想执行某个业务模块的所有测试，例如想一次跑完支付相关的测试，可以说："用测试环境跑一下支付相关的所有测试"。Claude 会自动找到所有相关测试文件并依次或者并行执行。

对比不同环境的测试结果

如果需要对比不同运行环境的测试结果，可以说："用开发环境和测试环境跑一下登录功能的测试"。Claude 会在两个环境下执行测试，并帮你分析结果差异。

根据代码变更执行测试

当代码有更新时，可以让 Claude 只执行受影响的测试场景或测试套件。例如："根据最近的代码变更，在开发环境跑一下受影响的接口测试"。Claude 会根据 Git 分析变更文件，并选择对应测试执行，节省时间和资源。

其它更多场景，需要你来探索......

下面将依次介绍 Apifox CLI、Claude Code 和 Claude Skills 的安装和构建方式，以及如何将它们组合使用，最终跑通这套工作流。

准备工作

环境要求

确保电脑上装了 Node 环境，可打开终端验证：

bash 复制代码

node -v
npm -v

安装 Apifox CLI

通过 npm 安装：

bash 复制代码

npm install -g apifox-cli

apifox --version

看到版本号说明安装成功。

可以到 Apifox 的「自动化测试 -> CI/CD」中，复制一个"测试场景"或者"测试套件"的 CLI 命令到终端执行，记得添加 Access Token。

看到测试输出就说明 Apifox CLI 能正常工作了。

💡 需要将 Apifox 客户端和 Apifox CLI 更新到最新版，才能使用最新的"测试套件"功能。

安装 Claude Code

通过 npm 安装：

bash 复制代码

npm install -g @anthropic-ai/claude-code

claude --version

首次运行需要登录：

bash 复制代码

claude

按照提示完成授权，需要 Claude 账号 （可以通过某鱼或一些中转站解决账号问题） 。登录后会进入对话界面，试试问一些问题，Claude 会给出回答。

现在 Claude 还不知道怎么跑 Apifox 测试，接下来我们通过 Claude Skills 来教会它。

Claude Skills 的构建

理解 Skills 的工作原理

使用 Claude Code 时，你不需要手动指定要使用的 Skill。你只需要用一句话描述你想做的事，Claude 会自动选择合适的 Skill 来完成。

只要你输入的自然语言与某个 Skill 的描述相匹配，Claude 就会加载该 Skill，并按照其中定义的流程执行任务。

步骤 1：创建 Skill 目录

Skills 的配置文件统一放在 .claude/skills/ 目录下，每个 Skill 对应一个独立的子目录。

在这里，我们在项目根目录下，为 Apifox 自动化测试创建一个最小可用的 Skill 目录：

shell 复制代码

mkdir -p .claude/skills/apifox-tests

执行完成后，目录结构如下：

shell 复制代码

.claude/skills/apifox-tests/

后续我们会在这个目录中，逐步添加 Skill 的入口文件和执行脚本等内容。

步骤 2：创建 SKILL.md

每个 Skill 都需要一个 SKILL.md 文件，用来说明当这个 Skill 被匹配到时，Claude 应该如何一步步完成任务。

SKILL.md 以 --- 包裹的 YAML 元信息开始，其中 name 和 description 是必需字段。

description 尤其重要，它用于帮助 Claude 判断在什么场景下应该启用这个 Skill，所以这里要根据你的业务写触发条件。

在 YAML 之后的 Markdown 内容中，则用于描述这个 Skill 被启用后，Claude 具体应该怎么做，包括判断逻辑、执行步骤、引用的脚本、以及需要遵循的约束规则。

下面是一个可直接使用的 SKILL.md 示例，用于定义 Apifox 自动化测试的执行流程：

markdown 复制代码

---
name: apifox-tests
description: 执行和解读 Apifox 自动化测试。触发场景：(1) 修改代码后需要验证接口可用性 (2) git commit/push 前的接口检查 (3) 发布版本前的回归测试 (4) 用户明确要求运行 Apifox 测试，或用具体环境跑相关测试 (5) 合并到 main 分支前的自动化检查。选择合适的测试场景或者测试套件，执行测试并解释结果，但不修改测试或命令本身。
---

# Apifox Tests

执行 Apifox 自动化测试并解释结果。

## 工作流程

1. **选择测试**：

- 如果用户在对话中明确提供了：
  - 测试文件路径
  - 测试文件名
  - 或清晰可唯一匹配的测试名称
- 直接使用该测试，不再进行自动选择
- 若信息不明确，应优先通过运行 `node ./.claude/skills/apifox-tests/scripts/list-tests.js` 脚本来快速获取所有的测试文件路径及描述。
- 避免在庞大的项目目录中进行盲目的全局搜索，直接定位到该 Skill 专用的测试文件目录 `tests/`。

2. **多测试执行规则**

- 默认只执行一个测试，但需给出是否批量执行的选择
- 如果用户明确表示：
  - "跑这几个"
  - "全部跑一遍"
- 则进入 **批量执行模式**

批量执行模式下：
- 明确列出将要执行的测试列表
- **询问执行方式**：让用户选择 "按顺序执行" (更易读) 或 "并行执行" (速度快)。
  - **按顺序执行**：逐个运行测试并即时分析，适合调试。
  - **并行执行**：同时启动多个测试（使用 `&` 结尾或脚本并发），适合快速回归，但日志可能会交织。
- 请求用户确认执行方式及测试列表（是 / 否）
- 按选择的方式执行测试
- 最终汇总或依次解释每个测试的结果

3. **确认环境**：
- 支持的环境包括：
  - `dev`
  - `test`
  - `prod`
- 如用户未明确指定环境：
  - 列出上述环境名
  - 让用户确认使用哪一个

4. **执行测试**：
- 在以下信息明确后执行测试：
  - 测试文件路径
  - 环境名（dev / test / prod）
```bash
node ./.claude/skills/apifox-tests/scripts/run-cli.js <测试文件路径> <环境名>
```

5. **解释结果**：分析 Apifox CLI 输出，解释失败原因

## 失败处理

- 不修改测试文件
- 不修改执行命令
- 基于测试名称、接口语义和 CLI 输出解释失败原因

步骤 3：补充 Skill 所需的支持文件

在前面的步骤中，我们已经创建了 SKILL.md，用于定义这个 Skill 的触发条件和整体执行流程。

在此基础上，其余文件都只是对 SKILL.md 的补充，当流程中需要其它信息，比如运行环境、执行命令或测试定义时，再按需引入对应的文件即可。

最终，这个 Skill 的目录结构如下：

shell 复制代码

.claude/skills/apifox-tests/
├── SKILL.md              # Skill 入口，定义触发条件和整体流程
├── env/                  # 运行环境配置（如 dev / test / prod），用于区分不同测试环境
│   ├── dev.env           # 开发环境
│   ├── test.env          # 测试环境
│   └── prod.env          # 生产环境
├── scripts/              # 执行脚本（被 SKILL.md 调用）
│   ├── list-tests.js     # 列出 tests 目录下的所有测试
│   └── run-cli.js        # 负责组装并执行 Apifox CLI 命令
└── tests/                # 测试定义（每个文件对应一个测试场景或测试套件）
    ├── 支付流程.md        
    └── 退款流程.md

下面分别介绍这些支持文件的作用和示例。

环境配置（env）

env/ 目录用于存放不同运行环境对应的变量配置，例如 Apifox 的访问令牌 （Access Token） 和环境 ID。

将环境 ID 抽离为变量，可以让我们在不改任何命令或脚本的情况下，快速切换测试运行环境 （如开发 / 测试 / 生产）。

例如，在 env/ 目录下创建 dev.env 文件：

shell 复制代码

APIFOX_ACCESS_TOKEN=APS-你的访问令牌
APIFOX_ENV_ID=你的环境ID

如果需要支持多个环境，可以按照同样的方式创建：

test.env
prod.env
......

每个文件只需要维护对应环境的变量即可。

环境 ID 对应的是 Apifox CLI 命令中 -e 参数后面的数字，每一个运行环境 （如开发、测试、生产） 在 Apifox 中都会有一个唯一的环境 ID。

💡 env/ 目录的 .env 文件包含访问令牌，是敏感信息，不能提交到 Git。

执行脚本（scripts）

scripts/ 目录用于存放可直接执行的脚本，负责把「测试定义」转换为实际可运行的 Apifox CLI 命令，并完成环境变量注入与执行。

本文中的 Skill 选择使用 Node.js，主要基于两个考虑：

Apifox CLI 本身依赖 Node.js 直接复用同一运行环境，无需额外准备 Python 等运行时。
降低上下文负担，减少 tokens 消耗 将"命令解析、变量注入、执行逻辑"放在脚本中完成，可以避免让 Claude 在对话中反复拼装完整 CLI 命令。

如果你对脚本不熟悉，也可以选择不使用，而是在 SKILL.md 中直接让 Claude 组装并执行 CLI 命令，只是上下文成本会更高一些。

在 scripts/ 目录下创建 run-cli.js，它的核心职责是：

从指定的 Markdown 测试文件中提取 Apifox CLI 命令
根据选定的环境 （如 dev / test） 加载对应的 .env 文件
注入环境变量后执行测试

可直接使用的示例脚本如下：

javascript 复制代码

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("❌ 缺少测试 md 文件路径");
    process.exit(1);
}

// env 路径：始终相对 skills 本身
const envPath = path.join(__dirname, "..", "env", `${envName}.env`);

if (!fs.existsSync(envPath)) {
    console.error(`❌ 未找到环境配置：${envPath}`);
    process.exit(1);
}

dotenv.config({ path: envPath });

// 读取 md
const content = fs.readFileSync(mdPath, "utf-8");
const match = content.match(/```bash([\s\S]*?)```/);

if (!match) {
    console.error("❌ 未找到 bash 命令块");
    process.exit(1);
}

let command = match[1].trim();

// 变量替换
command = command
    .replaceAll("$APIFOX_ACCESS_TOKEN", process.env.APIFOX_ACCESS_TOKEN)
    .replaceAll("$APIFOX_ENV_ID", process.env.APIFOX_ENV_ID);

console.log(`▶ Running (${envName})`);
console.log(command);

// 执行
try {
    execSync(command, { stdio: "inherit" });
} catch (e) {
    // Apifox CLI 在测试失败时会返回退出码 1
    process.exit(1);
}

同样在 scripts/ 下创建 list-tests.js，用于：

递归扫描 tests/ 目录
查找所有 Markdown 测试文件
提取首行描述信息
输出当前所有可用的 Apifox 自动化测试列表

可直接使用的示例脚本如下：

javascript 复制代码

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.isDirectory()) {
            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() 
                    : "无描述";
                const displayPath = path.join("./.claude/skills/apifox-tests/tests", relPath);
                console.log(`[${displayPath}] - ${description}`);
            } catch (err) {
                console.log(`[${relPath}] - (无法读取内容)`);
            }
        }
    }
}

console.log("🔍 可用的 Apifox 自动化测试列表：");
if (fs.existsSync(testsDir)) {
    scan(testsDir);
} else {
    console.log("❌ 未找到 tests 目录");
}

测试定义（tests）

tests/ 目录用于存放测试文件，采用 Markdown 编写。

设计原则：一个 Markdown 文件对应一个 Apifox 测试场景或测试套件。你可以直接复用 Apifox 自动化测试中已有的目录结构、测试场景或测试套件名称，以及描述信息。

每个 Markdown 文件只需包含两部分内容：一段简短的测试说明，以及一条可直接执行的 Apifox CLI 命令。

Apifox CLI 命令里的 Access Token 和 -e 参数后面的环境 ID，分别用 $APIFOX_ACCESS_TOKEN 和 $APIFOX_ENV_ID 代替，并统一在 .env 文件中配置，这样既可以避免 token 泄露，也能灵活切换运行环境。一个登录鉴权-认证流程.md文件的内容示例：

markdown 复制代码

> 验证登录、刷新 token、登出等核心接口是否可用。

```bash
apifox run --access-token $APIFOX_ACCESS_TOKEN -t 5564xxx -e $APIFOX_ENV_ID -n 1 -r html,cli
```

到这一步，我们的 Skills 算是构建完了，可以参考一下结构，对比一下与你的有什么不同：

在 Claude Code 中使用

配置完成后，在终端控制台运行 claude 命令进入项目目录。Claude 会自动扫描 .claude/skills/ 目录，发现 apifox-tests Skill。

你也可以先用 /skills 命令查看已加载的 Skill。

然后，可以试着说一句自然语言指令，例如："帮我跑一下退款流程的测试，用测试环境 "。

Claude 会理解你的意图，找到对应的测试文件并执行测试。在执行过程中，你会看到 Apifox CLI 的输出；测试完成后，Claude 会对结果进行分析并给出总结。

整个流程概述起来就是，你用自然语言描述需求，Claude 理解意图并调用脚本，脚本执行 Apifox CLI 命令，Claude 分析结果并反馈给你。

总结

本文介绍了如何通过 Claude Code、Apifox CLI 和 Claude Skills 构建自动化测试工作流。核心思想是让 Claude 成为你和工具之间的桥梁。你用自然语言描述需求，Claude 理解意图后调用脚本，脚本执行具体工作，Claude 把结果整理成易读的形式反馈给你。

要让这套方案真正发挥作用，需要根据项目特点调整配置。比如测试的组织方式、环境的管理策略、结果的分析逻辑等。好在这套方案各个部分都可以定制，可以根据需要添加新功能或修改现有逻辑。

如果你的团队经常需要执行接口测试，希望让这个过程更自动化、更智能，这套方案值得一试。初期需要花时间配置和熟悉，但一旦建立起来，能显著提升工作效率。随着使用深入，你会发现更多可以优化的地方，让整个工作流越来越顺畅。