2. 单元测试框架选型对比：Jest、Mocha、pytest、Go test的离线支持能力

2.1 离线优先测试的底层挑战

离线环境移除了网络依赖、远程服务、外部数据库和云存储等外部资源。单元测试框架自身的运行机制，包括测试发现、依赖注入、Mock/Stub能力、断言库以及覆盖率收集，必须在完全无网络的状态下正常工作。不同框架的内核设计决定了其离线支持的“原生度”。

2.2 四大框架离线支持对比表

2.3 各框架离线支持分析

2.3.1 Jest：一体化但对缓存依赖强

• 原理： Jest 集成了自动 Mock、断言、覆盖率、快照测试。所有功能在 `node_modules` 锁定版本后完全离线可用。
• 实现流程： 使用 `yarn --frozen-lockfile` 或 `npm ci` 确保 node_modules 与 lock 文件一致；离线后直接 `npx jest --ci --no-cache`。
• 离线配置示例：

// jest.config.js
module.exports = {
  clearMocks: true,
  restoreMocks: true,
  // 禁用网络请求，主动抛出异常
  transform: {
    '^.+\\.(ts|tsx)$': 'ts-jest',
  },
  // 即使有网络请求也会快速失败
  testEnvironment: 'node',
  // 覆盖率内建
  collectCoverage: true,
  coverageReporters: ['json', 'text', 'lcov'],
};

• 调试： `--verbose` 看到每个测试的状态；`--showSeed` 可用于复现 CI 上的顺滑顺序。
• 常见错误： 未预装 `node_modules` 时 `jest.mock` 会报模块未找到；快照文件没有提交到 Git 仓库会导致快照测试失败。

2.3.2 Mocha：灵活但需手动组装工具链

• 原理： Mocha 是测试运行器核心，不包含 Mock/断言/覆盖率。用户必须搭配 Sinon.js、Chai、nyc 等库。
• 实现流程： 在 `package.json` 的 `devDependencies` 中列明所有工具，运行 `npm ci` 后全量缓存。
• 离线命令示例：

# 运行 Mocha 测试（无网络场景）
npx mocha --require ts-node/register --reporter mochawesome --timeout 30000 src/**/*.test.ts

# 覆盖率（需提前安装 nyc）
npx nyc --reporter=html --reporter=text mocha --reporter json

• 调试： 使用 `--inspect-brk` 启动 Node 调试器。
• 常见错误： 缺少断言库时测试不会失败但无法执行 `expect` 链；覆盖率报告依赖 nyc 的 `--require` 钩子，若 Babel 编译链未预装则报告为空。

2.3.3 pytest：生态强大但需独立管理 wheelhouse

• 原理： pytest 的插件体系（pytest-mock, pytest-cov, pytest-html）可提前下载为 `.whl` 文件，离线安装。
• 实现流程： 在联网环境创建离线仓库：`pip download -r requirements-dev.txt -d wheelhouse`。
• 离线安装与运行：

# 从本地 wheelhouse 安装所有依赖
pip install --no-index --find-links ./wheelhouse -r requirements-dev.txt

# 运行测试（覆盖率、JUnit 报告）
python -m pytest --cov=src --cov-report=html --junitxml=report.xml tests/

• 调试： `-s` 显示 print 输出；`-pdb` 在失败时进入调试器。
• 常见错误： 自定义的 fixture 或 conftest.py 中引入了未预装的第三方包会导致 `ModuleNotFoundError`；插件版本与 pytest 主版本不兼容报存档解析错误。

2.3.4 Go test：原生离线最简方案

• 原理： Go 的标准库 `testing` 包自带测试运行、断言、覆盖率，无需第三方库。模块依赖通过 `vendor` 目录完全离线。
• 实现流程： 项目初始化后 `go mod vendor` 将所有依赖复制到 `vendor` 文件夹；之后 `go test -tags netgo -mod=vendor ./...` 完全不访问网络。
• 离线编译与测试：

# 确保 vendor 目录存在（联网时执行一次）
go mod vendor

# 关闭网络访问，使用 vendor 模式运行测试
CGO_ENABLED=0 GOFLAGS="-mod=vendor" go test -coverprofile=coverage.out -v ./...

# 生成覆盖率 HTML 报告
go tool cover -html=coverage.out -o coverage.html

• 调试： `go test -run TestFunctionName -v -gcflags=-l` 禁用内联以获取更清晰的堆栈。
• 常见错误： `vendor/modules.txt` 未包含所有依赖；间接依赖使用了 `go get` 意外引入外部网络；`CGO_ENABLED=1` 且宿主机缺少 gcc/clang 导致链接失败。

2.4 离线能力的递进式判断

2.5 离线测试配置清单（通用）

npm ls --depth=0

pip download -r req-dev.txt -d wheelhouse

npm config set registry ''; GONOSUMCHECK=*

npx jest --ci --coverage

strace -e network go test -mod=vendor ./...

2.6 常见错误与稳定性优化

• 错误： Jest 运行 `jest.mock('axios')` 但 `axios` 未在 node_modules 中 → 解决：确保所有 Mock 的模块显式列在 `devDependencies`。
• 错误： Mocha 使用 `chai-http` 做集成测试，但离线时没有 `chai-http` → 解决：将集成测试标记为 `@network` 并使用 `--grep` 跳过。
• 错误： pytest 插件 `pytest-postgresql` 在离线环境中因 `psycopg2` 二进制包缺失而失败 → 解决：使用 `--no-binary :all:` 强制从源码构建，或提前下载静态 wheel。
• 优化： 所有框架的测试发现阶段应避免递归扫描 `node_modules` 或 `__pycache__` 以提升性能（Jest 用 `modulePathIgnorePatterns`，pytest 用 `--ignore`）。
• 优化： 使用 `jest --onlyChanged`（Git 变基后）可在离线模式下仅测试修改过的文件，大幅缩短反馈周期。

2.7 离线支持能力框架图

2.8 离线选型最终建议

• 纯离线 CI 环境（Air-gapped）： 优先选用 Go test（Go 项目）或 pytest（Python 项目），因为 vendor 模式和 wheelhouse 可以完全避免运行时网络请求。Jest 在完全离线时需额外注意 node_modules 的完整性校验。
• 部分离线（本地开发与 CD 相同）： 四个框架均可，但务必在联网阶段运行一次 `npm ci` / `pip install` / `go mod vendor` 并锁定缓存目录。
• Mock 密集型项目： Jest 和 pytest（带 pytest-mock）的原生 Mock 在离线时无需额外安装，而 Mocha 必须预装 Sinon.js，Go test 需要预先生成 mock 代码。
• 报告与可观测性： 如果离线环境还需要生成 HTML 报告或 JUnit XML，Jest 和 Go test 的内建能力最省心；pytest 需要预装 `pytest-html`，Mocha 需要预装 `mochawesome`。