Testing

受众：开发者 摘要：测试规范：JUnit / AssertJ / Mockito / Spring Boot Test / Testcontainers + 默认 skipITs。

本文档记录项目常用验证方式。新增功能、修复缺陷或调整配置后，应选择和改动范围匹配的验证命令。

基础命令

运行应用聚合测试：

./mvnw -pl spring-open-application -am test -DskipITs

运行单个模块及依赖模块测试：

./mvnw -pl spring-open-starters/spring-open-starter-cache -am test -DskipITs

文档或格式检查：

git diff --check

推荐验证范围

改动类型	推荐命令
单个 starter Java 代码	./mvnw -pl <starter> -am test -DskipITs
IAM / Auth / 用户 / RBAC 后台代码	./mvnw -pl spring-open-core/spring-open-core-iam -am test -DskipITs
Config / Knowledge / Plugin 等 core 管理面	./mvnw -pl spring-open-core/spring-open-core-<module> -am test -DskipITs
application 装配或依赖	./mvnw -pl spring-open-application -am test -DskipITs
文档 only	git diff --check
Liquibase 迁移	对应模块测试 + 应用装配测试
依赖漏洞收口	dependency:tree + 相关模块测试

测试账号

项目没有固定默认测试账号，也不建议在文档、脚本或种子数据中沉淀固定账号密码。

推荐测试方式：

• 后台管理员：首次安装时通过安装向导创建首个超级管理员；项目只保留 Install 受控管理员初始化入口，不再提供平行初始化 API。不使用安装模块的应用装配需要自行提供受控的部署期初始化流程或预置管理员数据。
• 普通用户：通过账号密码注册、短信 / 邮箱验证码注册、OAuth / Telegram / 钱包等外部身份登录创建。
• 自动化测试：优先在测试用例内部构造用户、角色、权限和 token，不依赖运行环境里预置的固定账号。
• 前端本地样例填充按钮只用于快速填表，不代表框架内置凭据；生产环境应关闭。

Clean Test

跨模块常量、公共 API 或依赖管理变化后，建议执行 clean test：

./mvnw -pl spring-open-modules/spring-open-module-open-platform -am clean test -DskipITs

clean test 会重新编译依赖模块，更容易发现 IDE 或增量编译没有暴露的问题。

测试报告清理

父 POM 会在每次进入 test 前自动清理当前模块的 target/surefire-reports 和 target/failsafe-reports，避免定向重跑或类加载失败时残留上一轮报告干扰判断。

普通命令不需要手动删除报告目录：

./mvnw -pl spring-open-core/spring-open-core-iam -am test -DskipITs
./mvnw -pl spring-open-core/spring-open-core-iam -am -Dtest=DefaultWorkspaceManagerTest test -DskipITs

只有直接调用 Surefire / Failsafe 插件 goal、绕过 Maven 生命周期时，才需要先手动清理对应报告目录。

Web3 RPC Smoke

Web3 真实节点不放进默认单元测试，避免公共 RPC 波动影响普通开发。需要上线前验证节点时，直接用 JSON-RPC 只读请求检查链 ID 和区块高度：

RPC_URL="https://bsc-dataseed.bnbchain.org"

curl -fsS -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}' \
  "$RPC_URL"

curl -fsS -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' \
  "$RPC_URL"

这两个请求不会签名或广播交易。更多说明见 Web3 生产联调。

依赖树检查

检查某个依赖是否仍然进入运行时：

./mvnw -pl spring-open-application -am dependency:tree -Dincludes=org.dom4j:dom4j -DskipTests

支付、Web3、Storage、SMS 等第三方生态依赖升级后，应同时检查 starter 和 application 聚合依赖树。

Docker Smoke

基础环境：

docker compose -f docker/docker-compose.yml up -d

PostgreSQL：

docker compose -f docker/docker-compose.yml --profile postgres up -d postgres redis

容器级 smoke 适合验证：

• Liquibase 在 MySQL / PostgreSQL 下是否可执行。
• Config database provider 是否可读写。
• Scheduler / Queue 是否能连接基础设施。
• Redis / Redisson 相关能力是否正常。

隔离启动 Smoke

