retail-store-sample-app E2E 测试实战:Cypress 自动化验证完整购物流程指南

原创2026-11-15 22:06:542,126 阅读

retail-store-sample-app E2E 测试实战:Cypress 自动化验证完整购物流程指南

retail-store-sample-app 是一个用于演示容器平台(Docker Compose、Kubernetes 等)的开源微服务商店应用。它的 src/e2e/ 目录内置了一套完整的 Cypress E2E 测试,可以把整个应用当作黑盒,自动化跑通"浏览商品 → 加入购物车 → 结算下单"的全流程。本文带你快速看懂这套 E2E 测试如何编写、如何一键运行,适合刚接触前端自动化测试的新手。

retail-store-sample-app 商店首页 E2E 测试被测界面

💡 上面的商店首页,就是 E2E 测试的"起点":home.cy.js 第一个断言就是检查页面上的 Shop Now 按钮是否可见。

一、E2E 测试在仓库中的位置

整套测试位于 src/e2e/ 目录,核心结构如下:

src/e2e/
├── cypress/
│   ├── e2e/          # 5 个测试脚本(home/catalog/cart/checkout/search)
│   ├── pages/        # 页面对象模型(Page Object Model)
│   └── support/      # 全局配置与自定义命令
├── scripts/
│   ├── run-docker.sh # 用 Docker 容器化运行测试
│   └── assert-traces.sh # 验证分布式追踪(Jaeger)
├── cypress.config.js # Cypress 配置(默认 baseUrl 为 http://localhost:8080)
└── Dockerfile.run    # 基于 cypress/included:13.17.0 镜像

二、一键运行 E2E 测试:最快配置方法

运行前需要先用 Docker Compose 或 Kubernetes 把商店应用跑起来(参考 docs/features.md),然后从下面三种方式任选其一:

方式 1:Docker 容器运行(官方推荐)

# 指向你的 UI 服务地址
./scripts/run-docker.sh 'http://endpoint:8080'

# 针对本地 Docker Compose 部署(自动接入 docker-compose 网络)
./scripts/e2e-compose.sh

该脚本会自动构建镜像并注入 CYPRESS_BASE_URL 环境变量,实现见 run-docker.sh;针对 kind 集群还有一个 e2e-kind.sh 脚本。

方式 2:Yarn 本地运行

需要 NodeJS ≥ 20 和 Yarn:

cd src/e2e
yarn
CYPRESS_BASE_URL='http://endpoint:8080' yarn cypress run

小技巧:用 -s 开关启用搜索测试

搜索功能依赖 OpenSearch,默认关闭。加 -s 参数(或设置 SEARCH_ENABLED)后,搜索相关用例才会执行:

./scripts/e2e-compose.sh -s

三、完整购物流程:5 个测试脚本逐一拆解

5 个 spec 文件正好覆盖了用户的完整购物旅程,下面按购物路径顺序讲解。

1️⃣ 首页导航测试(home.cy.js)

home.cy.js 验证了 3 件事:首页 Shop Now 按钮可见、点击 Home 菜单留在首页、点击 Gadget Repository 菜单跳转到 /catalog。

商店首页 Hero 背景图(E2E 测试被测页面背景)

2️⃣ 商品目录测试(catalog.cy.js)

catalog.cy.js 是"加入购物车"场景的起点:

  • 断言目录页恰好显示 6 张商品卡片,第一张是 "Aqua Ace GT"
  • 点击第一张卡片的 Add to Cart 按钮后,购物车角标变为 1,且 URL 跳转到 /cart

The Quiet Quill 商品图(E2E 购物车测试使用的商品)

3️⃣ 购物车测试(cart.cy.js)

cart.cy.js 使用固定商品 "The Quiet Quill"(商品 ID d27cf49f-b689-4a75-a249-d373e0330bb5,就是上图这支钢笔)验证:

  • 购物车中只有 1 件商品,小计显示 $150
  • 点击 Checkout 按钮后跳转到 /checkout 页面

4️⃣ 结算下单测试(checkout.cy.js)

这是流程中最"硬核"的一组用例,checkout.cy.js 分两个场景:

场景 商品 小计 运费 税费 总额
单品下单 The Quiet Quill $150 $10 $5 $165
多品下单 2 件商品 $360 $10 $5 $375

测试会连续 3 次提交结算表单(地址 → 配送 → 支付),最终断言订单确认页的各项金额完全正确。这背后串联了 checkout(NestJS)→ orders(Java)→ PostgreSQL/RabbitMQ 整条微服务链路。

5️⃣ 搜索测试(search.cy.js)

search.cy.js 是最"聪明"的一组:

  • 搜索功能未启用时,断言搜索框不显示(反向验证)
  • 启用后,输入 shoe 应返回结果并显示 "products found"
  • 输入乱码 xyznonexistent123 应显示 "No gadgets found"
  • 点击 Clear 可清空搜索回到目录页

四、为什么易维护:Page Object 设计模式

测试代码之所以这么简洁,是因为 cypress/pages/ 目录采用了 页面对象模型(POM)。基类 Page.js 定义了通用的 visit() 和导航菜单方法,每个页面类只声明自己关心的元素选择器:

  • Catalog.js → 商品卡片 .product-card
  • Cart.js → 购物车项、小计、结算按钮
  • CheckoutOrder.js → 订单页的金额元素(#order-total 等)
  • Product.js → 通过商品 ID 直接访问商品详情页

页面结构变了?只需改 pages 目录,5 个测试脚本一行不动。这是 Cypress 项目保持可维护性的关键。

五、加分项:连分布式追踪一起验证

除了 UI 行为,仓库还提供 assert-traces.sh 脚本,通过 Jaeger API 断言关键链路的 trace 数据:

  • 访问 /catalog 时,catalog 服务的 SQL 查询(MySQL products 表)应被打上 trace
  • 购物车读取应出现 DynamoDB 查询 span
  • 结算时 checkout 会话写入 Redis 的 span 应可见

这让 E2E 测试从"功能正确"延伸到"可观测性正确",是容器平台演示项目的一大亮点。

六、小结

  • 🚀 运行:./scripts/e2e-compose.sh 一条命令搞定,测试跑在 cypress/included 无头容器里
  • 🛒 覆盖:首页导航 → 目录 → 购物车 → 结算下单 → 搜索,5 个 spec 串起完整购物旅程
  • 🧱 架构:Page Object 模式让测试代码与页面细节解耦
  • 📊 进阶:assert-traces.sh 还能验证 OpenTelemetry 分布式追踪链路

如果你想继续深入,可以阅读 src/e2e/README.md 了解参数细节,或参考 DEVELOPER_GUIDE.md 把整套应用部署到本地后跑一遍完整验证。

登录后查看全文
retail-store-sample-app