XuqmGroup 19e7b27d6e docs(test): 更新测试报告和文档

- 更新发布版本从 0.1.0-SNAPSHOT 到 0.4.0
- 更新 README.md 中的依赖版本引用
- 完善 TEST_REPORT.md 包括最新测试结果和新增测试用例
- 添加详细的 TEST_PLAN.md 文档
- 更新 sample-app 的测试配置和依赖
- 为各个 SDK 模块添加 ProGuard 规则文件
- 修复 ApiClient 中的 Gson 类型适配器问题
- 改进测试架构，解决会话删除和跨设备测试问题

2026-05-05 16:06:32 +08:00

21 KiB

原始文件 Blame 文件历史

XuqmGroup Android SDK 集成测试计划

文档版本: v2.0
适用版本: SDK 0.4.x（UserSig 鉴权体系）
编写日期: 2026-05-04
维护者: AI Agent（可由任意智能体无缝接续）

一、文档目的

本文档描述 XuqmGroup Android SDK 的完整集成测试方案，覆盖以下目标：

验证 SDK 核心功能（初始化、登录、IM、Push、Update）端到端正确性
提供可供 AI Agent 无缝衔接执行的标准化操作步骤
定义自动化与手工测试的边界，明确每项用例的执行方式

二、测试范围

2.1 模块覆盖

模块	Gradle 模块	测试类型
核心（初始化/登录/登出）	`:sdk-core`	自动化 + 手工
IM 消息（单聊/群聊/会话）	`:sdk-im`	自动化 + 手工
Push（设备注册/厂商检测）	`:sdk-push`	自动化（模拟器）
Update（版本检查/下载）	`:sdk-update`	自动化 + 手工
Sample App 端到端 UI	`:sample-app`	手工

2.2 测试类型定义

类型	说明	工具
自动化集成测试	在真实后端上执行，无 Mock	AndroidJUnit4 Instrumented Test
手工验证	需人工观察 UI 或硬件行为	肉眼 / Logcat
Agent 测试	由 AI Agent 通过 adb/Gradle 自动执行	Claude Code + adb shell

三、测试环境

3.1 硬件 / 软件环境

项目	配置
操作系统	macOS Sequoia 15.x
Android SDK	`/Users/xuqinmin/Library/Android/sdk`
AGP	9.1.0
Gradle	8.9（Wrapper）
JDK	OpenJDK 21
Kotlin	2.3.10
compileSdk / targetSdk	36
minSdk	24（Android 7.0）

3.2 模拟器配置

标识	AVD 名称	端口	角色
emulator-5554	Pixel_9_Pro	5554	主设备（user_a）
emulator-5556	Pixel_9_Pro_2	5556	副设备（user_b）

启动命令（Agent 可直接执行）：

export ANDROID_HOME=/Users/xuqinmin/Library/Android/sdk
$ANDROID_HOME/emulator/emulator -avd Pixel_9_Pro   -no-audio -no-boot-anim -no-snapshot-save &
$ANDROID_HOME/emulator/emulator -avd Pixel_9_Pro_2 -no-audio -no-boot-anim -no-snapshot-save &
# 等待双设备就绪
adb wait-for-device && sleep 15

3.3 后端服务

模式	地址	适用场景
外部（推荐）	`https://dev.xuqinmin.com`	自动化测试（稳定）
本地	`http://192.168.113.37`	开发调试

3.4 测试账号

账号	密码	appId	用途
user_a	123456	ak_demo_chat	主发送方
user_b	123456	ak_demo_chat	接收方
user_ascii	123456	ak_demo_chat	ASCII 专项

四、测试用例清单

TC-01 SDK 初始化测试

字段	内容
测试类型	自动化（含于 @BeforeClass）
优先级	P0
前置条件	无
测试步骤	1. 调用 `XuqmSDK.initialize(context, "ak_demo_chat")` 2. 调用 `XuqmSDK.requireInit()` 3. 检查 `XuqmSDK.config`、`tokenStore` 是否已赋值
预期结果	初始化成功，无异常；ServiceEndpoints 使用内置生产环境地址
自动化代码	`SdkIntegrationTest.@BeforeClass initSdk()`
通过状态	✅ 通过

TC-02 IM 登录 / 登出测试

