retail-store-sample-app E2E 测试实战:Cypress 自动化验证完整购物流程指南
retail-store-sample-app E2E 测试实战:Cypress 自动化验证完整购物流程指南
retail-store-sample-app 是一个用于演示容器平台(Docker Compose、Kubernetes 等)的开源微服务商店应用。它的 src/e2e/ 目录内置了一套完整的 Cypress E2E 测试,可以把整个应用当作黑盒,自动化跑通"浏览商品 → 加入购物车 → 结算下单"的全流程。本文带你快速看懂这套 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 镜像
- 配置入口:cypress.config.js,只需一个
baseUrl指向 UI 服务即可 - 运行方式文档:src/e2e/README.md
- 测试镜像:Dockerfile.run 只有一行
FROM 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。
2️⃣ 商品目录测试(catalog.cy.js)
catalog.cy.js 是"加入购物车"场景的起点:
- 断言目录页恰好显示 6 张商品卡片,第一张是 "Aqua Ace GT"
- 点击第一张卡片的 Add to Cart 按钮后,购物车角标变为 1,且 URL 跳转到
/cart
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 查询(MySQLproducts表)应被打上 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 把整套应用部署到本地后跑一遍完整验证。


