agoldis/sorry-cypress-dashboard

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. 查看测试并行运行 🚀

!https://s3.amazonaws.com/agoldis.dev/images/sorry-cypress/cypress.parallel.x2.3mb.gif

!https://s3.amazonaws.com/agoldis.dev/images/sorry-cypress/sorry-cypress-demo.gif

演示与示例

基于云的演示

访问 https://sorry-cypress-demo.herokuapp.com/ 查看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%AES3%E5%AD%98%E5%82%A8%E6%A1%B6%E5%90%8E%EF%BC%8C%E6%9B%BF%E6%8D%A2%60docker-compose.full.yml%60%E4%B8%AD%E7%9A%84%E5%87%AD%E6%8D%AE%E3%80%82

本地部署说明

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 或点击下方按钮 👇🏻

文档

重新配置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上运行的就是这种无状态执行模式，仅并行化测试，不持久化测试结果，也不上传失败测试的截图。

配置

服务使用https://www.npmjs.com/package/dotenv%E5%8C%85 - 要修改默认配置，在服务根目录创建.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种"执行驱动"：

无状态

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

这是最简单的实现方式。

适用于仅需并行运行测试，无需存储测试结果的场景。

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"

确保环境中存在具有调用https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html%E6%9D%83%E9%99%90%E7%9A%84https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html%E3%80%82

参见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

可在 https://sorry-cypress-demo.herokuapp.com/ 探索当前可用功能。

开发

项目使用https://yarnpkg.com/lang/en/docs/workspaces/%EF%BC%8C%E5%9C%A8%E6%A0%B9%E7%9B%AE%E5%BD%95%E8%BF%90%E8%A1%8C%60yarn%60%E5%88%9D%E5%A7%8B%E5%8C%96%E6%89%80%E6%9C%89%E5%86%85%E5%AE%B9%E3%80%82

在开发模式下运行每个包：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
• https://docs.cypress.io/guides/guides/parallelization.html
• https://github.com/agoldis/sorry-cypress/wiki/AWS-Multiple-Cypress-Agents 作者 https://github.com/mlsad3

许可证

MIT