QAT-CLI

Quick Auto Testing — 面向 Vue 项目，集成 Vitest & Playwright，AI 驱动覆盖测试全流程

功能特性 · 快速开始 · 命令详解 · 配置文件 · AI 辅助 · API · 开发

QAT-CLI 是什么？

QAT-CLI（Quick Auto Testing）是一个面向 Vue 生态的全局 CLI 测试工具，它不重复造轮子，而是将业界最优秀的测试框架（Vitest、Playwright、Lighthouse）整合到统一的命令行界面中，通过交互式引导+智能项目检测+源码分析+AI 辅助，让测试从"不想写"变成"容易写"。

核心设计理念

• 零配置起步 — qat init 一条命令完成项目检测、配置生成、目录创建、自动生成测试用例
• 智能分类 — 根据文件类型自动选择测试类型：.vue → 组件测试，utils/composables → 单元测试，api/ → API 测试
• AI 增强 — 全局 AI 模型配置，自动辅助生成测试代码、分析失败原因、建议修复方案
• 源码分析驱动 — 自动扫描源码，提取导出/Props/Emits/API调用，生成个性化测试用例
• Mock 自动化 — 扫描源码中的 API 调用，自动生成 Mock 路由，无需手写
• 框架智能适配 — 自动识别 Vben / Nuxt 等 Vue 框架及 UI 组件库，生成匹配的测试模板
• 依赖隔离 — QAT-CLI 内置 Vitest 依赖，通过 Node API 直接调用（进程内运行），用户项目无需安装；Playwright/Lighthouse 通过 npx 子进程调用
• 覆盖全流程 — 从创建用例 → 运行测试 → 视觉回归 → Mock 服务 → 生成报告，一站式解决
• 可扩展 — 框架注册表 + 模板引擎 + AI Provider 注册，添加新框架只需一个注册函数

功能特性

| 命令 | 说明 | |------|------| | qat init | 项目初始化：自动检测项目、配置 AI、智能扫描源码生成测试用例 | | qat create | 交互式创建更多测试用例（源码分析 + AI 辅助） | | qat run | 运行测试（支持按类型/文件/标签/并行/监听/Dry Run） | | qat status | 查看 QAT 状态 — AI 模型信息、项目配置、连通性测试 | | qat change | 更改 AI 模型配置（全局生效，所有项目共享） | | qat setup | 一键安装测试所需的外部依赖 | | qat mock | Mock API 服务器管理（启动/停止/状态） | | qat visual | 视觉回归测试（截图比对与基线管理） | | qat report | 生成 HTML 测试报告 |

支持的测试类型

| 类型 | 运行器 | 说明 | 自动匹配规则 | |------|--------|------|-------------| | 单元测试 | Vitest | 函数/工具类/composables 测试 | utils/、helpers/、services/、composables/、hooks/ | | 组件测试 | Vitest + @vue/test-utils | Vue SFC 组件挂载与交互测试 | .vue 文件 | | E2E 测试 | Playwright | 端到端用户流程测试 | 手动指定 | | API 测试 | Vitest + Express Mock | 接口请求/响应验证 | api/ 目录下的文件 | | 视觉回归 | Playwright + pixelmatch | UI 截图差异比对 | 手动指定 | | 性能测试 | Lighthouse | Core Web Vitals 指标检测 | 手动指定 |

安装

全局安装（推荐）

npm install -g qat-cli

使用 npx（免安装）

npx qat-cli --help

前置要求

• Node.js >= 18.0.0
• 一个 Vue 项目（Vue 2 / Vue 3 / Nuxt / Vben Admin 均可）

所有测试框架依赖已全部内置，无需用户项目安装。只需 npm install -g qat-cli 即可运行所有测试类型。E2E 测试需要额外运行一次 npx playwright install 安装浏览器二进制。

支持的框架

| 框架 | 自动检测 | 模板适配 | UI 库适配 | Monorepo | |------|:--------:|:--------:|:---------:|:--------:| | Vue 3 | ✅ | ✅ | ✅ | ✅ | | Vue 2 | ✅ | ✅ | ✅ | — | | Vben Admin (5.x) | ✅ | ✅ | ✅ | ✅ | | Nuxt 3 | ✅ | ✅ | ✅ | ✅ |

添加新框架只需调用 registerFramework() — 扩展指南

支持的 UI 组件库

组件测试模板会自动注入对应的全局插件注册，无需手动配置：