字段	内容
测试类型	自动化（含于 @Before/@After）
优先级	P0
前置条件	SDK 已初始化
测试步骤	1. 调用 Demo API 获取 imToken 2. 调用 `XuqmSDK.login(userId, userSig)` 3. 等待 `ImSDK.connectionState == Connected`（超时 20s） 4. 调用 `XuqmSDK.logout()` 5. 确认 connectionState → Disconnected
预期结果	WebSocket 101 连接建立，STOMP CONNECTED；登出后 TokenStore 清空
自动化代码	`SdkIntegrationTest.setUp()` / `tearDown()`
通过状态	✅ 通过

TC-03 单聊消息收发测试

字段	内容
测试类型	自动化（含于 TC-05 前置步骤）+ 可选手工复验
优先级	P0
前置条件	user_a、user_b 均已登录
双设备方案	emulator-5554(user_a) → 发送；emulator-5556(user_b) → 接收回调
测试步骤	1. user_a: `ImSDK.sendTextMessage("user_b", "SINGLE", content)` 2. user_b: 监听 `ImEventListener.onMessage()` 3. user_b: `fetchHistory("user_a")` 验证分页 4. user_b: `markRead("user_a")` 5. user_a: 查询 history，确认 status=READ
预期结果	消息 status≠FAILED；user_b 实时收到；未读归零
通过状态	✅ 通过（已手工验证）

TC-04 群聊消息收发测试

字段	内容
测试类型	手工（含 Agent 辅助）
优先级	P1
双设备方案	emulator-5554(user_a) 创建群、发消息；emulator-5556(user_b) 订阅、接收
测试步骤	1. user_a: `createGroup("TestGroup", ["user_b"])` 2. user_a: `subscribeGroup(groupId)` → 发送群消息 3. user_b: `subscribeGroup(groupId)` → `onGroupMessage()` 4. 双端: `fetchGroupHistory(groupId)` 5. 双端: `listConversations()` 确认群会话
预期结果	群创建成功；双端消息收发正常；历史分页正确
通过状态	✅ 通过（群会话聚合 Bug 已修复复验）

TC-05 会话列表 / 置顶 / 静音 / 草稿 / 已读 / 隐藏测试

字段	内容
测试类型	自动化
优先级	P1
前置条件	user_a 已登录且 WebSocket 已连接；@BeforeClass 已创建 testGroupId（GROUP 会话）
设计说明	使用 @BeforeClass 新建的群（testGroupId）而非 SINGLE 会话，原因：`deleteConversation` 在服务端为永久删除，重跑时 SINGLE 会话无法通过 SDK 恢复，导致测试幂等性破坏。GROUP 会话每次运行新建，彻底隔离状态。`deleteConversation` 功能移至 TC-99 专测。
测试步骤	1. `subscribeGroup(testGroupId)` + 发送探针消息 2. 轮询 `listConversations()` 直到 GROUP 会话出现（最长 15s） 3. `setConversationPinned(testGroupId, "GROUP", true)` → `isPinned=true` 4. `setConversationMuted(testGroupId, "GROUP", true)` → `isMuted=true` 5. `setDraft(testGroupId, "GROUP", "草稿内容")` → 不抛异常 6. `markRead(testGroupId, "GROUP")` → `unreadCount=0` 7. 清理置顶/静音 8. `setConversationHidden(testGroupId, "GROUP", true)` → 列表不再出现 9. `setConversationHidden(testGroupId, "GROUP", false)` → 恢复（保证后续测试可用）
预期结果	全步骤无异常；置顶/静音/已读状态服务端持久化正确；隐藏/恢复可逆
自动化代码	`SdkIntegrationTest.tc05_conversationManagement()`
执行模拟器	emulator-5554 + emulator-5556
通过状态	✅ 通过（双模拟器）

TC-99 会话永久删除测试

字段	内容
测试类型	自动化
优先级	P2
前置条件	user_a 已登录；testGroupId 有效（@BeforeClass 创建）
设计说明	放在最后（名称字典序 tc99 最大）；每次运行使用当次创建的 testGroupId，不影响后续运行（下次 @BeforeClass 创建新群）。
测试步骤	1. `subscribeGroup(testGroupId)` + 发送消息确保群会话存在 2. 轮询 `listConversations()` 确认群会话可见 3. `deleteConversation(testGroupId, "GROUP")` 4. 查询 `listConversations()`，断言群会话已消失
预期结果	deleteConversation 后目标群会话从列表中永久移除
自动化代码	`SdkIntegrationTest.tc99_deleteConversation()`
通过状态	✅ 通过

