@be-link/smart-test 1.0.1-beta.0 → 1.0.1-beta.2

package/README.md

@@ -6,17 +6,36 @@
 
 ## ✨ 特性
 
-- 🤖 **AI 视觉检查**：基于通义千问等视觉模型，智能检查页面是否符合预期
-- 🎯 **零侵入设计**：与 Playwright 无缝集成，无需修改现有测试代码
-- 🔧 **灵活配置**：支持全局配置和单次调用配置
-- 📸 **自动截图**：自动保存测试截图，方便排查问题
-- 🚫 **优雅降级**：无 API Key 时自动跳过，不影响其他测试
-- 📦 **TypeScript**：完整的类型定义支持
+### 🤖 AI 视觉检查
+
+- 基于通义千问等视觉模型，智能检查页面是否符合预期
+- 支持自然语言描述测试预期
+- 自动识别页面问题并给出详细反馈
+
+### 🎯 零代码测试生成（开发中）
+
+- **CLI 工具**：一条命令自动生成测试代码
+- **录制模式**：访问页面自动录制接口和交互
+- **代码分析**：扫描项目代码自动生成 Mock 数据
+- **AI 生成**：基于自然语言描述生成完整测试
+
+### 🔧 灵活易用
+
+- 与 Playwright 无缝集成，零侵入设计
+- 支持全局配置和单次调用配置
+- 优雅降级：无 API Key 时自动跳过
+- 完整的 TypeScript 类型支持
+
+### 📸 自动化
+
+- 自动截图并保存
+- 自动生成 Mock 数据
+- 自动生成测试用例
 
 ## 📦 安装
 
 ```bash
-# 使用 pnpm
+# 使用 pnpm（推荐）
 pnpm add -D @be-link/smart-test
 
 # 使用 npm
@@ -28,7 +47,56 @@ yarn add -D @be-link/smart-test
 
 ## 🚀 快速开始
 
-### 1. 配置 API Key
+### 方式一：使用 CLI 工具（推荐）⭐
+
+#### 1. 初始化配置
+
+```bash
+npx smart-test init
+```
+
+交互式配置向导会引导你完成设置：
+
+```
+━━━ 初始化 Smart Test 配置 ━━━
+
+? 请输入 AI API Key: sk-xxxxx
+? 选择 AI 模型: 通义千问 (qwen3-vl-plus)
+? 测试文件目录: ./tests/e2e
+? Helpers 目录: ./tests/helpers
+? Playwright Base URL: http://localhost:8080
+? 文件命名风格: kebab-case
+
+✓ 配置文件已创建: .smarttestrc.json
+```
+
+#### 2. 生成测试代码（开发中）
+
+```bash
+# 录制模式 - 访问页面自动录制
+npx smart-test record --url http://localhost:8080/coupon
+
+# 代码分析模式 - 扫描页面代码
+npx smart-test generate --page src/pages/coupon/index.tsx
+
+# 描述生成模式 - 基于自然语言
+npx smart-test generate --desc "优惠券列表页，有可用券和已用券两个 tab"
+
+# 交互式模式 - 引导式生成
+npx smart-test generate --interactive
+```
+
+#### 3. 运行测试
+
+```bash
+npx playwright test
+```
+
+---
+
+### 方式二：手动编程
+
+#### 1. 配置 API Key
 
 在项目根目录创建 `.env` 文件：
 
@@ -36,7 +104,7 @@ yarn add -D @be-link/smart-test
 AI_API_KEY=sk-your-api-key-here
 ```
 
-### 2. 初始化配置
+#### 2. 初始化配置
 
 在 `playwright.config.ts` 中配置：
 
@@ -55,7 +123,7 @@ export default defineConfig({
 });
 ```
 
-### 3. 在测试中使用
+#### 3. 在测试中使用
 
 ```typescript
 import { test, expect } from '@playwright/test';