| UI 库 | 自动检测 | 组件测试适配 | |-------|:--------:|:-----------:| | Ant Design Vue | ✅ | ✅ | | Element Plus | ✅ | ✅ | | Naive UI | ✅ | ✅ | | Vuetify | ✅ | ✅ | | PrimeVue | ✅ | ✅ |

快速开始

# 1. 进入项目目录（Vue / Vben / Nuxt 均可）
cd my-vue-project

# 2. 初始化（自动检测项目、配置 AI、生成测试用例）
qat init

# 3. 直接运行测试（init 已自动生成测试用例）
qat run

# 4. 如需更多测试用例
qat create

# 5. 查看 AI 模型状态
qat status

# 6. 切换 AI 模型
qat change

命令详解

qat init

交互式初始化测试项目。自动检测项目结构、配置 AI、智能扫描源码并生成测试用例。

qat init           # 交互式引导
qat init --force   # 强制覆盖已有配置

执行流程：

1. 项目检测 — 自动识别框架、Vue 版本、UI 组件库、TypeScript 等
2. AI 配置 — 首次使用引导配置（apiKey / baseUrl / model），已配置则显示当前模型
3. 连通性测试 — 同一行显示模型名称和延迟
4. 生成配置文件 — qat.config.js
5. 创建测试目录 — tests/unit、tests/component、tests/e2e 等
6. Mock 路由生成 — 自动扫描源码 API 调用
7. 智能扫描源码 + 生成测试用例 — 根据文件类型自动选择测试类型

智能测试分类：