TC-06 Push 设备注册测试

字段	内容
测试类型	自动化（模拟器场景） + 真机手工（Firebase 场景）
优先级	P1
前置条件	SDK 已初始化，user_a 已登录
测试步骤（自动化-模拟器）	1. `detectVendor()` → FCM 2. `initializeVendors(context)` → 不崩溃 3. `currentRegistration(context)?.pushToken` → null（无 Firebase） 4. `setReceivePush(context, userId, false)` → 接口调用正常 5. `setReceivePush(context, userId, true)` → 恢复
测试步骤（手工-真机）	1. Firebase 设备：`registerDevice()` → `/api/push/register` 返回 200 2. `setReceivePush(false)` → `/api/push/receive` 设为 false 3. 登出 → `/api/push/unregister` 返回 200
自动化代码	`PushSdkTest.tc06_pushRegistrationEmulator()`
通过状态	✅ 通过（模拟器场景）；真机场景待真机验证

TC-07 版本更新检查测试

字段	内容
测试类型	自动化
优先级	P2
前置条件	SDK 已初始化，user_a 已登录
测试步骤	1. `UpdateSDK.checkAppUpdate(context)` 2. 返回 `UpdateInfo?`：若非 null 断言 `versionCode > 0`、`versionName` 非空 3. 若 `needsUpdate=true`，验证 `downloadUrl` 经过 normalizeDownloadUrl 处理
预期结果	接口无异常；UpdateInfo 字段完整（若有更新）
自动化代码	`SdkIntegrationTest.tc07_updateCheck()`
通过状态	✅ 通过

TC-08 UserSig 匹配重登测试

字段	内容
测试类型	自动化
优先级	P1
前置条件	user_a 已登录，WebSocket Connected
测试步骤	1. 记录初始 `connectionState == Connected` 2. 不登出，再次调用 Demo API 获取 token（可能相同或不同） 3. `XuqmSDK.login(userId, newToken)` 4. 等待 `connectionState == Connected`（超时 20s） 5. 断言 `currentLoginSession.userId == user_a`
预期结果	token 相同→跳过重连保持 Connected；token 不同→无缝重连恢复 Connected；无内存泄漏
自动化代码	`SdkIntegrationTest.tc08_reLogin()`
通过状态	✅ 通过

TC-09 多厂商 Push 检测测试

字段	内容
测试类型	自动化
优先级	P2
前置条件	SDK 已初始化
测试步骤	1. 读取 `Build.MANUFACTURER.uppercase()` 2. 按映射表验证 `detectVendor()` 返回值：HUAWEI→HUAWEI, XIAOMI→XIAOMI, OPPO→OPPO, VIVO→VIVO, HONOR→HONOR, 其他→FCM 3. 验证 `initializeVendors()` 仅初始化匹配厂商服务
预期结果	emulator（MANUFACTURER=Google）→ FCM；真机按品牌正确识别
自动化代码	`PushSdkTest.tc09_vendorDetection()`
执行模拟器	emulator-5554 + emulator-5556
通过状态	✅ 通过（双模拟器）

TC-10 网络断开 / 自动重连测试

字段	内容
测试类型	自动化（Instrumented，反射注入）
优先级	P1
前置条件	user_a 已登录，WebSocket Connected
测试步骤（自动化）	1. 记录 `connectionState == Connected` 2. 反射获取 `ImSDK.client` 字段 3. 调用 `ImClient.disconnect()`（不修改 `reconnectEnabled`） 4. 等待 `connectionState == Disconnected`（超时 5s） 5. 等待 `connectionState == Connected`（超时 15s，退避首次 1s） 6. 验证重连后能发送消息
测试步骤（WiFi 级）	`bash scripts/tc10_network_resilience.sh emulator-5554`
预期结果	SDK 在 15s 内自动重连；重连后消息发送正常
自动化代码	`NetworkResilienceTest.tc10_autoReconnectAfterSocketClose()`
执行模拟器	emulator-5554 + emulator-5556
通过状态	✅ 通过（双模拟器，5.5s / 5.6s）

