agoldis/sorry-cypress-api

sorry-cypress

!https://github.com/agoldis/sorry-cypress/workflows/Update%20Dockerhub%20Images/badge.svg?event=push

目录

• 特性
• 设置
• 演示与示例
  • 基于云的演示
  • 本地运行演示（2 分钟）
• 本地部署说明
  • Docker 镜像
  • 🔥新! Heroku
  • 🔥新! Amazon AWS
• 文档
  • 重新配置 Cypress
  • 项目结构
  • director 服务
  • api 服务
  • dashboard 服务
• 开发
• 幕后原理
• 常见问题
• 其他资源
• 许可证

特性

• 无需官方仪表盘即可并行运行 Cypress 测试
• 将失败截图和视频上传至 S3 存储桶
• 浏览测试结果、失败记录、截图和视频录制
• 支持无持久化的轻量模式或附加 MongoDB 存储的模式
• 本地自托管 Cypress 仪表盘 - 使用自有基础设施，数据自主管理，无使用限制

设置

1. 将 Cypress 指向服务 - 在 <cypress-root>/packages/server/config/app.yml 中设置 api_url 为 https://sorry-cypress-demo-director.herokuapp.com/
2. 运行多个 cypress run --parallel --record --key xxx --ci-build-id <buildId> 实例
3. 查看测试并行运行 🚀

!并行运行 Cypress 测试演示

!Web 仪表盘原型

演示与示例

基于云的演示

访问 [***] 查看 Web 仪表盘 alpha 版本的实际效果。

此演示基于免费 Heroku 实例，首次访问时可能需要一分钟启动。

您可以重新配置 Cypress，将 api_url 设置为 "https://sorry-cypress-demo-director.herokuapp.com/"，运行测试后即可在仪表盘中查看结果。

也可参考https://github.com/agoldis/sorry-cypress/tree/master/example%E4%BA%86%E8%A7%A3%E5%B9%B6%E8%A1%8C%E5%8C%96%E7%9A%84%E8%AF%A6%E7%BB%86%E7%94%A8%E6%B3%95%E3%80%82

本地运行演示

1. 运行 docker-compose -f docker-compose.full.yml up
2. 在浏览器中打开 http://localhost:8080/ 查看仪表盘

这将在本地启动所有 3 个服务，

重新配置 Cypress，将 api_url 设置为 "http://localhost:1234/"，

运行测试 cypress run --parallel --record --key xxx --ci-build-id <buildId>，结果将显示在仪表盘中。这些 Cypress 测试将并行运行，无需连接官方仪表盘。

如需上传失败测试截图，需https://github.com/agoldis/sorry-cypress/wiki/S3-screenshot-bucket-setup-instructions%E3%80%82%E8%AE%BE%E7%BD%AE S3 存储桶后，替换 docker-compose.full.yml 中的凭据。

本地部署说明

Docker 镜像

每个包均包含 Dockerfile，可用于构建自定义镜像。

预构建 Docker 镜像可在 https://hub.docker.com/u/agoldis 获取。

Docker 镜像标签对应 Git 标签，latest 标签对应 master 分支。

参考 docker-compose.full.yml 获取配置示例。

Heroku

已迁移至 https://github.com/agoldis/sorry-cypress/wiki/Heroku-Tutorial

Amazon AWS

🎉 使用 AWS CloudFormation 模板，仅需 5 分钟即可在 AWS 上部署 sorry-cypress，获得完整功能版本，包括：

• 并行化
• GraphQL API
• Web 仪表盘
• 预配置用于存储截图和视频的 S3 存储桶
• 作为持久层的 MongoDB
• 通过 AWS VPC 实现的安全网络配置
• 通过 AWS CloudWatch 预配置的日志组
• 通过 AWS 负载均衡器实现的便捷访问

详见 https://github.com/agoldis/sorry-cypress/wiki/AWS-Tutorial%EF%BC%8C%E6%88%96%E7%9B%B4%E6%8E%A5%E7%82%B9%E5%87%BB%E4%B8%8B%E6%96%B9%E6%8C%89%E9%92%AE 👇🏻

