# 贡献指南感谢您有兴趣为 @yuantest/playwright 做出贡献！本文档将帮助您了解如何参与项目开发。 ## 目录 - [行为准则](#行为准则) - [如何贡献](#如何贡献) - [开发环境设置](#开发环境设置) - [项目结构](#项目结构) - [开发流程](#开发流程) - [代码规范](#代码规范) - [提交规范](#提交规范) - [Pull Request 流程](#pull-request-流程) ## 行为准则本项目采用贡献者公约作为行为准则。参与此项目即表示您同意遵守其条款。请阅读 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 了解详情。 ## 如何贡献 ### 报告 Bug 如果您发现了 bug，请通过 [GitHub Issues](https://github.com/yuandiv/yuantest-playwright/issues) 提交报告。提交前请： 1. 搜索现有 issues，确认该问题尚未被报告 2. 使用 issue 模板填写详细信息 3. 提供可复现的步骤、预期结果和实际结果 ### 提出新功能欢迎提出新功能建议！请： 1. 通过 Issues 描述您的想法 2. 说明该功能的使用场景和价值 3. 等待维护者反馈后再开始实现 ### 提交代码我们非常欢迎代码贡献！请遵循以下流程。 ## 开发环境设置 ### 前置要求 - Node.js >= 16.0.0 - npm >= 7.0.0 - Git ### 安装步骤 ```bash # 1. Fork 并克隆仓库 git clone https://github.com//yuantest-playwright.git # 2. 进入项目目录 cd yuantest-playwright # 3. 安装依赖 npm install # 4. 编译项目 npm run build ``` ### 验证安装 ```bash # 运行测试 npm test # 运行 lint 检查 npm run lint # 运行类型检查 npm run typecheck ``` ## 项目结构 ``` yuantest-playwright/ ├── bin/ # CLI 入口文件 ├── dashboard/ # Web Dashboard 前端 (React + Vite) ├── src/ # 核心源代码 │ ├── orchestrator/ # 测试编排器 │ ├── executor/ # 测试执行器 │ ├── reporter/ # 报告生成器 │ ├── flaky/ # Flaky 测试管理 │ ├── realtime/ # WebSocket 实时报告 │ ├── trace/ # Trace 管理 │ ├── annotations/ # 注解扫描器 │ ├── tags/ # 标签管理器 │ ├── visual/ # 视觉测试 │ ├── storage/ # 存储提供者 │ ├── config/ # 配置管理 │ ├── cli/ # CLI 命令行 │ └── ui/ # Dashboard 服务器 ├── tests/ # 测试文件 │ ├── unit/ # 单元测试 │ ├── integration/ # 集成测试 │ └── e2e/ # 端到端测试 └── package.json ``` ## 开发流程 ### 1. 创建分支 ```bash # 从 main 创建新分支 git checkout -b feature/your-feature-name # 或 git checkout -b fix/your-bug-fix ``` 分支命名规范： - `feature/` - 新功能 - `fix/` - Bug 修复 - `docs/` - 文档更新 - `refactor/` - 代码重构 - `test/` - 测试相关 ### 2. 进行开发确保遵循 [代码规范](#代码规范)。 ### 3. 运行测试 ```bash # 运行所有测试 npm test # 运行特定测试文件 npm test -- path/to/test.test.ts # 运行测试并生成覆盖率报告 npm run test:coverage # 运行集成测试 npm run test:integration # 运行 E2E 测试 npm run test:e2e ``` ### 4. 代码检查 ```bash # 运行 ESLint npm run lint # 自动修复 lint 问题 npm run lint:fix # 运行类型检查 npm run typecheck # 检查代码格式 npm run format:check # 自动格式化代码 npm run format ``` ### 5. 提交代码遵循 [提交规范](#提交规范)。 ## 代码规范 ### TypeScript - 使用 TypeScript 编写所有代码 - 为所有公共 API 添加类型定义 - 避免使用 `any`，必要时使用 `unknown` - 为函数添加 JSDoc 注释（中文） ```typescript /** * 执行测试运行 * @param options - 执行选项 * @returns 测试运行结果 */ async execute(options?: ExecuteOptions): Promise { // ... } ``` ### 代码风格 - 使用 ESLint 和 Prettier 保持代码风格一致 - 使用 2 空格缩进 - 使用单引号 - 语句末尾不加分号（由 Prettier 自动处理） ### 文件命名 - 使用 kebab-case 命名文件 - 测试文件使用 `.test.ts` 后缀 - 类型定义放在 `types/index.ts` ### 测试规范 - 为新功能添加单元测试 - 测试覆盖率应达到 80% 以上 - 使用 describe/it 组织测试结构 - 测试描述使用中文 ```typescript describe('Orchestrator', () => { describe('orchestrate()', () => { it('应该正确分发测试到各个分片', () => { // ... }); }); }); ``` ## 提交规范我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范： ``` ():