TC-11 消息撤回 / 编辑测试

字段	内容
测试类型	自动化
优先级	P2
前置条件	user_a 已登录，WebSocket Connected；testGroupId 有效（@BeforeClass 创建）
设计说明	使用 testGroupId（GROUP）发送和查询消息，避免依赖 SINGLE 会话历史（SINGLE 会话可能被 deleteConversation 永久删除导致 fetchHistory 返回空）。`fetchGroupHistory` 独立于会话记录，始终可用。
测试步骤（TC-11a 撤回）	1. `subscribeGroup(testGroupId)` 2. 发送带唯一标签的群消息 3. 轮询 `fetchGroupHistory(testGroupId)` 按内容匹配服务端 ID（最长 10s） 4. `revokeMessage(id)` 5. 断言返回消息 `status == "REVOKED"`
测试步骤（TC-11b 编辑）	1. `subscribeGroup(testGroupId)` 2. 发送带唯一标签群消息 → 轮询 `fetchGroupHistory` 内容匹配 ID 3. `editMessage(id, newContent)` 4. 断言 `editedAt != null` 且 `content == newContent`
预期结果	撤回后 status="REVOKED"；编辑后 editedAt 有值且 content 更新
自动化代码	`SdkIntegrationTest.tc11a_revokeMessage()` / `tc11b_editMessage()`
通过状态	✅ 通过

TC-12 文件消息发送测试

字段	内容
测试类型	自动化
优先级	P2
前置条件	user_a 已登录，WebSocket Connected
测试步骤	1. 在 `cacheDir` 创建临时文本文件 2. `ImSDK.sendFileMessage(toId, chatType, file)` 3. 断言 `msg.status != "FAILED"` 4. 断言 `msg.content` 解析为 JSON 且含 `url` 字段 5. 清理临时文件
预期结果	文件上传成功；消息 content 含有效 URL；status 非 FAILED
自动化代码	`SdkIntegrationTest.tc12_sendFileMessage()`
通过状态	✅ 通过

TC-03 单聊消息收发（双设备自动化）

字段	内容
测试类型	自动化（跨设备轮询）
优先级	P0
执行顺序	1. emulator-5554 运行 `CrossDeviceSenderTest`（user_a 发送） 2. emulator-5556 运行 `CrossDeviceReceiverTest`（user_b 轮询接收）
测试步骤	发送方: `sendTextMessage(user_b, SINGLE, CROSS_DEVICE_AUTO_SINGLE_...)` 接收方: 轮询 `fetchHistory("user_a")` 找含 CROSS_DEVICE_AUTO 的消息（最长 40s）接收方: `markRead("user_a")` → 验证 unreadCount=0
通过状态	✅ 通过（双模拟器，12.66s）

TC-04 群聊消息收发（双设备自动化）

字段	内容
测试类型	自动化（跨设备轮询）
优先级	P1
执行顺序	与 TC-03 同批（CrossDeviceSenderTest + CrossDeviceReceiverTest）
测试步骤	发送方: `createGroup(TC04_AUTO_GROUP_xxx, [user_b])` → 订阅 → 发消息接收方: `listGroups()` 找 TC04_AUTO_GROUP 前缀最新群 → `fetchGroupHistory` 找消息
通过状态	✅ 通过（双模拟器）

五、Agent 执行手册

本节提供可供 AI Agent（Claude Code 或其他）直接无缝接续执行的完整命令集。

5.1 前置检查

# 检查 adb 连接
export ANDROID_HOME=/Users/xuqinmin/Library/Android/sdk
$ANDROID_HOME/platform-tools/adb devices
# 预期: emulator-5554 device / emulator-5556 device

# 若模拟器未启动
$ANDROID_HOME/emulator/emulator -avd Pixel_9_Pro   -no-audio -no-boot-anim -no-snapshot-save &
$ANDROID_HOME/emulator/emulator -avd Pixel_9_Pro_2 -no-audio -no-boot-anim -no-snapshot-save &
sleep 30  # 等待启动

5.2 构建 APK