@@ -78,7 +146,95 @@ test.describe('优惠券页面', () => {
 });
 ```
 
-## 📖 API 文档
+## 📖 CLI 命令参考
+
+### `smart-test init`
+
+初始化配置文件，交互式设置 AI API Key、模型、输出目录等。
+
+```bash
+smart-test init
+```
+
+### `smart-test generate` (开发中)
+
+生成测试代码。
+
+```bash
+# 基础用法
+smart-test generate
+
+# 指定页面（代码分析模式）
+smart-test generate --page <path>
+
+# 指定 URL（录制模式）
+smart-test generate --url <url>
+
+# 基于描述（自然语言模式）
+smart-test generate --desc <description>
+
+# 交互式模式
+smart-test generate --interactive
+
+# 指定输出目录
+smart-test generate --page <path> --output tests/custom
+
+# 预览模式（不写入文件）
+smart-test generate --page <path> --dry-run
+```
+
+**选项：**
+
+| 选项                   | 简写 | 说明                         |
+| ---------------------- | ---- | ---------------------------- |
+| `--page <path>`        | `-p` | 页面文件路径（代码分析模式） |
+| `--url <url>`          | `-u` | 页面 URL（录制模式）         |
+| `--desc <description>` | `-d` | 页面描述（自然语言模式）     |
+| `--output <dir>`       | `-o` | 输出目录                     |
+| `--interactive`        | `-i` | 交互式模式                   |
+| `--dry-run`            |      | 预览模式，不写入文件         |
+
+### `smart-test record` (开发中)
+
+录制模式的快捷命令（`generate --url` 的别名）。
+
+```bash
+# 基础录制
+smart-test record --url http://localhost:8080/coupon
+
+# 手动操作模式
+smart-test record --url http://localhost:8080/coupon --manual
+
+# 交互式引导
+smart-test record --url http://localhost:8080/coupon --interactive
+```
+
+**选项：**
+
+| 选项             | 简写 | 说明                     |
+| ---------------- | ---- | ------------------------ |
+| `--url <url>`    | `-u` | 要录制的页面 URL（必需） |
+| `--output <dir>` | `-o` | 输出目录                 |
+| `--manual`       |      | 手动操作模式             |
+| `--interactive`  |      | 交互式引导               |
+
+### `smart-test config`
+
+查看当前配置。
+
+```bash
+smart-test config
+```
+
+### 全局选项
+
+| 选项        | 简写 | 说明                 |
+| ----------- | ---- | -------------------- |
+| `--version` | `-V` | 显示版本号           |
+| `--verbose` | `-v` | 详细输出（调试模式） |
+| `--help`    | `-h` | 显示帮助信息         |
+
+## 📖 编程 API 文档
 
 ### `configure(config)`
 
@@ -91,8 +247,6 @@ configure({
   apiKey: 'sk-xxx', // AI API 密钥
   baseURL: 'https://...', // AI 服务地址（可选）
   model: 'qwen3-vl-plus', // AI 模型（可选）
-  screenshotDir: './screenshots', // 截图保存目录（可选）
-  saveScreenshots: true, // 是否保存截图（可选）
   timeout: 30000, // 超时时间（可选）
 });
 ```
@@ -135,8 +289,6 @@ const result = await aiReviewScreenshot(page, '页面应该显示登录表单');
 const result = await aiReviewScreenshot(page, {
   expected: '页面应该显示商品列表',
   model: 'gpt-4-vision-preview', // 使用其他模型
-  saveScreenshots: false, // 不保存截图
-  screenshotPrefix: 'product', // 自定义截图前缀
 });
 ```
 
@@ -183,26 +335,48 @@ test.describe('商品页面测试', () => {
 });
 ```
 
-### 批量检查多个元素
-
-```typescript
-test('检查多个区域', async ({ page }) => {
-  const checks = [
-    { selector: '.header', expected: '顶部导航栏应显示 logo 和菜单' },
-    { selector: '.main-content', expected: '主内容区应显示文章列表' },
-    { selector: '.sidebar', expected: '侧边栏应显示热门标签' },
-  ];
-
-  for (const check of checks) {
-    const element = await page.locator(check.selector);
-    const screenshot = await element.screenshot();
-
-    // 这里可以扩展为单独检查某个元素的功能
-    // 当前版本检查整页，后续可以增强
+## 🔧 配置文件
+
+### `.smarttestrc.json`
+
+使用 `smart-test init` 命令生成的配置文件：
+
+```json
+{
+  "version": "1.0.0",
+  "ai": {
+    "model": "qwen3-vl-plus",
+    "apiKey": "${AI_API_KEY}",
+    "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    "timeout": 30000
+  },
+  "output": {
+    "testsDir": "./tests/e2e",
+    "helpersDir": "./tests/helpers",
+    "naming": "kebab-case"
+  },
+  "templates": {
+    "mock": "default",
+    "test": "default"
+  },
+  "playwright": {
+    "baseURL": "http://localhost:8080",
+    "viewport": {
+      "width": 375,
+      "height": 667
+    },
+    "browser": "chromium"
   }
-});
+}
 ```
 
+### 支持的配置格式
+
+- `.smarttestrc.json`
+- `.smarttestrc.js`
+- `smarttest.config.js`
+- `package.json` 中的 `smarttest` 字段
+
 ## 🔧 高级配置
 
 ### 支持多种 AI 模型
@@ -263,9 +437,17 @@ A: 理论上支持所有兼容 OpenAI Chat Completions API 的视觉模型，包
 - OpenAI GPT-4 Vision
 - 其他兼容的模型服务
 
-### Q: 截图保存在哪里？
+### Q: CLI 生成的测试代码需要手动修改吗？
+
+A: 生成的代码是可以直接运行的，但建议根据实际需求进行调整。AI 会尽量生成合理的测试用例，但可能无法覆盖所有业务场景。
+
+### Q: 录制模式如何处理需要点击才能触发的接口？
+
+A: 录制模式支持三种方式：
 
-A: 默认保存在 `./test-results/ai-screenshots/` 目录，可以通过 `screenshotDir` 配置修改。
+1. **手动操作**：`--manual` 参数，用户手动操作浏览器
+2. **交互式引导**：`--interactive` 参数，AI 引导用户操作
+3. **脚本引导**：`--actions` 参数，提供操作脚本自动执行
 
 ### Q: 如何查看 AI 的原始响应？
 
@@ -276,6 +458,55 @@ const result = await aiReviewScreenshot(page, '...');
 console.log('AI 原始响应:', result.rawResponse);
 ```
 