| 文件类型 | 自动归类 | 说明 | |---------|---------|------| | *.vue | 组件测试 | Vue SFC 文件 | | composables/*.ts、hooks/*.ts、use*.ts | 单元测试 | Composables / Hooks | | utils/*.ts、helpers/*.ts、services/*.ts、lib/*.ts | 单元测试 | 工具函数 / 服务 | | api/*.ts | API 测试 | API 接口文件 |

生成内容：

• qat.config.js — 测试配置文件（AI 配置存储在全局 ~/.qat/ai.json）
• tests/ — 测试目录结构 + 自动生成的测试用例
• tests/mock/routes/auto-generated.json — 自动生成的 Mock 路由

检测能力：

| 检测项 | 说明 | |--------|------| | 框架类型 | 自动识别 Vue / Vben Admin / Nuxt（含置信度） | | Vue 版本 | 自动识别 Vue 2 / Vue 3 | | UI 组件库 | 检测 Ant Design Vue / Element Plus / Naive UI 等 | | Vite 构建 | 检测 vite 依赖或配置文件 | | TypeScript | 检测 tsconfig 或 typescript 依赖 | | Monorepo | 检测 pnpm workspace / Turborepo / Nx / Lerna | | 子项目 | 自动发现 apps/ 和 packages/ 下的子项目 | | 包管理器 | 识别 npm / yarn / pnpm / bun | | 已有测试框架 | 检测 vitest / jest / playwright / cypress | | 组件目录 | 自动发现 components/ 等目录 |

AI 配置（首次运行自动引导）：

  AI 模型配置 (首次使用需配置，之后可通过 qat change 修改)

? API Key (Ollama 本地可留空): sk-xxx
? API Base URL: https://api.deepseek.com/v1
? 模型名称: deepseek-chat
  配置已保存至 ~/.qat/ai.json

  ✓ 当前 AI 模型: deepseek-chat @ https://api.deepseek.com/v1 (sk-****1234)
✔ AI 连通正常 deepseek-chat (234ms)

已配置 AI 后再运行 qat init，直接显示当前模型信息，无需重复配置。

自动生成的目录结构：

my-vue-project/
├── qat.config.js
└── tests/
    ├── unit/
    │   ├── format-utils.test.ts        ← 自动生成
    │   └── use-auth.test.ts            ← 自动生成
    ├── component/
    │   ├── user-list.test.ts           ← 自动生成
    │   └── login-form.test.ts          ← 自动生成
    ├── e2e/
    ├── api/
    │   └── user-api.test.ts            ← 自动生成
    ├── visual/
    │   ├── baseline/
    │   └── diff/
    └── mock/
        └── routes/
            └── auto-generated.json      ← 自动生成的 Mock 路由

qat status

查看 QAT 当前状态 — AI 模型信息、项目配置、连通性测试。

qat status

输出示例：

  AI 模型状态
  ─────────────────────────────
  模型:      deepseek-chat
  API URL:   https://api.deepseek.com/v1
  API Key:   sk-****1234
  Provider:  openai
  配置文件:  ~/.qat/ai.json
✔ 连通正常 (234ms)

  项目配置
  ─────────────────────────────
  框架:       Vue
  源码目录:   src
  Vitest:     ✓ (happy-dom)
  Playwright: ✓ (chromium)
  Mock:       ✓ (port 3456)
  Visual:     ✓
  Lighthouse: ✓

qat change

更改 AI 模型配置。修改全局 ~/.qat/ai.json，所有项目共享。

qat change

交互流程：

1. 显示当前 AI 配置（模型 / API URL / API Key 脱敏）
2. 引导输入新的 apiKey / baseUrl / model（默认填充当前值）
3. 保存后自动测试连通性

输出示例：

  当前 AI 配置:
  模型:     deepseek-chat
  API URL:  https://api.deepseek.com/v1
  API Key:  sk-****1234

? API Key (Ollama 本地可留空): ****
? API Base URL: https://api.openai.com/v1
? 模型名称: gpt-4o-mini

  ✓ AI 配置已保存
    ~/.qat/ai.json
    模型: gpt-4o-mini @ https://api.openai.com/v1
✔ AI 连通正常 (gpt-4o-mini, 456ms)

qat setup

一键安装测试所需的外部依赖，根据 qat.config.js 中启用的功能自动判断。

qat setup             # 交互式选择并安装
qat setup --dry-run   # 仅预览需要安装什么，不实际执行
qat setup -f          # 强制重新安装已有依赖

依赖分组：

| 分组 | 安装的包 | 对应配置项 | |------|---------|-----------| | Playwright 浏览器 | npx playwright install | playwright.enabled |

测试框架全家桶已全部内置在 QAT-CLI 中：vitest、@vue/test-utils、happy-dom、@vitest/coverage-v8、@vitejs/plugin-vue、@playwright/test、lighthouse。用户项目无需安装任何测试框架依赖。qat setup 仅用于安装 Playwright 浏览器二进制文件（Chromium/Firefox/WebKit）。

qat create

交互式创建测试用例，支持自动发现 Vue 组件和工具文件，源码分析 + AI 辅助生成个性化测试。

qat create                           # 交互式创建
qat create -t unit component         # 指定多个类型
qat create -t unit -n my-utils       # 指定名称
qat create -t e2e --target /login    # 指定被测目标

选项：

| 选项 | 说明 | |------|------| | -t, --type <types...> | 测试类型（支持多选）：unit / component / e2e / api / visual / performance | | -n, --name <name> | 测试文件名称 | | --target <paths...> | 被测目标（支持多选，组件路径、页面路由等） |

源码分析驱动：

qat create 在生成测试前会自动分析目标源码：

| 分析能力 | 说明 | |---------|------| | 导出项提取 | 识别函数/类/const/组件等导出，生成针对性测试 | | Props 分析 | 提取 defineProps 的对象/数组/类型形式，生成 props 测试 | | Emits 分析 | 提取 defineEmits，生成事件触发测试 | | Methods/Computed | Options API 的方法和计算属性 | | 必填/可选区分 | 自动区分 required/optional props，分别生成测试 |

无源码分析数据时降级为通用模板，确保始终可用。

AI 增强模式：

启用 AI 后，会将源码分析结果 + 完整源码一并传给大模型，生成更精准的测试代码。

qat run

运行测试，支持多种筛选和执行方式。

qat run                    # 交互式选择运行
qat run -t unit            # 只运行单元测试
qat run -t unit component  # 运行多种类型
qat run -f tests/unit/a.ts # 运行指定文件
qat run -t e2e -b chromium # 指定浏览器
qat run -p                 # 并行执行多种类型
qat run -w                 # 监听模式（文件变更自动重跑）

选项：

| 选项 | 说明 | |------|------| | -t, --type <types...> | 测试类型（支持多选） | | -f, --file <file> | 指定测试文件路径 | | --tag <tag> | 按标签筛选测试用例 | | -w, --watch | 监听模式 | | -p, --parallel | 并行执行测试 | | -b, --browser <browser> | 指定浏览器：chromium / firefox / webkit |

实时测试输出：

qat run 在串行模式下直接输出 vitest 的实时测试过程，你可以看到每个测试用例的执行状态、耗时和失败原因：

  ▶ 单元测试

 ✓ tests/unit/math.test.ts (2 tests) 5ms
   ✓ should add 2ms
   ✓ should subtract 1ms

 ✗ tests/unit/string.test.ts (1 test) 3ms
   ✗ should trim 2ms
     Expected "hello " to be "hello"

 ✓ 单元测试 通过

  ─────────────────────────────────────────────────────
  测试结果汇总
  ─────────────────────────────────────────────────────
  ...

Vitest 运行策略：

| 策略 | 方式 | 说明 | |------|------|------| | 优先 | vitest/node Node API | 进程内运行，无 shell/glob 问题，结果直接获取 | | 回退 | 子进程 execFile | 当 Node API 不可用时回退，直接传文件路径（非 glob） |

Vitest 作为 QAT-CLI 的直接依赖内置，用户项目无需单独安装。

AI 失败分析：

测试失败时，如已配置 AI，自动调用大模型分析失败原因并给出修复建议：

  ✗ 单元测试 失败

  🤖 AI 分析失败原因...

    my-utils > should format date
      错误: Expected "2024-01-01" but received undefined
      → formatDate 需要传入有效 Date 对象，undefined 调用时返回了 undefined
      → 在函数开头添加参数校验: if (!date) return ''

qat mock

Mock API 服务器管理，内置 Express 服务器。

qat mock start             # 启动 Mock 服务器（默认端口 3456）
qat mock start -p 8080     # 指定端口
qat mock stop              # 停止服务器
qat mock status            # 查看运行状态

特性：

• 自动生成路由 — qat init 扫描源码 API 调用，自动生成 Mock 路由
• JSON / JS 路由配置文件
• 请求参数模板替换（{{params.id}} / {{query.key}} / {{body.field}}）
• 自定义延迟和响应头
• 404 兜底路由

qat visual

视觉回归测试，基于 Playwright 截图 + pixelmatch 像素级比对。

qat visual test                      # 执行视觉回归测试
qat visual test --threshold 0.05     # 自定义差异阈值
qat visual approve                   # 批准当前截图为新基线
qat visual clean                     # 清理所有基线快照

qat report

生成 HTML 测试报告，聚合所有测试结果。

qat report                 # 生成报告
qat report --open          # 自动打开浏览器
qat report -o my-report    # 指定输出目录

配置文件

在项目根目录创建 qat.config.js（qat init 会自动生成）：

// @ts-check
/**
 * QAT 配置文件 - Quick Auto Testing
 * 修改后无需重启，下次运行 qat 命令时自动生效
 *
 * AI 模型配置请运行: qat change
 * AI 状态查看请运行: qat status
 */