cd /Users/xuqinmin/Projects/XuqmGroup/XuqmGroup-AndroidSDK

# 构建主 APK + 测试 APK
./gradlew :sample-app:assembleDebug :sample-app:assembleDebugAndroidTest

# 验证产物
ls sample-app/build/outputs/apk/debug/sample-app-debug.apk
ls sample-app/build/outputs/apk/androidTest/debug/sample-app-debug-androidTest.apk

5.3 安装到双模拟器

APK=sample-app/build/outputs/apk/debug/sample-app-debug.apk
TEST_APK=sample-app/build/outputs/apk/androidTest/debug/sample-app-debug-androidTest.apk

for DEV in emulator-5554 emulator-5556; do
  adb -s $DEV install -r "$APK"
  adb -s $DEV install -r "$TEST_APK"
done

5.4 执行自动化测试

RUNNER="androidx.test.runner.AndroidJUnitRunner"
TEST_PKG="com.xuqm.demo.test"

# ── 单设备全量（TC-01~TC-12, 非跨设备部分）──
ALL_SINGLE="com.xuqm.sdk.sample.SdkIntegrationTest,com.xuqm.sdk.sample.PushSdkTest,com.xuqm.sdk.sample.NetworkResilienceTest"
adb -s emulator-5554 shell am instrument -w -r -e class "$ALL_SINGLE" "${TEST_PKG}/${RUNNER}"
adb -s emulator-5556 shell am instrument -w -r -e class "$ALL_SINGLE" "${TEST_PKG}/${RUNNER}"

# ── 跨设备 TC-03/04（先发送方，再接收方）──
adb -s emulator-5554 shell am instrument -w -r \
  -e class "com.xuqm.sdk.sample.CrossDeviceSenderTest" "${TEST_PKG}/${RUNNER}"
adb -s emulator-5556 shell am instrument -w -r \
  -e class "com.xuqm.sdk.sample.CrossDeviceReceiverTest" "${TEST_PKG}/${RUNNER}"

或使用 Gradle（自动检测所有连接设备，单设备用例）：

./gradlew :sample-app:connectedDebugAndroidTest

5.5 判断通过标准

每个测试用例输出:
  INSTRUMENTATION_STATUS_CODE: 0   → 通过
  INSTRUMENTATION_STATUS_CODE: -2  → 失败（查看 stack 字段）

全套通过期望（单设备 13 个用例）:
  Tests run: 13, Failures: 0  （SdkIntegrationTest×10 + PushSdkTest×2 + NetworkResilienceTest×1）

跨设备（各 2 个用例）:
  CrossDeviceSenderTest: Tests run: 2, Failures: 0
  CrossDeviceReceiverTest: Tests run: 2, Failures: 0

5.6 查看 Logcat（失败时诊断）

# 过滤 SDK 相关日志
adb -s emulator-5554 logcat -d -s "XuqmImSDK:D" "XuqmPushSDK:W" "XuqmUpdateSDK:D"

# TC-10 网络韧性（实时监控重连事件）
adb -s emulator-5554 logcat -s "XuqmImSDK:D" | grep -E "onConnected|onDisconnected|scheduleReconnect|connectWithToken"

5.7 TC-10 WiFi 断开（可选主机级脚本）

# 使用 adb 从主机切换模拟器网络（需先确保 App 已登录）
bash scripts/tc10_network_resilience.sh emulator-5554

推荐方式: 使用 NetworkResilienceTest（Section 5.4 已包含），通过反射直接关闭 WebSocket，无需登录状态依赖。

六、测试文件路径索引

文件	作用
`sample-app/src/androidTest/java/com/xuqm/sdk/sample/SdkIntegrationTest.kt`	TC-05 / TC-07 / TC-08 / TC-11 / TC-12 / TC-13 / TC-14 / TC-15 自动化
`sample-app/src/androidTest/java/com/xuqm/sdk/sample/PushSdkTest.kt`	TC-06 / TC-09 Push 自动化
`sample-app/src/androidTest/java/com/xuqm/sdk/sample/NetworkResilienceTest.kt`	TC-10 网络韧性自动化
`sample-app/src/androidTest/java/com/xuqm/sdk/sample/CrossDeviceTest.kt`	TC-03 / TC-04 双设备协同自动化
`scripts/tc10_network_resilience.sh`	TC-10 WiFi 级别网络断开脚本（主机运行）
`sample-app/build.gradle.kts`	已添加 `testInstrumentationRunner` 及测试依赖
`TEST_REPORT.md`	每轮测试结果记录

