Skip to content

README.md

Latest commit

 

History

History
331 lines (247 loc) · 9.52 KB

README.md

File metadata and controls

331 lines (247 loc) · 9.52 KB

E2E 测试

这是 cocos-cli 的端到端（E2E）测试套件，用于测试打包后的 CLI 命令和 MCP 服务器 API。

📋 特点

  • 独立运行：只依赖 dist/ 目录和 tests 文件夹，不依赖功能源码
  • 真实环境：测试实际用户使用场景
  • 完整覆盖：包括 CLI 命令和 MCP API 测试
  • 并行安全：使用临时目录和随机端口

🚀 快速开始

前置条件

确保项目已经构建：

npm run build

基本用法

# 运行所有 E2E 测试
npm run test:e2e

# 调试模式（保留测试工作区，不删除测试文件）
npm run test:e2e:debug

# 或者使用参数方式
npm run test:e2e -- --preserve

# 运行所有测试（单元测试 + E2E）
npm run test:all

# 运行指定测试文件
npm run test:e2e -- tests/cli/build.e2e.test.ts
npm run test:e2e:debug -- tests/cli/build.e2e.test.ts

# 运行指定测试目录
npm run test:e2e -- tests/mcp/api

查看测试报告

测试完成后会自动生成可视化的 HTML 报告：

# 测试报告位置（包含本地时间戳）
e2e/server/reports/test-report-2024-01-15-10-30.html

自动打印报告路径

测试完成后，会在控制台自动打印报告的完整路径和快速打开命令：

============================================================
📊 测试报告已生成
============================================================

✅ HTML 测试报告路径:
   F:\code\cocos-cli\e2e\reports\test-report-2025-10-28-15-30-00.html

💡 快速打开报告:
   start F:\code\cocos-cli\e2e\reports\test-report-2025-10-28-15-30-00.html
============================================================

直接复制快速打开命令即可在浏览器中查看！

手动打开报告

# Windows
start e2e/server/reports/test-report-*.html

# macOS
open $(ls -t e2e/server/reports/test-report-*.html | head -1)

# Linux
xdg-open $(ls -t e2e/server/reports/test-report-*.html | head -1)

报告包含：

  • ✅ 测试通过/失败统计
  • ⏱️ 每个测试的执行时间
  • 📋 详细的错误信息和堆栈跟踪
  • 📊 按状态排序的测试列表
  • 💬 控制台日志输出

指定 CLI 路径

# 测试默认的 dist/ 目录
npm run test:e2e

# 指定特定的 CLI 路径
npm run test:e2e -- --cli ./dist/cli.js

# 测试全局安装的包
npm run test:e2e -- --cli $(which cocos)

💡 更多测试场景和配置选项，请参考 CLI 路径配置指南

📁 目录结构

e2e/
├── cli/                          # CLI 命令测试
│   ├── build.e2e.test.ts        # 测试 cocos build 命令
│   └── create.e2e.test.ts       # 测试 cocos create 命令
├── mcp/                          # MCP 服务器测试
│   ├── server.e2e.test.ts       # 测试 MCP 服务器启动和错误处理
│   └── api/                      # API 接口测试
│       ├── builder.e2e.test.ts  # 测试构建 API
│       └── assets/              # 资源 API 测试（按功能拆分）
│           ├── operation.e2e.test.ts  # 资源操作（创建、删除、移动、保存、重命名、刷新）
│           ├── query.e2e.test.ts      # 资源查询
│           ├── import.e2e.test.ts     # 资源导入和重新导入
│           └── user-data.e2e.test.ts  # 资源用户数据管理
├── helpers/                      # 测试辅助工具
│   ├── cli-runner.ts            # CLI 命令执行器
│   ├── mcp-client.ts            # MCP 客户端封装
│   ├── project-manager.ts       # 测试项目管理器
│   ├── shared-mcp-server.ts    # 共享 MCP 服务器管理
│   ├── test-utils.ts            # 通用测试工具函数
│   └── report-printer.js        # 测试报告打印工具
├── scripts/                     # 🛠️ 辅助脚本
│   ├── check-coverage.ts        # E2E 测试覆盖率检查脚本
│   ├── generate-mcp-types.ts    # 自动生成 MCP 工具类型定义
│   ├── tool-utils.ts            # MCP 工具扫描共享工具函数
│   ├── prepare-test.js           # 测试准备脚本
│   └── README.md                 # 脚本说明文档
├── docs/                         # 📚 文档
│   ├── CLI-PATH-GUIDE.md        # CLI 路径配置指南
│   ├── USAGE.md                 # 详细使用指南
│   ├── PROJECT-MANAGER-GUIDE.md # 测试项目管理器指南
│   ├── E2E-COVERAGE-CHECK.md    # E2E 测试覆盖率检查
│   ├── WIZARD-TESTING-LIMITATIONS.md # Wizard 测试限制说明
│   ├── README-TSCONFIG.md       # TypeScript 配置说明
│   ├── REPORT-SERVER-SETUP.md   # 测试报告服务器设置
│   └── TYPE-INFERENCE-EXAMPLE.md # 类型推断示例
├── types/                        # 类型定义
│   └── mcp-tools.generated.ts    # 自动生成的 MCP 工具类型定义
├── reports/                      # 测试报告（自动生成）
│   └── test-report-*.html       # HTML 测试报告
├── config.ts                    # ⚙️ 全局配置（超时、端口等）
├── jest.config.e2e.ts           # E2E 测试配置
├── tsconfig.json                # TypeScript 配置（仅类型检查）
├── setup.ts                     # 全局测试前置
├── teardown.ts                  # 全局测试清理
├── jest.setup.ts                # Jest 环境配置
└── README.md                    # 本文档

