toast Docker镜像文档

镜像概述和主要用途

toast Docker镜像是将toast测试运行器打包成的容器化应用，基于Node.js环境构建，旨在提供一致、高效的JavaScript/TypeScript测试执行环境。该镜像无需手动安装依赖，可直接运行测试，支持前端（React、Vue等）和后端（Node.js）项目，适合本地开发调试和CI/CD流水线集成，帮助开发者快速验证代码正确性。

核心功能和特性

• 高性能并行测试：优化的执行引擎支持多线程并行测试，大幅缩短测试耗时。
• 全标准兼容：原生支持ES模块（ESM）和CommonJS，兼容TypeScript及现代JavaScript语法。
• 零配置启动：默认自动识别*.test.js、*.spec.ts等测试文件，无需手动配置。
• 轻量独立运行：不依赖外部测试框架，容器化设计确保跨环境一致性。
• 多格式报告输出：支持TAP、JSON、简洁文本等报告格式，适配CI/CD日志系统。
• 实时文件监听：通过--watch参数监听文件变更，自动重跑受影响的测试用例。
• 内置覆盖率分析：支持生成HTML、LCov等格式的代码覆盖率报告，直观展示测试覆盖情况。

使用场景和适用范围

适用项目类型

• 前端应用：React、Vue、Angular等框架的组件测试和功能测试。
• 后端服务：Node.js API服务的接口测试和业务逻辑验证。
• 工具库开发：JavaScript/TypeScript工具包的单元测试和集成测试。

典型使用场景

• 本地开发：开发者在编码过程中快速运行测试，即时反馈代码问题。
• CI/CD流水线：集成到GitHub Actions、GitLab CI等平台，实现提交/合并时的自动化测试。
• 多环境验证：在开发、测试、预发布环境中使用统一测试工具，避免环境差异导致的测试结果不一致。

使用方法和配置说明

获取镜像

从Docker Hub拉取最新版本镜像：

bash
docker pull stepchowfun/toast:latest

基本测试命令

在项目根目录运行默认测试（自动查找测试文件）：

bash
docker run --rm -v $(pwd):/app -w /app stepchowfun/toast toast

指定测试文件/目录

显式指定测试文件路径或匹配模式：

bash
# 运行src目录下所有.test.ts文件
docker run --rm -v $(pwd):/app -w /app stepchowfun/toast toast src/**/*.test.ts

# 运行单个测试文件
docker run --rm -v $(pwd):/app -w /app stepchowfun/toast toast tests/utils.spec.js

实时监听模式

启动文件监听，代码变更时自动重跑测试：

bash
docker run --rm -v $(pwd):/app -w /app stepchowfun/toast toast --watch src/test

生成覆盖率报告

生成HTML格式覆盖率报告并输出到项目coverage目录：

bash
docker run --rm -v $(pwd):/app -w /app stepchowfun/toast toast --coverage --coverage-reporter html

CI/CD集成示例（GitHub Actions）

在.github/workflows/test.yml中配置：

yaml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests with toast
        run: |
          docker run --rm -v $(pwd):/app -w /app stepchowfun/toast toast --reporter tap > test-results.tap
      - name: Upload test report
        uses: actions/upload-artifact@v3
        with:
          name: test-report
          path: test-results.tap

配置参数与环境变量

常用命令行参数

环境变量

自定义配置文件示例

创建toast.config.js自定义测试行为：

javascript
export default {
  testMatch: ['**/*.test.{js,ts}', '**/*.spec.{js,ts}'], // 测试文件匹配模式
  testIgnore: ['node_modules/**', 'dist/**'], // 排除文件
  reporter: 'tap', // 默认报告格式
  coverage: {
    include: ['src/**/*.{js,ts}'], // 覆盖率统计范围
    exclude: ['src/**/*.d.ts'], // 排除类型定义文件
    reporter: ['html', 'text-summary'] // 覆盖率报告格式
  }
};

使用自定义配置运行：

bash
docker run --rm -v $(pwd):/app -w /app stepchowfun/toast toast --config toast.config.js

注意事项

• 文件权限：挂载项目目录时，若遇权限问题，可通过--user $(id -u):$(id -g)指定当前用户ID：

  bash
  docker run --rm -v $(pwd):/app -w /app --user $(id -u):$(id -g) stepchowfun/toast toast
  

• 路径映射：确保容器工作目录（-w /app）与本地项目目录挂载路径一致，避免测试文件查找失败。
• TypeScript支持：无需额外安装TypeScript依赖，镜像内置TypeScript编译器，可直接运行.ts测试文件。