# ldesign-testing

**Repository Path**: ldesign-v1/ldesign-testing

## Basic Information

- **Project Name**: ldesign-testing
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @composy/testing

`@composy/testing`
是 LDesign 工具链中的统一测试工作流包，用来把日常分散的 Vitest、Playwright、覆盖率、Mock、快照、性能基准与自动巡检能力收口到一套可复用、可编排、可扩展的 Node.js/TypeScript 包中。

English documentation: [README.en.md](./README.en.md)

## 核心定位

这个包并不是简单“再包一层 Vitest”，而是提供一套偏工程化的测试基础设施：

- 统一初始化项目测试基线
- 统一命令行入口和测试运行策略
- 支持 dry-run 执行计划，提前解释将要运行的阶段、范围和选择原因
- 提供覆盖率分析、覆盖率汇总诊断、历史报告、Mock 数据和快照管理
- 保留自动化巡检体系（`automation/*`）
- 对外提供可组合的 TypeScript API，便于二次封装

适合以下场景：

- 团队希望统一测试脚本、配置文件与执行口径
- 包/应用同时需要单测、E2E、覆盖率与巡检能力
- 希望保留测试历史、失败重跑和按变更选择测试等工作流增强
- 需要在 monorepo 内共享一套测试工具底座

## 当前能力

### CLI 命令面

稳定 CLI 入口由 `bin/cli.js` 暴露，当前主命令包括：

- `init`
- `run`
- `run:unit`
- `run:e2e`
- `flow`
- `doctor`
- `coverage`
- `snapshot`
- `mock`
- `generate`

### 运行时模块

- `src/config/*` 负责配置加载、校验、preset 管理
- `src/runners/*` 负责 Vitest / Playwright / 并行运行与测试选择
- `src/reporting/*` 负责结果格式化、覆盖率分析、历史报告存储
- `src/mocking/*` 负责 Faker、MSW、函数 mock 与 mock 数据工厂
- `src/snapshots/*` 负责组件快照与视觉快照
- `src/performance/*` 负责 tinybench 基准测试封装
- `src/automation/*` 负责自动巡检、页面分析、API 分析、UI 巡检、回归分析、通知与报告
- `src/workflow/*`
  负责 JSON 流程定义、项目组合执行、阶段反馈、校验、计划、受控服务生命周期、原生框架 CLI 适配、专项质量门禁与
  `release:gate` 适配

### 对外 API

入口位于 `src/index.ts`，常见导出包括：

- 配置与 preset 能力
- Vitest / Playwright 运行器
- 测试执行计划与 changed/failed 选择器
- 覆盖率分析器、阈值校验器与 doctor 覆盖率 / Playwright / CI 一致性检查
- Mock / 快照 / 生成器工具
- 自动巡检子模块导出

构建后会按源码目录保留稳定子路径导出，便于消费者只引入需要的能力：

```ts
import { ConfigLoader } from '@composy/testing/config'
import { MockFactory } from '@composy/testing/mocking'
import { VitestRunner } from '@composy/testing/runners'
import { CIIntegrator } from '@composy/testing/automation'
```

自动巡检的项目探测和 CI 配置生成复用 `@composy/runtime` 的包管理器识别与命令生成，当前可识别
`npm`、`pnpm`、`yarn` 和 `bun`。

## 技术栈

- Node.js `>= 18`
- TypeScript（ESM，`"type": "module"`）
- 打包：`@composy/pack`（来自 `tools/tsup-config` 工作区包）
- 单测：Vitest
- E2E：Playwright
- Mock：`@faker-js/faker`、MSW
- 性能基准：tinybench
- 文档：Markdown / VitePress

## 安装

```bash
pnpm add -D @composy/testing
```

或：

```bash
npm install -D @composy/testing
```

## 快速开始

### 1. 初始化测试基线

```bash
npx ltesting init
```

指定 preset：

```bash
npx ltesting init --preset react
```

初始化后会生成测试配置与示例测试文件。

### 2. 运行常见工作流

