@composy/testing

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

English documentation: 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 / 快照 / 生成器工具
• 自动巡检子模块导出

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

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

安装

pnpm add -D @composy/testing

或：

npm install -D @composy/testing

快速开始

1. 初始化测试基线

npx ltesting init

指定 preset：

npx ltesting init --preset react

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

2. 运行常见工作流

# 全量测试工作流
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. 生成辅助产物

# 生成 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 中：

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 阶段用于生成更贴近项目类型的默认配置。

目录结构

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 先把 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

常用开发脚本

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 统一接入

接入类型：bin 统一命令：ldesign test 命令别名：t、testing 包内原生 bin：ldesign-test、ldesign-testing、ltesting 当前包通过独立 bin 接入，统一命令会转发到包自身 CLI。

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