import { defineConfig } from 'qat-cli';

export default defineConfig({
  project: {
    framework: 'vue',
    vite: true,
    srcDir: 'src',
  },
  vitest: {
    enabled: true,
    coverage: true,
    globals: true,
    environment: 'happy-dom',
  },
  playwright: {
    enabled: true,
    browsers: ['chromium'],
    baseURL: 'http://localhost:5173',
    screenshot: 'only-on-failure',
  },
  visual: {
    enabled: true,
    threshold: 0.1,
    baselineDir: 'tests/visual/baseline',
    diffDir: 'tests/visual/diff',
  },
  lighthouse: {
    enabled: true,
    urls: ['http://localhost:5173'],
    runs: 3,
    thresholds: { performance: 80, accessibility: 90 },
  },
  mock: {
    enabled: true,
    port: 3456,
    routesDir: 'tests/mock/routes',
  },
  report: {
    outputDir: 'qat-report',
    open: false,
  },
});

配置项说明

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | project.framework | FrameworkType | 'vue' | 项目框架 | | project.uiLibrary | UILibrary | 'none' | UI 组件库 | | project.srcDir | string | 'src' | 源码目录 | | project.appDir | string | — | Monorepo 子项目路径 | | vitest.enabled | boolean | true | 是否启用 Vitest | | vitest.environment | string | 'happy-dom' | 测试环境 | | playwright.enabled | boolean | true | 是否启用 Playwright | | playwright.baseURL | string | 'http://localhost:5173' | 开发服务器地址 | | visual.threshold | number | 0.1 | 差异阈值（0-1） | | lighthouse.runs | number | 3 | 采样次数 | | mock.port | number | 3456 | Mock 服务端口 |

AI 配置不再存储在 qat.config.js 中，而是全局存储在 ~/.qat/ai.json，通过 qat change 修改，qat status 查看。