+### Q: 生成的代码文件如何组织？
+
+A: 默认按页面分组：
+
+- `tests/helpers/mock-{页面名}.ts` - Mock 数据
+- `tests/e2e/{页面名}.spec.ts` - 测试用例
+
+可以通过 `--output` 参数自定义输出目录。
+
+## 🗺️ 开发路线图
+
+### ✅ 已完成
+
+- [x] AI 视觉检查核心功能
+- [x] CLI 基础架构
+- [x] 配置系统
+- [x] 交互式初始化
+
+### 🚧 开发中
+
+- [ ] 录制模式（Phase 2）
+  - [ ] 网络请求录制
+  - [ ] HAR 文件解析
+  - [ ] AI 生成 Mock 代码
+  - [ ] 交互操作录制
+
+### 📅 计划中
+
+- [ ] 代码分析模式（Phase 3）
+  - [ ] TypeScript AST 解析
+  - [ ] API 调用提取
+  - [ ] 类型定义分析
+
+- [ ] 描述生成模式（Phase 4）
+  - [ ] 自然语言理解
+  - [ ] 交互式问答
+  - [ ] 代码生成
+
+- [ ] 增强功能（Phase 5+）
+  - [ ] 增量更新
+  - [ ] 自定义模板
+  - [ ] 测试覆盖率分析
+  - [ ] VS Code 插件
+
+## 📄 文档
+
+- [CLI 设计文档](./docs/CLI_DESIGN.md) - 完整的 CLI 工具设计方案
+- [使用示例](./examples/) - 更多使用示例
+
 ## 📝 License
 
 MIT
@@ -287,3 +518,7 @@ MIT
 ## 📮 联系方式
 
 如有问题，请在 [GitHub Issues](https://github.com/snowmountain-top/be-link/issues) 中提出。
+
+---
+
+**版本**：v1.0.0 | **最后更新**：2025-12-30

package/bin/smart-test.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+/**
+ * Smart Test CLI 入口文件
+ */
+
+// 使用 Node.js 原生 ESM 加载器
+import('../dist/cli/index.js')
+  .then((module) => {
+    module.run(process.argv);
+  })
+  .catch((error) => {
+    console.error('Failed to load CLI:', error);
+    process.exit(1);
+  });

package/dist/cli/commands/generate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 生成命令选项
+ */
+export interface GenerateOptions {
+    page?: string;
+    url?: string;
+    desc?: string;
+    output?: string;
+    interactive?: boolean;
+    dryRun?: boolean;
+}
+/**
+ * 生成命令
+ */
+export declare function generateCommand(options: GenerateOptions): Promise<void>;
+//# sourceMappingURL=generate.d.ts.map

package/dist/cli/commands/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAgD7E"}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 初始化命令
+ */
+export declare function initCommand(): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CA2HjD"}

package/dist/cli/index.d.ts

@@ -0,0 +1,10 @@
+import { Command } from 'commander';
+/**
+ * 创建 CLI 程序
+ */
+export declare function createCLI(): Command;
+/**
+ * 运行 CLI
+ */
+export declare function run(argv?: string[]): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAgEnC;AAED;;GAEG;AACH,wBAAsB,GAAG,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtE"}