```bash
# 全量测试工作流
npx ltesting run

# 仅运行 unit 测试
npx ltesting run:unit

# 仅运行指定的 unit 测试文件
npx ltesting run:unit src/foo.test.ts src/bar.test.ts

# 运行 E2E
npx ltesting run:e2e

# 覆盖率分析
npx ltesting coverage

# 仅跑与当前改动关联的测试
npx ltesting run:unit --changed

# 重跑上一次失败的测试
npx ltesting run:unit --failed

# 只输出执行计划，不真正启动 Vitest / Playwright
npx ltesting run --changed --dry-run

# 诊断配置、依赖、覆盖率汇总、Playwright 浏览器、CI 脚本和执行计划
npx ltesting doctor --type unit

# CI 中使用 JSON 输出并把警告视为失败
npx ltesting doctor --json --strict

# 写入 Markdown 诊断报告，便于 CI artifact 或 GitHub Summary 归档
npx ltesting doctor --format markdown --output test-reports/doctor.md

# 写入 GitHub Actions Step Summary 友好的精简报告
npx ltesting doctor --format github-summary --output "$GITHUB_STEP_SUMMARY"

# 生成、校验并执行 JSON 流程；dry-run 不会执行步骤
npx ltesting flow init
npx ltesting flow validate .ldesign/.testing/flows/example.flow.json
npx ltesting flow run .ldesign/.testing/flows/example.flow.json --dry-run

# 同一套步骤覆盖多个项目；可只运行指定项目
npx ltesting flow run .ldesign/.testing/flows/example.flow.json --project admin site

# 打开本地工作台；从前端完整回归、本地发布门禁或自定义流程开始
# 在同一工作台管理项目、编辑执行链，并查看运行记录与项目报告
npx ltesting flow ui .ldesign/.testing/flows/example.flow.json --open

# 在流程中通过原生 CLI 运行 Vitest/Jest/Cypress/k6 等框架，并归档其报告产物
# 详见 docs/guide/flow-testing.md 中的 framework 步骤

# 生成并预演 LDesign 本地发布验收流程
npx ltesting flow init --template release-gate
npx ltesting flow run .ldesign/.testing/flows/release-gate.flow.json --dry-run
```

### 3. 生成辅助产物

```bash
# 生成 Mock 数据
npx ltesting mock user --count 10 --output ./mocks/users.json

# 管理快照
npx ltesting snapshot list
npx ltesting snapshot update

# 生成测试模板
npx ltesting generate --file src/components/Button.tsx --type unit
```

## 配置示例

默认配置可以放在 `.ldesign/.testing/testing.config.ts` 中：

```ts
import type { TestingConfig } from '@composy/testing'

const config = {
  framework: 'vitest',
  testMatch: ['**/*.test.{ts,tsx,js,jsx}', '**/*.spec.{ts,tsx,js,jsx}'],
  unit: {
    environment: 'jsdom',
    setupFiles: ['tests/setup.ts'],
    timeout: 5000,
    clearMocks: true,
    resetMocks: true,
    restoreMocks: true,
  },
  coverage: {
    enabled: true,
    provider: 'v8',
    reporter: ['text', 'json-summary', 'html'],
    threshold: {
      branches: 70,
      functions: 70,
      lines: 70,
      statements: 70,
    },
  },
  e2e: {
    framework: 'playwright',
    baseUrl: 'http://localhost:3000',
    testDir: 'tests/e2e',
    browsers: ['chromium'],
    headless: true,
  },
} satisfies TestingConfig

export default config
```

## Preset

内置 preset：

- `base`
- `web`
- `react`
- `next`
- `vue`
- `nuxt`
- `node`
- `library`

它们主要在 `init` 阶段用于生成更贴近项目类型的默认配置。

## 目录结构

```text
src/
  automation/     自动巡检、报告、通知、回归分析
  cli/            命令行入口与命令实现
  config/         配置加载、校验、preset
  diagnostics/    doctor 诊断、覆盖率/浏览器/CI 检查、检查项和执行计划格式化
  filesystem/     文件与路径工具
  generation/     测试模板生成
  logging/        日志门面
  mocking/        Faker / MSW / 函数 Mock
  performance/    性能基准工具
  reporting/      覆盖率与历史报告
  runners/        Vitest / Playwright / 并行运行
  snapshots/      组件/视觉快照
  types/          共享类型
  workflow/       JSON 流程测试、项目组合执行与阶段反馈
```