AI 辅助

QAT-CLI 内置 OpenAI 兼容协议的 AI Provider，全局配置，所有项目共享。

全局 AI 配置

AI 模型配置存储在 ~/.qat/ai.json，与项目无关：

{
  "provider": "openai",
  "apiKey": "sk-xxx",
  "baseUrl": "https://api.deepseek.com/v1",
  "model": "deepseek-chat"
}

管理命令：

| 命令 | 说明 | |------|------| | qat status | 查看 AI 模型信息 + 连通性测试 | | qat change | 更改 AI 模型配置（交互式） |

支持的服务商

| 服务商 | Base URL | 默认模型 | 需要 API Key | |--------|----------|---------|:------------:| | DeepSeek | https://api.deepseek.com/v1 | deepseek-chat | ✅ | | OpenAI | https://api.openai.com/v1 | gpt-4o-mini | ✅ | | Moonshot (月之暗面) | https://api.moonshot.cn/v1 | moonshot-v1-8k | ✅ | | 智谱 (GLM-4) | https://open.bigmodel.cn/api/paas/v4 | glm-4-flash | ✅ | | 通义千问 | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-turbo | ✅ | | Ollama (本地) | http://localhost:11434/v1 | qwen2.5-coder:7b | ❌ |

所有服务商统一使用 OpenAI 兼容协议，只需填写 apiKey / baseUrl / model 三个字段即可。

AI 能力

| 能力 | 触发场景 | 说明 | |------|---------|------| | 测试生成 | qat init / qat create | AI 根据源码分析结果生成精准测试代码 | | 测试审计 | qat init / qat create | 独立审计员 AI 审查测试是否贴切准确，不通过则重新生成（最多3次） | | 失败分析 | qat run | 测试失败时自动分析原因，给出修复建议 | | 修复建议 | qat run | 针对具体错误给出问题定位 + 修复方案 + 示例代码 |

双模型审计机制

QAT-CLI 在生成测试用例时采用生成者 + 审计员双模型架构，确保测试质量：

┌─────────────┐     测试代码      ┌─────────────┐
│  生成者 AI   │ ───────────────→ │  审计员 AI   │
│  (Generator) │                  │  (Reviewer)  │
└─────────────┘                  └──────┬──────┘
       ↑                                │
       │         审计反馈                │
       └────── 未通过则重新生成 ←────────┘
                                        │
                                   通过 → 写入文件

审计标准：

• 测试类型是否与源码匹配（如 .vue → 组件测试，utils → 单元测试）
• 覆盖完整性（是否覆盖核心导出/Props/Emits）
• 断言有效性（非空断言或永真断言）
• 代码可运行性（无语法错误、导入正确）

防死循环： 最多重试 3 次，3 次均未通过的测试仍会写入文件，但在最终审计报告中标注为"未通过"。

上下文隔离： 生成者和审计员使用独立的 Provider 实例，上下文互不污染。

配置方式

方式一：qat init 自动引导（推荐）

首次运行 qat init 时自动引导配置 AI，后续运行直接显示当前模型：

# 首次运行
  AI 模型配置 (首次使用需配置，之后可通过 qat change 修改)

? API Key (Ollama 本地可留空): sk-xxx
? API Base URL: https://api.deepseek.com/v1
? 模型名称: deepseek-chat

# 后续运行
  ✓ 当前 AI 模型: deepseek-chat @ https://api.deepseek.com/v1 (sk-****1234)
✔ AI 连通正常 deepseek-chat (234ms)

方式二：qat change 随时切换

qat change    # 交互式修改 AI 配置

方式三：Ollama 本地零成本使用

# 先启动 Ollama 服务
ollama serve

# 运行 qat change 配置
qat change
# Base URL: http://localhost:11434/v1
# 模型: qwen2.5-coder:7b
# API Key: (留空)

源码分析 + AI 联合增强

qat init 和 qat create 在 AI 模式下会将源码分析结果（导出项/Props/Emits/Methods/Computed）传给大模型，让 AI 生成更精准的测试代码：

源码分析结果:
导出项:
  - async fetchUsers(page, size) [function]
  - UserList [component]
Props:
  - users: Array (必填)
  - loading: Boolean (可选)
Emits:
  - select(user)

→ AI 根据这些结构化信息生成针对性测试

源码分析器