🔧 测试辅助工具

CLIRunner

用于执行 CLI 命令：

import { cliRunner } from '../helpers/cli-runner';

// 执行构建
const result = await cliRunner.build({
    project: testProjectPath,
    platform: 'web-desktop',
    debug: true,
});

MCPTestClient

用于测试 MCP API：

import { MCPTestClient } from '../helpers/mcp-client';

// 创建并启动客户端
const client = new MCPTestClient({
    projectPath: testProjectPath,
    port: 9527,
});
await client.start();

// 调用 API
const result = await client.callTool('builder-build', {
    platform: 'web-desktop',
});

// 关闭客户端
await client.close();

测试工具函数

import {
    createTestProject,
    getSharedTestProject,
    checkPathExists,
    validateBuildOutput,
    E2E_TIMEOUTS,
} from '../helpers/test-utils';
import { resolve } from 'path';

// 创建独立的测试项目（用于写入测试）
const fixtureProject = resolve(__dirname, '../../tests/fixtures/projects/asset-operation');
const testProject = await createTestProject(fixtureProject);
console.log('测试项目路径:', testProject.path);

// 使用共享测试项目（用于只读测试）
const sharedProject = await getSharedTestProject(fixtureProject, 'readonly-common');
console.log('共享项目路径:', sharedProject.path);

// 验证路径是否存在
const exists = await checkPathExists(testProject.path);

// 验证构建输出
const validation = await validateBuildOutput(buildPath);

// 使用统一的超时配置
test('long operation', async () => {
    // ...
}, E2E_TIMEOUTS.BUILD_OPERATION);

📝 编写新测试

CLI 测试示例

import { cliRunner } from '../helpers/cli-runner';

describe('my new command', () => {
    test('should execute successfully', async () => {
        const result = await cliRunner.run(['my-command', '--option', 'value']);
        
        expect(result.exitCode).toBe(0);
        expect(result.stdout).toContain('success');
    });
});

MCP API 测试示例

import { MCPTestClient } from '../helpers/mcp-client';

describe('my new API', () => {
    let client: MCPTestClient;

    beforeAll(async () => {
        client = new MCPTestClient({ projectPath, port: 9527 });
        await client.start();
    });

    afterAll(async () => {
        await client.close();
    });

    test('should call API successfully', async () => {
        const result = await client.callTool('my-api-name', { arg: 'value' });
        
        expect(result.code).toBe(200);
        expect(result.data).toBeDefined();
    });
});

⚠️ 注意事项

  1. 测试隔离：每个测试应使用独立的临时目录和端口
  2. 资源清理：测试后必须清理临时文件和关闭服务器进程
  3. 超时设置：构建测试需要较长时间（最多 5 分钟）
  4. 错误处理：测试应该覆盖正常和异常场景
  5. CI 兼容：测试应该能在 CI 环境中运行

🐛 调试

保留测试工作区（调试模式）

# 方式 1：使用快捷脚本
npm run test:e2e:debug

# 方式 2：使用参数
npm run test:e2e -- --preserve

# 方式 3：组合使用（保留工作区 + 运行单个测试）
npm run test:e2e -- --preserve e2e/cli/build.e2e.test.ts

调试模式特性：

  • ✅ 测试后不删除 e2e/.workspace/ 目录
  • ✅ 可以查看测试生成的项目文件
  • ✅ 方便排查测试失败原因

查看详细输出

npm run test:e2e -- --verbose

运行单个测试文件

npm run test:e2e -- e2e/cli/build.e2e.test.ts

只测试特定部分

# 只测试 CLI
npm run test:e2e -- e2e/cli

# 只测试 MCP
npm run test:e2e -- e2e/mcp

📚 文档