普通开发和发布前联调不推荐使用 lite。只有在需要隔离诊断应用装配、验证单进程兼容性，且明确不覆盖真实 MySQL / Redis 行为时，才使用 lite：

SPRING_PROFILES_ACTIVE=lite ./mvnw -pl spring-open-application spring-boot:run

或打包后：

SPRING_PROFILES_ACTIVE=lite java -jar spring-open-application.jar

lite 会使用 H2 文件数据库、file cache、memory queue 和 memory scheduler，因此不能代表默认开发环境、生产部署或多实例行为。

Browser E2E Smoke

浏览器 smoke 使用 Playwright，默认巡检已经启动的 SpringOpen 应用：

pnpm -C views/admin test:e2e

默认目标是 http://localhost:8000，未启动应用时默认跳过；发布前或 CI 应先启动 dev 应用并连接真实基础设施，再设置 SPRING_OPEN_E2E_REQUIRED=true 强制执行。只有隔离诊断单进程装配时才考虑 lite。账号和入口来自环境变量：

环境变量	默认值	说明
SPRING_OPEN_E2E_BASE_URL	http://localhost:8000	应用 base URL
SPRING_OPEN_E2E_READY_URL	Admin 入口 URL	就绪探测 URL，可改成 /actuator/health
SPRING_OPEN_E2E_REQUIRED	false	true 时就绪探测失败直接失败；默认未启动应用时跳过
SPRING_OPEN_E2E_ADMIN_PATH	/admin/	Admin 入口路径
SPRING_OPEN_E2E_ADMIN_USERNAME	admin	管理员账号
SPRING_OPEN_E2E_ADMIN_PASSWORD	123456	管理员密码，仅用于本地受控环境
SPRING_OPEN_E2E_INSTALL_PATH	/install/	安装向导入口
SPRING_OPEN_E2E_APP_PATH	/app/	App H5 入口
SPRING_OPEN_E2E_APP_HOME_PATH	/app/#/pages/home/index	App 首页路由 smoke
SPRING_OPEN_E2E_APP_MALL_PATH	/app/#/pages/mall/index	App 商城入口 smoke
SPRING_OPEN_E2E_APP_POINTS_PATH	/app/#/member/points	App 会员积分入口 smoke；设为空字符串可跳过
SPRING_OPEN_E2E_APP_CASHIER_PATH	/app/#/cashier/index	App 收银台入口 smoke；设为空字符串可跳过
SPRING_OPEN_E2E_APP_WALLET_PATH	/app/#/wallet/index	App 钱包 / Web3 入口 smoke；设为空字符串可跳过
SPRING_OPEN_E2E_APP_OPEN_PLATFORM_PATH	/app/#/open-platform/index	App 开放平台入口 smoke；设为空字符串可跳过
SPRING_OPEN_E2E_APP_KNOWLEDGE_PATH	/app/#/pages/knowledge/index	App 知识库入口 smoke；设为空字符串可跳过
SPRING_OPEN_E2E_PC_PATH	/pc/	PC 用户端入口
SPRING_OPEN_E2E_PC_MALL_PATH	/pc/mall	PC 商城入口 smoke
SPRING_OPEN_E2E_PC_MALL_CHECKOUT_PATH	/pc/mall/checkout	PC 商城结算入口 smoke；设为空字符串可跳过
SPRING_OPEN_E2E_PC_CASHIER_PATH	/pc/cashier	PC 收银台入口 smoke
SPRING_OPEN_E2E_PC_POINTS_PATH	空	PC 会员积分入口 smoke；默认跳过，发布环境已准备登录态 / 深层静态路径时可显式设置为 /pc/account/points
SPRING_OPEN_E2E_PC_OPEN_PLATFORM_PATH	空	PC 开放平台用户控制台入口 smoke；默认跳过，发布环境已准备登录态 / 深层静态路径时可显式设置为 /pc/account/open-platform
SPRING_OPEN_E2E_PC_PAYMENT_PLATFORM_PATH	空	PC 聚合支付商户控制台入口 smoke；默认跳过，发布环境已准备登录态 / 深层静态路径时可显式设置为 /pc/account/payment-platform
SPRING_OPEN_E2E_PC_KNOWLEDGE_PATH	/pc/knowledge	PC 知识库入口 smoke
SPRING_OPEN_E2E_DOCS_PATH	/docs/	文档站入口
SPRING_OPEN_E2E_ADMIN_MALL_PRODUCTS_ROUTE	#/mall/products	Admin 商城商品控制台 route；设为空字符串可跳过
SPRING_OPEN_E2E_ADMIN_MALL_ORDERS_ROUTE	#/mall/orders	Admin 商城订单控制台 route；设为空字符串可跳过
SPRING_OPEN_E2E_ADMIN_MONEY_ROUTE	#/money	Admin 资金账户控制台 route；设为空字符串可跳过
SPRING_OPEN_E2E_ADMIN_AI_PLATFORM_ROUTE	#/ai/platform	Admin AI 平台控制台 route；设为空字符串可跳过
SPRING_OPEN_E2E_ADMIN_OPEN_PLATFORM_ROUTE	#/open-platform	Admin 开放平台控制台 route；设为空字符串可跳过
SPRING_OPEN_E2E_ADMIN_PAYMENT_PLATFORM_ROUTE	#/payment-platform	Admin 聚合支付控制台 route；设为空字符串可跳过
SPRING_OPEN_E2E_ADMIN_WEB3_CHAIN_ROUTE	#/web3/chains	Admin Web3 链控制台 route；设为空字符串可跳过
SPRING_OPEN_E2E_ADMIN_KNOWLEDGE_ROUTE	#/knowledge	Admin Knowledge 控制台 route；设为空字符串可跳过

