本计划用于为“海外历史用户迁移到国内主站”能力补齐完整的 E2E 测试体系。目标不是补几条临时脚本,而是形成一套可以本地稳定复跑、能定位失败原因、后续可接 CI 的测试资产。
本计划覆盖四个层面:
| 项目 | 现状 |
|---|---|
| 浏览器 E2E 框架 | 仓库内暂无 Playwright/Cypress |
| 现有 E2E 风格 | 只有零散的 test/e2e_*.go、test/e2e_*.py |
| 迁移相关单测/集成测 | 已较完整,service/user_migration/service_test.go 已覆盖主链路 |
| 自动初始化 | 已支持 POST /api/setup 创建 root |
| 自动登录 | 已支持 POST /api/user/login |
| region_sync 配置 | 走 root option API 写入数据库 |
| CI 工作流 | 当前 worktree 下未见 .github/workflows/ |
现成 test/e2e/ 目录 |
尚未建立 |
以下约定在第一版中固定,不在实施过程中反复修改:
| 项目 | 固定值 |
|---|---|
| CN 节点端口 | 3100 |
| OV 节点端口 | 3101 |
| CN 数据库 | test-artifacts/user-migration-e2e/cn.db |
| OV 数据库 | test-artifacts/user-migration-e2e/ov.db |
| 产物目录 | test-artifacts/user-migration-e2e/ |
| CN session 名 | cn_session |
| OV session 名 | ov_session |
| Sync API Key | e2e-sync-key |
| 第一版运行方式 | 双进程 + 双 SQLite,不先上 Docker |
| 第一版 UI 覆盖 | Playwright smoke,不做重业务断言 |
本计划明确不做以下事情:
本计划完成后,仓库中应至少新增以下内容:
test/e2e/ Go API 黑盒 E2Etest/e2e/helpers/ 编排、登录、配置、seed、断言 helperweb/e2e/ Playwright UI smoke 测试web/playwright.config.tsscripts/run-user-migration-e2e.ps1test-artifacts/user-migration-e2e/.gitignoredocs/testing/user-migration-e2e.md严格按以下顺序推进,避免返工:
目标:锁定实现边界,避免中途改架构。
任务
验收
目标:先把结构搭起来。
文件
test/e2e/test/e2e/helpers/web/e2e/test-artifacts/user-migration-e2e/.gitignoredocs/testing/user-migration-e2e.md任务
验收
建议提交
chore(e2e): scaffold user migration e2e directories目标:自动拉起 cn 和 ov 两个真实后端实例。
文件
test/e2e/helpers/cluster.go任务
强制环境变量
PORTSQLITE_PATHSESSION_SECRETSESSION_NAMESESSION_SECURE=falseSESSION_SAMESITE=laxGLOBAL_API_RATE_LIMIT_ENABLE=falseGLOBAL_WEB_RATE_LIMIT_ENABLE=falseCRITICAL_RATE_LIMIT_ENABLE=falseGIN_MODE=release节点差异
NODE_TYPE=masterNODE_TYPE=slave验收
3100 和 3101 均能返回 /api/status建议提交
test(e2e): add dual-node cluster runner for migration tests目标:封装请求、会话、root 初始化和登录。
文件
test/e2e/helpers/http_client.gotest/e2e/helpers/auth.go任务
验收
POST /api/setup 自动创建 rootPOST /api/user/login 自动拿到会话建议提交
test(e2e): add setup and session helpers for migration tests目标:通过 root option API 配好双节点联通。
文件
test/e2e/helpers/options.go任务
需要写入的配置
CN 侧:
region_sync.enabled = trueregion_sync.region_id = "cn"region_sync.is_master = trueregion_sync.master_endpoint = "http://127.0.0.1:3100"region_sync.slave_endpoints = ["http://127.0.0.1:3101"]region_sync.sync_api_key = "e2e-sync-key"OV 侧:
region_sync.enabled = trueregion_sync.region_id = "ov"region_sync.is_master = falseregion_sync.master_endpoint = "http://127.0.0.1:3100"region_sync.slave_endpoints = []region_sync.sync_api_key = "e2e-sync-key"注意
slave_endpoints 通过 JSON 字符串写入,不要直接写 Go slice 的字符串表示验收
建议提交
test(e2e): add region sync configuration helpers目标:每次测试从固定数据出发,结果稳定。
文件
test/e2e/helpers/seed.go任务
固定数据集
CN:
cn-merge-targetcn-synced-copy-ownertaken-usernameaff-ownerOV:
ov-createov-mergeov-hard-syncedov-username-conflictov-aff-soft额外:
source=synced 用户,remote_user_id 指向 cn-synced-copy-owner验收
建议提交
test(e2e): add migration seed data for cn and ov nodes目标:把复杂轮询和 DB 断言收敛到 helper,主测试保持清晰。
文件
test/e2e/helpers/assert.go任务
验收
建议提交
test(e2e): add assertion helpers for migration flow目标:建立统一生命周期和测试入口。
文件
test/e2e/user_migration_test.go任务
建议
验收
建议提交
test(e2e): add user migration test main lifecycle目标:先证明迁移全链路真实可用。
文件
test/e2e/user_migration_test.go必须实现的用例
FullFlow_GrayScenarios 覆盖点
scanresolveexecuteverifysource=syncedremote_user_idsynced_quota == cn.quota验收命令
go test -v ./test/e2e -run TestUserMigrationE2E_FullFlow_GrayScenarios -count=1go test -v ./test/e2e -run TestUserMigrationE2E_IdempotentRetry -count=1go test -v ./test/e2e -run TestUserMigrationE2E_ExecutionTimeDriftFails -count=1建议提交
test(e2e): add core migration flow tests目标:补齐重扫、分页、权限、异常输入等场景。
文件
test/e2e/user_migration_test.go必须实现的用例
验收命令
go test -v ./test/e2e -count=1建议提交
test(e2e): add migration edge case coverage目标:搭 UI smoke 运行底座。
文件
web/playwright.config.tsweb/e2e/global-setup.tsweb/e2e/global-teardown.tsweb/e2e/fixtures/cluster.ts任务
验收
cd web && bunx playwright test --list 可正常执行建议提交
test(ui): add playwright infrastructure for migration smoke tests目标:验证 root 迁移中心页面真正可用。
文件
web/e2e/user-migration.spec.tsweb/src/components/table/users/migration/*(如需补 data-testid)必须实现的用例
规则
验收
cd web && bunx playwright test建议提交
test(ui): add migration center smoke tests目标:本地单命令跑完全部 E2E。
文件
scripts/run-user-migration-e2e.ps1任务
验收
建议提交
chore(e2e): add user migration e2e runner目标:让别人能跑、能排查、能扩展。
文件
docs/testing/user-migration-e2e.md任务
验收
建议提交
docs(e2e): document user migration end-to-end tests目标:确认新增 E2E 不破坏现有代码。
必须执行
验收
目标:将 E2E 纳入自动化执行。
说明
当前仓库中尚未看到 .github/workflows/,本阶段默认后置,不作为本轮硬性前置条件。
任务
验收
如果要立即开始实施,正式开工前只需要做这些最小动作:
确认完后,直接从阶段 1开始执行,不需要额外准备。
只有同时满足以下条件,才算该 E2E 计划完成:
test/e2e API E2E 可稳定运行web/e2e UI smoke 可稳定运行go test ./... 通过cd web && bun run build 通过