七、测试汇总（当前状态）

用例	名称	类型	自动化	状态
TC-01	SDK 初始化	核心	✅ @BeforeClass	✅ 通过
TC-02	IM 登录/登出	核心	✅ @Before/@After	✅ 通过
TC-03	单聊消息收发	IM	✅ CrossDeviceTest	✅ 通过（双模拟器）
TC-04	群聊消息收发	IM	✅ CrossDeviceTest	✅ 通过（双模拟器）
TC-05	会话管理（置顶/静音/已读/删除）	IM	✅ SdkIntegrationTest	✅ 通过
TC-06	Push 设备注册	Push	✅ PushSdkTest	✅ 通过（模拟器 FCM）
TC-07	版本更新检查	Update	✅ SdkIntegrationTest	✅ 通过
TC-08	UserSig 重登	核心	✅ SdkIntegrationTest	✅ 通过
TC-09	多厂商 Push 检测	Push	✅ PushSdkTest	✅ 通过（双模拟器）
TC-10	网络断开/自动重连	核心	✅ NetworkResilienceTest	✅ 通过（双模拟器）
TC-11a	消息撤回	IM	✅ SdkIntegrationTest	✅ 通过
TC-11b	消息编辑	IM	✅ SdkIntegrationTest	✅ 通过
TC-12	文件消息发送	IM	✅ SdkIntegrationTest	✅ 通过
TC-13	音频消息发送	IM	✅ SdkIntegrationTest	✅ 通过
TC-14	消息关键词搜索	IM	✅ SdkIntegrationTest	✅ 通过
TC-15	好友管理与黑名单	IM	✅ SdkIntegrationTest	✅ 通过
TC-99	会话永久删除（GROUP）	IM	✅ SdkIntegrationTest	✅ 通过

总计: 17 用例 / 17 通过 | 自动化覆盖率: 17/17（100%）

八、后续扩展建议

扩展项	优先级	说明
TC-06 真机 Firebase 验证	P1	在 Pixel/Samsung 真机上验证 FCM token 注册流程，`/api/push/register` 返回 200
TC-10 WiFi 级压测	P2	使用 `scripts/tc10_network_resilience.sh` 在已登录 App 上做 WiFi 级断网验证
TC-16 音视频通话（预留）	P3	待 RTC 模块上线后补充
CI/CD 集成	P1	Jenkins Job `xuqmgroup-android-sdk-test`，`connectedDebugAndroidTest` 自动触发；见 `Jenkinsfile`

21 KiB 原始文件 Blame 文件历史 Unescape Escape

XuqmGroup Android SDK 集成测试计划

一、文档目的

二、测试范围

2.1 模块覆盖

2.2 测试类型定义

三、测试环境

3.1 硬件 / 软件环境

3.2 模拟器配置

3.3 后端服务

3.4 测试账号

四、测试用例清单

TC-01 SDK 初始化测试

TC-02 IM 登录 / 登出测试

TC-03 单聊消息收发测试

TC-04 群聊消息收发测试

TC-05 会话列表 / 置顶 / 静音 / 草稿 / 已读 / 隐藏测试

TC-99 会话永久删除测试

TC-06 Push 设备注册测试

TC-07 版本更新检查测试

TC-08 UserSig 匹配重登测试

TC-09 多厂商 Push 检测测试

TC-10 网络断开 / 自动重连测试

TC-11 消息撤回 / 编辑测试

TC-12 文件消息发送测试

TC-03 单聊消息收发（双设备自动化）

TC-04 群聊消息收发（双设备自动化）

五、Agent 执行手册

5.1 前置检查

5.2 构建 APK

5.3 安装到双模拟器

5.4 执行自动化测试

5.5 判断通过标准

5.6 查看 Logcat（失败时诊断）

5.7 TC-10 WiFi 断开（可选主机级脚本）

六、测试文件路径索引

七、测试汇总（当前状态）

八、后续扩展建议

21 KiB

原始文件 Blame 文件历史