QAT-CLI 内置源码分析器，在生成测试时自动扫描目标文件，提取结构化信息。

分析能力

| 分析类型 | 支持的写法 | |---------|-----------| | 导出项 | export function、export const/let/var、export class、export default | | Props | defineProps({}) 对象形式、defineProps([]) 数组形式、defineProps<T>() 类型形式 | | Emits | defineEmits([]) 数组形式、defineEmits<T>() 类型形式 | | Methods | Options API methods: {} | | Computed | Options API computed: {} | | API 调用 | fetch()、axios.get/post()、useFetch()、$fetch()、自定义 HTTP 实例 |

编程式使用

import { analyzeFile, scanAPICalls, generateMockRoutesFromAPICalls } from 'qat-cli';

// 分析单个文件
const analysis = analyzeFile('src/components/UserList.vue');
console.log(analysis.vueAnalysis?.props);   // [{ name: 'users', type: 'Array', required: true }]
console.log(analysis.vueAnalysis?.emits);   // [{ name: 'select', params: ['user'] }]
console.log(analysis.apiCalls);             // [{ method: 'GET', url: '/api/users' }]

// 扫描整个项目的 API 调用
const apiCalls = scanAPICalls('src');

// 自动生成 Mock 路由
const mockRoutes = generateMockRoutesFromAPICalls(apiCalls);

框架扩展

QAT-CLI 采用框架注册表模式，内置了 Vue / Vben / Nuxt 三种框架的检测规则。添加新框架只需调用 registerFramework() 注册即可。

注册新框架

import { registerFramework } from 'qat-cli';

registerFramework({
  type: 'quasar',
  displayName: 'Quasar Framework',
  detect(ctx) {
    if (ctx.dependencies['quasar']) return 1.0;
    return 0;
  },
  resolve(ctx) {
    return {
      uiLibrary: 'none',
      monorepo: 'none',
      appDirs: [],
      srcDir: 'src',
      componentDirs: ['src/components'],
      pageDirs: ['src/pages'],
      componentTestSetup: {
        extraImports: [`import { Quasar } from 'quasar';`],
        globalPlugins: ['Quasar'],
        mountOptions: `{ global: { plugins: [Quasar] } }`,
      },
    };
  },
});

外部扩展

QAT-CLI 的编程式 API 可以通过外部扩展文件自动加载，无需修改源码。

单文件模式

在项目根目录创建 qat.config.ext.ts：

import { registerFramework, registerTemplate, registerAIProvider } from 'qat-cli';

registerFramework({ /* ... */ });
registerTemplate('custom-type', `...`);
registerAIProvider('my-provider', MyProvider);

多文件模式

project/
├── qat.ext/
│   ├── index.ts           # 统一入口
│   ├── framework.ts
│   └── templates.ts

文件扫描优先级

