测试系统

相关源文件

• .github/workflows/generate-theme-doc.yml
• .github/workflows/test.yml
• .husky/.gitignore
• .husky/pre-commit
• jest.config.js
• package-lock.json
• package.json
• src/calculateRank.js
• tests/calculateRank.test.js
• tests/e2e/e2e.test.js
• tests/fetchRepo.test.js

本文档全面概述了 GitHub Readme Stats 中实现的测试框架。该测试系统通过自动化测试套件，确保了代码库的可靠性和可维护性，这些测试套件验证了卡片渲染、数据获取和其他核心功能的正确行为。有关设置开发环境的信息，请参阅开发环境设置。

1. 测试架构概览

GitHub Readme Stats 项目采用多层测试方法，在不同抽象级别上验证其组件的功能。

来源： package.json22-26 .github/workflows/test.yml12-47 .husky/pre-commit1-3

2. 测试类型

2.1 单元测试

单元测试用于隔离验证单个组件和函数的正确行为。这些测试侧重于特定的逻辑和边缘情况。

单元测试验证

• 数学计算（如排名计算）
• API 请求/响应处理
• 错误处理和边缘情况
• SVG 渲染准确性

来自 calculateRank.test.js 的示例测试

来源： tests/calculateRank.test.js5-19 tests/fetchRepo.test.js41-105

2.2 端到端测试

端到端测试通过将本地生成的卡片与已部署的 Vercel 预览生成的卡片进行比较来验证整个系统。

E2E 测试

• 验证已部署的 API 端点是否正常运行
• 确保本地和已部署环境之间的渲染一致性
• 测试所有卡片类型（统计信息、语言、WakaTime、仓库、gist）
• 验证自定义选项是否正常工作

来源： tests/e2e/e2e.test.js1-225 package.json25

2.3 基准测试

基准测试用于衡量关键操作的性能，以确保系统保持高效。

来源： package.json34 .github/workflows/test.yml38-40

3. 测试配置

3.1 Jest 配置

该项目使用 Jest 作为其主要测试框架，配置如下：

关键配置点

• JSDOM 环境用于 DOM 操作测试
• V8 覆盖率提供程序用于准确的覆盖率指标
• E2E 测试的独立配置

来源： jest.config.js1-12 package.json22-34

3.2 测试脚本

该项目提供了几个 npm 脚本来运行不同类型的测试

脚本	目的	命令
test	运行所有单元测试并包含覆盖率	node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage
test:watch	在监视模式下运行测试	node --experimental-vm-modules node_modules/jest/bin/jest.js --watch
test:update:snapshot	更新测试快照	node --experimental-vm-modules node_modules/jest/bin/jest.js -u
test:e2e	运行端到端测试	node --experimental-vm-modules node_modules/jest/bin/jest.js --config jest.e2e.config.js
bench	运行基准测试	node --experimental-vm-modules node_modules/jest/bin/jest.js --config jest.bench.config.js

来源： package.json22-34

4. CI/CD 测试集成

4.1 GitHub Actions 工作流

GitHub Readme Stats 使用 GitHub Actions 工作流在每次推送到 master 分支和拉取请求时自动运行测试。

工作流

1. 设置 Node.js 环境
2. 安装依赖项
3. 运行单元测试
4. 使用 ESLint 执行 linting
5. 运行基准测试
6. 使用 Prettier 检查代码格式
7. 将代码覆盖率上传到 Codecov

来源： .github/workflows/test.yml1-47

4.2 提交前钩子 (Pre-commit Hooks)

该项目使用 Husky 来实现提交前钩子，在允许提交之前运行测试和 linting。

这确保所有提交的代码都通过测试并符合编码标准。

来源： .husky/pre-commit1-3 package.json32-33 package.json71-73

5. 编写测试

5.1 单元测试结构

单元测试遵循以下通用模式

1. 导入所需的模块和函数
2. 设置测试数据和模拟（如果需要）
3. 使用 describe 和 it/test 定义测试用例
4. 对预期行为进行断言

关于 fetchRepo 函数的单元测试示例

来源： tests/fetchRepo.test.js41-51 tests/calculateRank.test.js5-19

5.2 端到端测试结构

E2E 测试用于验证已部署的 API 端点的功能

1. 设置测试环境和数据
2. 向已部署的 API 发起请求
3. 将 API 响应与本地生成的结果进行比较
4. 断言它们匹配

统计卡片的 E2E 测试示例

来源： tests/e2e/e2e.test.js115-135

6. 测试覆盖率和质量保证

6.1 代码覆盖率

该项目使用 Jest 的内置覆盖率报告和 Codecov 来跟踪测试覆盖率。

覆盖率指标有助于识别

• 未测试的代码路径
• 需要更全面测试的复杂函数
• 潜在的回归区域

来源： .github/workflows/test.yml46-47 package.json22

6.2 质量门

几个质量门确保代码的可靠性

1. 提交前钩子：在本地提交前运行测试和 linting
2. CI 检查：自动在所有 PR 上运行，以验证代码质量
3. PR 审查：用于额外质量保证的手动代码审查流程
4. 覆盖率要求：通过与 Codecov 的 CI 集成来维护

来源： .husky/pre-commit1-3 .github/workflows/test.yml1-47

7. 在本地运行测试

开发人员可以使用以下命令在本地运行测试

命令	目的
npm test	运行所有单元测试并包含覆盖率
npm run test:watch	在 watch 模式下运行测试（开发过程中很有用）
npm run test:e2e	运行端到端测试（需要设置环境）
npm run bench	运行基准测试

注意：E2E 测试需要在 .env 文件中设置 VERCEL_PREVIEW_URL 环境变量。

来源： package.json22-34 tests/e2e/e2e.test.js4-5 tests/e2e/e2e.test.js110-113

8. 总结

GitHub Readme Stats 中的测试系统提供了跨多个级别的全面功能验证。通过将单元测试、端到端测试和基准测试与自动化 CI/CD 集成相结合，该项目在支持持续开发的同时，保持了高质量和可靠性。