该 smoke 包含三类检查：

• Admin 登录 smoke：登录后台并巡检首页、配置、IAM 用户、Queue 和 Scheduler 等核心入口。
• 多端入口 smoke：巡检 Install、App、PC 和 Docs 的发布入口，以及 App 首页 / 商城、PC 商城 / 收银台 / 知识库等只读入口。
• 业务金路径浏览器 smoke：覆盖 Mall、Cashier、会员积分、Open Platform、Payment Platform、AI、Web3 和 Knowledge 的 App / PC / Admin 关键入口，捕获路由渲染、控制台错误、网络失败和 5xx 响应。

这些 smoke 都会记录 console error、page error、网络失败和 HTTP 5xx 响应到 Playwright attachment；多端入口和业务金路径 smoke 会把入口 HTTP 4xx 视为发布入口缺失。顺序导航导致的 net::ERR_ABORTED 和 PC 相对路径静态输出的固定 hydration mismatch 视为非致命浏览器诊断，不阻断 smoke。它们只覆盖可重复的浏览器渲染、路由和网络错误，不替代真实第三方 Provider、真实支付、真实 Web3 签名 / 广播或真实 AI 上游验收。

发布前人工验收清单：

1. 干净库安装：从 /install/ 完成首个管理员创建，确认再次访问安装入口会进入已安装态。
2. Admin：用超管登录，检查配置、IAM、Queue、Scheduler、Feature Flag、AI、支付、Web3、微信等本次涉及菜单。
3. PC：完成注册或登录，打开商城列表、商品详情、结算页、收银台、支付结果、知识库问答和用户中心。
4. App H5：完成注册或登录，打开首页、商城、订单、收银台、聊天、通知和个人中心。
5. 支付 Provider：使用沙箱或受控测试商户完成下单、支付、回调、补偿查询和退款，不在公开 CI 暴露真实密钥。
6. Web3：在注入钱包浏览器里验证连接、报价、用户拒签、链不匹配和交易提交降级提示；自动 smoke 不签名、不广播交易。
7. AI / 知识库：用测试 Key 验证 Chat、Stream、模型目录、知识库问答和失败提示。
8. Docs：检查 /docs/、核心模块文档和本次变更文档深链，确认没有 404、重复语言前缀或资源路径问题。

常见警告

当前项目在较新 JDK 下可能出现 Lombok、Mockito 动态 agent 或 Spring 过时 API 警告。只要测试通过，这类警告不等同于失败。

如果警告来自安全漏洞、即将删除的核心 API 或生产运行风险，应单独创建任务处理。