ovos/custom-cypress-docker-image

自定义Cypress Docker镜像文档

1. 镜像概述和主要用途

本镜像为自定义Cypress前端测试工具的Docker封装，旨在解决前端自动化测试环境配置复杂、跨环境依赖冲突等问题。通过预集成Cypress核心组件、Node.js运行环境及浏览器依赖，提供开箱即用的测试环境，确保开发、测试、CI/CD等不同场景下测试执行的一致性，大幅降低环境配置成本。

2. 核心功能和特性

• 预配置测试环境：内置Cypress最新稳定版、Node.js（LTS版本）及Chrome/Firefox浏览器，无需手动安装依赖
• 环境一致性保障：容器化封装避免"在我电脑上能运行"问题，确保测试结果跨环境一致
• 灵活定制能力：支持通过挂载配置文件（如cypress.json）、环境变量覆盖默认配置
• 多浏览器支持：默认集成Chrome和Firefox，可通过参数指定测试浏览器类型
• 轻量级设计：基于Alpine或Debian Slim基础镜像，平衡功能与镜像体积
• CI/CD友好：支持非交互模式运行，易于集成到Jenkins、GitHub Actions等CI/CD平台

3. 使用场景和适用范围

适用场景

• 前端项目端到端（E2E）自动化测试
• CI/CD流水线中的自动化测试环节（如提交代码后自动执行测试）
• 开发环境本地测试验证（无需在本地安装完整Cypress环境）
• 跨团队协作时的测试环境标准化
• 测试脚本兼容性验证（在统一环境中验证不同版本测试脚本）

适用范围

• 基于React、Vue、Angular等主流前端框架的项目
• 需要执行端到端测试、组件测试的前端应用
• 追求测试流程自动化、标准化的开发/测试团队

4. 使用方法和配置说明

4.1 前置条件

• 已安装Docker Engine（20.10+版本）
• 本地项目中已创建Cypress测试目录（通常为cypress/）及配置文件（cypress.json或cypress.config.js）

4.2 获取镜像

从镜像仓库拉取（如私有仓库或Docker Hub）：

bash
docker pull [镜像仓库地址]/custom-cypress-docker-image:latest

（若未推送至仓库，可本地构建：docker build -t custom-cypress-docker-image .）

4.3 基本使用示例

4.3.1 本地运行测试（Docker Run）

挂载本地测试文件并执行测试：

bash
docker run -it --rm \
  -v $(pwd)/cypress:/app/cypress \          # 挂载测试用例目录
  -v $(pwd)/cypress.json:/app/cypress.json \  # 挂载Cypress配置文件
  -e CYPRESS_BASE_URL="https://example.com" \ # 设置测试基础URL
  custom-cypress-docker-image \
  cypress run --browser chrome               # 执行测试命令（指定Chrome浏览器）

4.3.2 集成到Docker Compose

创建docker-compose.yml：

yaml
version: '3.8'
services:
  cypress-test:
    image: custom-cypress-docker-image:latest
    volumes:
      - ./cypress:/app/cypress           # 挂载测试用例
      - ./cypress.config.js:/app/cypress.config.js  # 挂载现代Cypress配置文件
      - ./package.json:/app/package.json  # 如需依赖项目package.json中的scripts
    environment:
      - CYPRESS_BASE_URL=https://your-app.com  # 应用基础URL
      - CYPRESS_BROWSER=firefox               # 指定Firefox浏览器
      - CYPRESS_VIDEO=false                   # 禁用测试视频录制
      - CYPRESS_RECORD_KEY=your_record_key   # （可选）Cypress Dashboard录制密钥
    command: cypress run --spec "cypress/e2e/login.cy.js"  # 执行指定测试文件

启动测试：

bash
docker-compose run cypress-test

4.4 关键配置说明

4.4.1 挂载目录说明

4.4.2 环境变量

4.5 高级用法：自定义测试命令

通过覆盖容器启动命令，执行特定Cypress命令：

bash
# 打开Cypress图形化界面（需启用交互模式）
docker run -it --rm -v $(pwd)/cypress:/app/cypress -p 6100:6100 custom-cypress-docker-image cypress open

# 仅运行指定测试文件
docker run -v $(pwd)/cypress:/app/cypress custom-cypress-docker-image cypress run --spec "cypress/e2e/checkout.cy.js"

# 运行测试并生成JUnit报告
docker run -v $(pwd)/reports:/app/reports custom-cypress-docker-image cypress run --reporter junit --reporter-options "mochaFile=reports/results.xml"

5. 注意事项

• 首次运行时，Cypress可能需要下载浏览器二进制文件（根据网络环境可能耗时较长）
• 挂载目录权限问题：确保本地目录对Docker进程有读权限，避免权限拒绝错误
• CI/CD环境中建议使用--headless模式运行（Cypress默认行为），减少资源占用
• 如需扩展依赖，可基于本镜像创建新Dockerfile（FROM custom-cypress-docker-image）并添加额外安装命令