## 打包与发布

### 当前打包方案

本包已经使用工作区中的 `tools/tsup-config` 包，也就是运行时包名 `@composy/pack` 进行统一打包。

`@composy/pack` 会基于包元数据零配置推导入口，并：

- 递归收集 `src/**` 下所有运行时代码
- 排除 `*.test.*`、`*.spec.*`、`*.d.ts`
- 将源码相对路径映射到 `dist/**`
- 同时生成 `esm`、`cjs` 与 `d.ts`

当前 `.ldesign/` 目录仅保留文档配置，不再要求为工具包本体维护单独的 tsup 配置文件。

### 当前产物

构建后会在 `dist/` 下看到：

- `dist/index.js` / `dist/index.cjs` / `dist/index.d.ts`
- `dist/cli/**`
- `dist/automation/**`
- `dist/config/**`
- `dist/reporting/**`
- `dist/runners/**`
- 以及其它运行时代码的逐文件产物

当前已验证存在 `72` 个 `d.ts` 产物，说明类型声明已随运行时代码展开生成。当前最新构建已展开到 `144`
个 `d.ts` 文件，对应 `src/**` 运行时代码的镜像产物。

## 质量基线

本轮已确认：

- `pnpm run lint:check` 通过
- `pnpm run type-check` 通过
- `pnpm run build` 通过
- `pnpm run test:run` 通过
- `pnpm run test:smoke` 通过
- `pnpm run test:performance` 通过
- `pnpm run test:coverage` 通过
- `node ./bin/cli.js --help` 通过

## 测试验证说明

### 当前测试启动策略

本包当前不再依赖 `vitest` 默认的 Vite/esbuild 配置加载链来运行测试，而是通过
[`scripts/run-vitest.mjs`](./scripts/run-vitest.mjs) 先把 `src/**`
预编译到临时目录，再让 Vitest 直接运行编译后的 JS 测试文件。

这样做的目的有两个：

- 绕开当前 Windows 沙箱里 `esbuild` / `net use` 的 `spawn EPERM`
- 保留 sourcemap，保证测试失败时仍能映射回原始 TypeScript 文件

当前策略已经验证通过：

- `pnpm run test:run`
- `pnpm run test:smoke`
- `pnpm run test:performance`
- `pnpm run test:coverage`

## 常用开发脚本

```bash
pnpm run lint:check
pnpm run type-check
pnpm run build
pnpm run test:run
pnpm run test:coverage
pnpm run test:smoke
pnpm run test:performance
node ./bin/cli.js --help
```

## 可维护性优化说明

本轮对包内工程质量做了以下收口：

- 清理并修复历史 ESLint 问题，使 `@antfu/eslint-config` 下的 `lint:check` 全绿
- 收紧部分 mock / 自动化模块的类型边界
- 显式处理 Node 运行时对象导入与日志输出边界
- 保留 `automation/*` 中适合浏览器注入/模式定义场景的局部 lint 例外，避免规则误伤
- 新增无 `esbuild` 依赖的测试启动器，稳定收口沙箱和 Windows 环境下的 Vitest 执行路径
- 新增 `--dry-run` 执行计划，复用结构化 `TestExecutionPlan` 类型
- 子进程环境变量合并复用 `@composy/runtime`，避免各运行器重复拼接 `process.env`
- 将日志测试更新为基于 `stdout/stderr` 的断言，和当前运行时实现保持一致

## README / 文档约定

- 中文主文档：`README.md`
- 英文文档：`README.en.md`
- 构建配置：`@composy/pack` 零配置入口
- 测试启动脚本：`scripts/run-vitest.mjs`
- 会话维护记录：`AGENTS.md`

## License

MIT

## 通过 `@composy/cli` 统一接入

<!-- ldesign-cli-integration:start -->

- 接入类型：`bin`
- 统一命令：`ldesign test`
- 命令别名：`t`、`testing`
- 包内原生 bin：`ldesign-test`、`ldesign-testing`、`ltesting`

当前包通过独立 bin 接入，统一命令会转发到包自身 CLI。

```bash
pnpm add -D @composy/cli
ldesign test --help
ldesign tools run testing --help
```

<!-- ldesign-cli-integration:end -->