![启动堆栈]([***]

文档

重新配置 Cypress

查找 Cypress 安装路径

bash
$ DEBUG=cypress:* cypress version

...
# 路径示例
cypress:cli Reading binary package.json from: /Users/agoldis/Library/Caches/Cypress/3.4.1/Cypress.app/Contents/Resources/app/package.json +0ms
...

示例路径：/Users/agoldis/Library/Caches/Cypress/3.4.1/Cypress.app/Contents/Resources/app/

修改默认仪表盘 URL

bash
$ cat /Users/agoldis/Library/Caches/Cypress/3.4.1/Cypress.app/Contents/Resources/app/packages/server/config/app.yml

...
# 替换为替代仪表盘的 URL
production:
  # api_url: "https://api.cypress.io/"
  api_url: "http://localhost:1234/"
...

项目结构

仓库包含 3 个可独立部署的包：

• packages/director - 负责并行化和保存测试结果的服务
• packages/api - 允许读取测试运行详情和结果的 GraphQL 服务器
• packages/dashboard - Web 仪表盘（ReactJS）

director 服务

director 服务负责：

• 测试运行的并行化与协调
• 保存测试结果
• 保存失败测试的截图

当在 CI 环境的多台机器上启动 Cypress 时，每台机器首先联系仪表盘获取下一个要运行的测试。仪表盘协调不同机器的请求并为每台机器分配测试。这正是 director 服务的功能 👆

启动服务

sh
cd packages/director

npm install
npm run build
npm run start

# ...

Initializing "in-memory" execution driver...
Initializing "dummy" screenshots driver...
Listening on 1234...

默认情况下，服务在端口 1234 启动，使用内存执行驱动和 dummy 快照驱动。

https://sorry-cypress.herokuapp.com 上运行的就是这种无状态执行模式，仅并行化测试，不持久化测试结果，也不上传失败测试的截图。

配置

服务使用 dotenv 包 - 要修改默认配置，在服务根目录创建 .env 文件设置环境变量：

sh
$ pwd
/Users/agoldis/sorry-cypress/packages/director

$ cat .env

PORT=1234

# DASHBOARD_URL 是 Cypress 客户端显示的"运行 URL"
DASHBOARD_URL="https://sorry-cypress.herokuapp.com"

# 执行驱动详情见下文
EXECUTION_DRIVER="../execution/in-memory"

# 截图驱动详情见下文
SCREENSHOTS_DRIVER="../screenshots/dummy.driver"

# 记录密钥白名单详情见下文
ALLOWED_KEYS="my_secret_key,my_another_secret_key"

驱动

director 使用"驱动"定义其不同功能方面。

执行驱动

...用于驱动执行流程。

已实现 2 种"执行驱动"：

无状态（in-memory）

在内存中保存运行状态。重启服务会清除所有数据。

这是最简单的实现方式。适用于仅需并行运行测试，无需存储测试结果的场景。

MongoDB 持久化

运行状态（测试运行和结果）持久化到 MongoDB，可通过查询在仪表盘中显示。

要启用此驱动，设置环境变量：

EXECUTION_DRIVER="../execution/mongo/driver"
MONGODB_URI="monodgb://your-DB-URI"
MONGODB_DATABASE="your-DB-name"

使用 MongoDB 驱动后，可通过 api 和 dashboard 服务查看运行结果。

快照驱动

...用于保存快照和测试视频。为客户端（Cypress 运行器）提供资产（视频和截图）的上传 URL。

Dummy

默认驱动，不执行任何操作 - 快照不会保存。

设置环境变量定义截图驱动：

SCREENSHOTS_DRIVER="../screenshots/dummy.driver"

S3 驱动

生成 S3 存储桶的上传 URL。相应设置环境变量：

SCREENSHOTS_DRIVER="../screenshots/s3.driver"
S3_BUCKET="your_bucket_name"
S3_REGION="us-east-1"

确保环境中存在具有调用 s3.getSignedUrl 权限的 AWS 凭据。

参考 wiki 页面了解https://github.com/agoldis/sorry-cypress/wiki/S3-screenshot-bucket-setup-instructions%E3%80%82

记录密钥白名单

设置 ALLOWED_KEYS 变量可定义逗号分隔的记录密钥列表（通过 --key 选项提供给 Cypress 运行器），director 服务仅接受这些密钥。当 Cypress 在外部 CI 服务器上运行且需将 director 暴露到互联网时，此功能非常有用。

变量为空或未设置时，允许所有记录密钥。

ALLOWED_KEYS="my_secret_key"

api 服务

...是一个简单的 GraphQL 服务，允许查询 MongoDB 中持久化的数据。

设置定义 MongoDB 连接详情的环境变量：

MONGODB_URI='mongodb://mongo:27017'
MONGODB_DATABASE='sorry-cypress'

dashboard 服务

...是基于 ReactJS 实现的 Web 仪表盘，目前处于 alpha 阶段，功能较基础 - 可浏览测试详情、失败记录和查看截图。

生产模式下需提供环境变量 GRAPHQL_SCHEMA_URL - GraphQL 客户端将使用该 URL 下载模式。

设置定义获取模式的 URL 的环境变量：

GRAPHQL_SCHEMA_URL=https://sorry-cypress-demo-api.herokuapp.com

可在 [***] 探索当前可用功能。

开发

项目使用 yarn workspaces，在根目录运行 yarn 引导所有依赖。

在开发模式下运行每个包：yarn dev。

建议使用 docker-compose 运行后端服务（director 和 api），在主机上运行 dashboard。

使用 docker-compose 运行后端服务

项目使用 docker-compose 便捷地在容器中运行后端服务。

从项目根目录运行 docker-compose build 运行 docker-compose up 启动服务。

上述命令将创建 3 个服务：

• 端口 27017 上的 MongoDB 实例
• 端口 1234 上的 director 服务
• 端口 4000 上的 api 服务

可通过 docker-compose.yml 文件中定义的环境变量修改配置。

幕后原理

1. 每台机器发送包含以下内容的初始请求：

• 测试规范列表
• 机器硬件详情
• Git 提交详情
• --ci-build-id 和其他 CLI 参数

2. director 基于参数创建或获取现有 run，返回随机生成的 machineId 和分配的 runId

3. 每个 Cypress 客户端请求先前返回的 runId 的下一个可用任务

4. 服务查看测试规范列表并返回下一个可用测试

官方 Cypress 仪表盘实现了不同的"智能"策略来选择下一个测试

5. 当运行中没有更多可用测试时，服务返回"空"响应 - 客户端报告完成

常见问题

为什么开发此项目？

我开发此项目是因为：

• 官方仪表盘崩溃导致测试受阻
• 付费计划达到限制后并行化停止工作

是否合法？

是的，Cypress 是https://github.com/cypress-io/cypress/blob/develop/LICENSE%E3%80%82

是否生产就绪？

是的。

其他资源

• https://github.com/agoldis/sorry-cypress/wiki
• Cypress 并行化官方指南
• https://github.com/agoldis/sorry-cypress/wiki/AWS-Multiple-Cypress-Agents 作者 https://github.com/mlsad3

许可证

MIT