| 优先级 | 文件 | 说明 | |:------:|------|------| | 1 | qat.config.ext.ts | 单文件（最常用） | | 2 | qat.config.ext.js | JS 版本 | | 3 | qat.ext/index.ts | 目录入口 | | 4 | qat.ext/*.ts | 目录多文件 |

API

QAT-CLI 同时提供编程式 API，可以在 Node.js 中直接调用：

import {
  // 配置
  loadConfig, defineConfig, validateConfig,
  // 检测
  detectProject, discoverVueComponents, discoverUtilityFiles,
  // 源码分析
  analyzeFile, analyzeFiles, scanAPICalls, generateMockRoutesFromAPICalls,
  // 框架注册表
  registerFramework, getRegisteredFrameworks, detectFramework,
  // 运行器
  runVitest, runPlaywright, runLighthouse,
  // AI
  registerAIProvider, getAIProvider, isAIAvailable, testAIConnection,
  // 全局 AI 配置
  loadGlobalAIConfig, saveGlobalAIConfig, toAIConfig,
  // 报告
  generateHTMLReport, aggregateResults,
  // 视觉回归
  compareImages, createBaseline,
  // Mock 服务
  startMockServer, stopMockServer,
} from 'qat-cli';

// 使用全局 AI 配置
const globalAI = loadGlobalAIConfig();
if (globalAI) {
  const aiConfig = toAIConfig(globalAI);
  const result = await testAIConnection(aiConfig);
  console.log(result.ok);      // true/false
  console.log(result.message); // "连通正常 (234ms)" 或错误信息
}

// 分析源码
const analysis = analyzeFile('src/utils/format.ts');

// 扫描项目 API 调用并生成 Mock
const apiCalls = scanAPICalls('src');
const mockRoutes = generateMockRoutesFromAPICalls(apiCalls);

// 运行测试
const testResult = await runVitest({ type: 'unit', coverage: true });

架构

┌─────────────────────────────────────────────────────────────┐
│                     用户项目 (my-vue-app)                     │
│                                                              │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────┐          │
│  │  vitest   │  │ @playwright/ │  │  lighthouse    │          │
│  │(QAT内置) │  │ test (QAT内置)│  │  (QAT内置)     │          │
│  └────┬─────┘  └──────┬───────┘  └──────┬────────┘          │
│       │ Node API      │ npx 调用         │ npx 调用           │
├───────┼────────────────┼─────────────────┼───────────────────┤
│       ▼                ▼                 ▼                    │
│  ┌────────────────────────────────────────────────────┐      │
│  │           QAT-CLI 工具 (全局安装)                     │      │
│  │                                                    │      │
│  │  全局 AI 配置:                                       │      │
│  │  ~/.qat/ai.json · qat status · qat change          │      │
│  │                                                    │      │
│  │  源码分析器 + 智能分类:                                │      │
│  │  .vue → 组件测试 · utils → 单元测试 · api → API测试  │      │
│  │                                                    │      │
│  │  AI 增强:                                            │      │
│  │  OpenAI 兼容协议 · DeepSeek · Ollama · 连通性测试     │      │
│  │                                                    │      │
│  │  Mock 自动化:                                        │      │
│  │  源码 API 扫描 → 自动生成 Mock 路由                    │      │
│  │                                                    │      │
│  │  框架注册表:                                         │      │
│  │  Vue ─ Vben Admin ─ Nuxt ─ [自定义框架]              │      │
│  └────────────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────────┘

项目结构

qat/
├── bin/
│   └── qat.js                    # CLI 入口
├── src/
│   ├── cli.ts                    # 命令注册 + Logo
│   ├── index.ts                  # API 导出
│   ├── commands/                 # 命令实现
│   │   ├── init.ts               #   项目初始化（AI 配置 + 智能扫描 + 自动生成测试用例）
│   │   ├── create.ts             #   创建用例（源码分析 + AI 辅助）
│   │   ├── run.ts                #   运行测试（含 AI 失败分析）
│   │   ├── status.ts             #   查看 AI 模型状态
│   │   ├── change.ts             #   更改 AI 模型配置
│   │   ├── setup.ts              #   依赖安装
│   │   ├── mock.ts               #   Mock 服务
│   │   ├── visual.ts             #   视觉回归
│   │   └── report.ts             #   生成报告
│   ├── runners/                  # 测试运行器
│   │   ├── vitest-runner.ts
│   │   ├── playwright-runner.ts
│   │   └── lighthouse-runner.ts
│   ├── services/                 # 核心服务
│   │   ├── config.ts             #   配置管理
│   │   ├── global-config.ts      #   全局 AI 配置 (~/.qat/ai.json)
│   │   ├── test-reviewer.ts      #   生成者+审计员双模型审核流程
│   │   ├── detector.ts           #   项目检测
│   │   ├── source-analyzer.ts    #   源码分析器（导出/Props/Emits/API调用）
│   │   ├── framework-registry.ts #   框架注册表
│   │   ├── template.ts           #   模板引擎
│   │   ├── reporter.ts           #   报告生成
│   │   ├── mock-server.ts        #   Mock 服务器
│   │   └── visual.ts             #   视觉比对
│   ├── ai/                       # AI 集成
│   │   ├── provider.ts           #   Provider 管理 + 连通性测试
│   │   ├── openai-provider.ts    #   OpenAI 兼容 Provider
│   │   └── noop-provider.ts      #   默认空实现
│   ├── templates/                # 测试模板 (Handlebars)
│   │   ├── unit-test.hbs
│   │   ├── component-test.hbs
│   │   ├── e2e-test.hbs
│   │   ├── api-test.hbs
│   │   ├── visual-test.hbs
│   │   └── performance-test.hbs
│   └── types/                    # 类型定义
│       ├── index.ts
│       └── ai.ts
├── tests/                        # 测试文件
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── vitest.config.ts

开发

环境准备

git clone https://github.com/your-username/qat-cli.git
cd qat-cli

npm install
npm run dev      # 开发模式
npm run build    # 构建
npm test         # 运行测试
npm run lint     # 类型检查

技术栈

| 技术 | 用途 | |------|------| | TypeScript | 主要开发语言 | | Commander.js | CLI 框架 | | Inquirer.js | 交互式命令行（多选支持） | | Chalk | 终端彩色输出 | | Handlebars | 测试模板引擎 | | Express | Mock API 服务器 | | pixelmatch + pngjs | 视觉回归比对 | | Vitest + @vue/test-utils + happy-dom (内置) | 单元/组件/API 测试全家桶，开箱即用 | | @vitest/coverage-v8 (内置) | 测试覆盖率 | | @vitejs/plugin-vue (内置) | Vue SFC 编译支持 | | tsup | 构建打包 |

本地调试

npm run build
npm link

cd my-vue-project
qat init
qat run

# 取消链接
npm unlink -g qat-cli

常见问题

QAT-CLI 不是一个测试框架，而是测试框架的编排层。它解决的核心问题是：

1. 初始化成本高 — 自动检测项目、生成配置、自动生成测试用例
2. 工具割裂 — Vitest/Playwright/Lighthouse 统一调度
3. 测试难写 — 源码分析器 + AI 辅助生成个性化测试，而不是固定模板
4. 报告分散 — 聚合为统一的 HTML 报告
5. 失败难定位 — AI 自动分析失败原因并给出修复建议

AI 配置是全局的，存储在 ~/.qat/ai.json，所有项目共享：

• 首次配置 — 运行 qat init 时自动引导
• 修改配置 — 运行 qat change
• 查看状态 — 运行 qat status

只需填写三个字段：apiKey、baseUrl、model。支持所有 OpenAI 兼容 API（DeepSeek / OpenAI / Ollama 等）。

AI 模型配置通常是跨项目共享的 — 你不会每个项目用不同的 AI。将 AI 配置放在全局 ~/.qat/ai.json 中：

• 一个配置所有项目使用
• 切换模型只需 qat change，不用改每个项目的配置文件
• API Key 不会意外提交到 Git

会。qat init 会自动扫描源码并根据文件类型智能生成测试：

• .vue 文件 → 组件测试（component）
• composables/、hooks/、utils/、helpers/、services/ → 单元测试（unit）
• api/ → API 测试

如果已配置 AI，测试用例将由 生成者 + 审计员 双角色协作生成（使用同一个模型，通过不同系统提示词扮演不同角色）：生成者负责写测试代码，审计员负责审查是否贴切准确，不通过则带具体问题反馈重新生成（最多 3 次），最终审计结果会在报告中显示。

不需要。qat init 会自动扫描源码中的 fetch/axios/useFetch 等 API 调用，自动生成对应的 Mock 路由文件（auto-generated.json）。如需自定义，直接编辑该文件即可。

• Props: defineProps({}) 对象形式、defineProps([]) 数组形式、defineProps<T>() 类型形式
• Emits: defineEmits([]) 数组形式、defineEmits<T>() 类型形式
• 导出: export function/const/class/default 全部支持
• API 调用: fetch()、axios、useFetch()、$fetch()、自定义 HTTP 实例
• 支持 <script setup> 和 Options API

所有测试框架依赖全部内置在 QAT-CLI 全局安装中，用户项目零依赖即可运行所有测试类型：

| 内置依赖 | 用途 | |---------|------| | vitest + happy-dom + @vue/test-utils + @vitest/coverage-v8 + @vitejs/plugin-vue | 单元/组件/API 测试 | | @playwright/test | E2E/视觉回归测试 | | lighthouse | 性能测试 |

唯一需要额外安装的是 Playwright 浏览器二进制（运行 npx playwright install），因为浏览器文件太大不适合打包进 npm。

如果用户项目已安装了自己的 vitest 或有 vitest.config.* / vite.config.*，QAT-CLI 会优先使用用户项目的配置，确保与项目自身行为一致。

支持。Playwright CI 下自动启用重试和 worker 限制，Lighthouse 使用 headless 模式，测试失败时 process.exitCode = 1。

qat run -p   # 并行运行所有测试
qat report   # 生成报告

贡献

欢迎贡献代码！

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/my-feature
3. 提交更改：git commit -m 'feat: add my feature'
4. 推送分支：git push origin feature/my-feature
5. 提交 Pull Request

提交规范

使用 Conventional Commits 格式：feat: / fix: / docs: / refactor: / test: / chore:

License

MIT © 2024-present