Skip to content

TESTING_GUIDE.md

Latest commit

 

History

History
696 lines (523 loc) · 15.2 KB

TESTING_GUIDE.md

File metadata and controls

696 lines (523 loc) · 15.2 KB
Raw

Kanade 音乐播放器 - 详细测试指南

📋 目录

  1. 测试前准备
  2. 基础功能测试
  3. 浮窗歌词测试
  4. 日志查看指南
  5. 常见问题排查
  6. 测试检查清单

测试前准备

1. 确认应用已安装

方式一：通过 Android Studio

# 编译并安装 Debug 版本
./gradlew installDebug

# 或者直接运行
./gradlew runDebug

方式二：通过 ADB 手动安装

# 编译 APK
./gradlew assembleDebug

# 安装到设备
adb install app/build/outputs/apk/debug/app-debug.apk

验证安装

# 检查应用是否已安装
adb shell pm list packages | grep org.parallel_sekai.kanade

# 预期输出：
# package:org.parallel_sekai.kanade

2. 确认设备已连接

# 列出所有连接的设备
adb devices

# 预期输出示例：
# List of attached devices
# emulator-5554          device
# 13pro:5555             device
# 192.168.31.104:5555    device

连接远程设备（平板/手机）：

# 平板连接
adb connect 192.168.31.104:5555

# 手机连接
adb connect 13pro:5555

# 验证连接
adb devices

3. 确认权限已授予

应用需要以下权限：

权限 用途 必需
READ_MEDIA_AUDIO 读取音乐文件 ✅ 必需
POST_NOTIFICATIONS 显示播放通知 ✅ 必需
SYSTEM_ALERT_WINDOW 显示浮窗歌词 ✅ 必需（浮窗功能）
INTERNET 网络访问（脚本音源） ⚠️ 可选

授予权限

# 授予读取音乐权限
adb shell pm grant org.parallel_sekai.kanade android.permission.READ_MEDIA_AUDIO

# 授予通知权限
adb shell pm grant org.parallel_sekai.kanade android.permission.POST_NOTIFICATIONS

# 授予浮窗权限
adb shell pm grant org.parallel_sekai.kanade android.permission.SYSTEM_ALERT_WINDOW

# 授予网络权限（自动授予）
adb shell pm grant org.parallel_sekai.kanade android.permission.INTERNET

验证权限

# 查看应用权限
adb shell pm list permissions -g | grep -A 20 org.parallel_sekai.kanade

# 或者在设备上：设置 → 应用 → Kanade → 权限

基础功能测试

1. 启动应用

# 启动应用
adb shell am start -n org.parallel_sekai.kanade/.MainActivity

# 预期结果：
# - 应用启动成功
# - 显示主播放器界面
# - 无崩溃日志

2. 准备测试音乐

方式一：使用设备本地音乐

# 查看设备上的音乐文件
adb shell find /storage/emulated/0/Music -name "*.mp3" -o -name "*.flac"

# 如果没有音乐，可以推送测试文件
adb push /path/to/test/music.mp3 /storage/emulated/0/Music/

方式二：使用模拟音源（KSS 脚本）

应用内置 mock_provider.js，可以提供虚拟音乐源进行测试。

3. 播放音乐

步骤：

  1. 打开应用
  2. 进入"音乐库"或"搜索"页面
  3. 选择一首歌曲
  4. 点击播放按钮

预期结果：

  • ✅ 音乐开始播放
  • ✅ 播放进度条更新
  • ✅ 播放时间显示正确
  • ✅ 暂停/继续功能正常
  • ✅ 下一曲/上一曲功能正常

浮窗歌词测试

前置条件

  • ✅ 应用已安装并启动
  • ✅ 已授予 SYSTEM_ALERT_WINDOW 权限
  • ✅ 正在播放有歌词的音乐

1. 启用浮窗歌词

步骤：

  1. 打开应用
  2. 进入"设置"页面
  3. 找到"浮窗歌词"选项
  4. 打开开关

预期结果：

  • ✅ 浮窗歌词服务启动
  • ✅ 浮窗出现在屏幕上
  • ✅ 日志显示 FloatingLyricsService started

2. 检查歌词显示

步骤：

  1. 确保浮窗歌词已启用
  2. 播放一首有歌词的音乐
  3. 观察浮窗内容

预期结果：

  • ✅ 歌词文本显示在浮窗中
  • ✅ 歌词内容与当前播放的歌曲匹配
  • ✅ 浮窗位置可见（不被其他应用遮挡）

3. 检查歌词同步

步骤：

  1. 播放音乐
  2. 观察浮窗歌词随播放进度更新
  3. 快进/快退音乐
  4. 观察歌词是否立即更新

预期结果：

  • ✅ 歌词随播放进度实时更新
  • ✅ 快进/快退后歌词立即同步
  • ✅ 无明显延迟（< 100ms）

4. 切歌时歌词更新

步骤：

  1. 播放第一首歌曲
  2. 记录浮窗显示的歌词
  3. 点击"下一曲"或"上一曲"
  4. 观察浮窗歌词变化

预期结果：

  • ✅ 歌词立即更新为新歌曲的歌词
  • ✅ 如果新歌曲无歌词，显示"暂无歌词"或空白
  • ✅ 无崩溃或闪烁

5. 浮窗交互测试

步骤：

  1. 浮窗歌词启用状态下
  2. 尝试拖动浮窗位置
  3. 尝试调整浮窗大小（如支持）
  4. 尝试点击浮窗（如支持）

预期结果：

  • ✅ 浮窗可以拖动
  • ✅ 位置保存并在下次启动时恢复
  • ✅ 点击浮窗可以打开应用或控制播放

6. 浮窗关闭测试

步骤：

  1. 浮窗歌词启用状态下
  2. 在设置中关闭浮窗歌词开关
  3. 或者在浮窗上点击关闭按钮

预期结果：

  • ✅ 浮窗立即消失
  • ✅ 服务停止
  • ✅ 日志显示 FloatingLyricsService stopped

日志查看指南

1. 连接 ADB

# 确保设备已连接
adb devices

# 如果使用远程设备
adb connect 192.168.31.104:5555  # 平板
adb connect 13pro:5555            # 手机

2. 查看实时日志

# 查看所有日志
adb logcat

# 只查看 Kanade 应用的日志
adb logcat | grep "kanade\|Kanade"

# 清除日志后查看新日志
adb logcat -c && adb logcat | grep "kanade\|Kanade"

3. 过滤关键日志

浮窗歌词相关日志

# 查看浮窗服务日志
adb logcat | grep -i "FloatingLyrics"

# 预期日志：
# FloatingLyricsService: Service started
# FloatingLyricsService: Lyrics updated: [歌词内容]
# FloatingLyricsService: Position updated: 12345ms

播放相关日志

# 查看播放服务日志
adb logcat | grep -i "KanadePlayback"

# 预期日志：
# KanadePlaybackService: Now playing: [歌曲名]
# KanadePlaybackService: Playback state changed: PLAYING

歌词解析日志

# 查看歌词解析日志
adb logcat | grep -i "LyricParser\|LRC"

# 预期日志：
# LyricParser: Parsing LRC format
# LyricParser: Found 120 lyric lines

4. 关键日志标签

标签 说明
FloatingLyricsService 浮窗歌词服务
KanadePlaybackService 播放服务
LyricParser 歌词解析器
SettingsRepository 设置仓库
KSS 脚本系统
MediaSession 媒体会话

5. 保存日志到文件

# 保存日志到文件
adb logcat > kanade_logs.txt

# 实时查看并保存
adb logcat | tee kanade_logs.txt

# 查看特定时间段的日志
adb logcat -d > kanade_logs_$(date +%Y%m%d_%H%M%S).txt

6. 使用 Android Studio Logcat

  1. 打开 Android Studio
  2. 连接设备
  3. 打开 Logcat 窗口（View → Tool Windows → Logcat）
  4. 在搜索框中输入过滤条件：
    • package:org.parallel_sekai.kanade
    • FloatingLyrics
    • KanadePlayback

常见问题排查

问题 1：浮窗歌词不显示

症状

  • 启用浮窗歌词后，屏幕上看不到浮窗

排查步骤

步骤 1：检查权限

# 检查 SYSTEM_ALERT_WINDOW 权限
adb shell pm list permissions -g | grep -A 5 "SYSTEM_ALERT_WINDOW"

# 如果未授予，手动授予
adb shell pm grant org.parallel_sekai.kanade android.permission.SYSTEM_ALERT_WINDOW

步骤 2：检查服务是否启动

# 查看浮窗服务日志
adb logcat -c
# 启用浮窗歌词
# 等待 2 秒
adb logcat | grep -i "FloatingLyricsService"

# 预期输出：
# FloatingLyricsService: Service started

步骤 3：检查是否有歌词

# 查看歌词解析日志
adb logcat | grep -i "LyricParser"

# 如果显示 "No lyrics found"，说明当前歌曲无歌词

步骤 4：检查浮窗位置

  • 浮窗可能在屏幕边缘或被其他应用遮挡
  • 尝试拖动屏幕各个位置查找浮窗
  • 关闭其他浮窗应用（如微信浮窗、QQ浮窗）

步骤 5：重启服务

# 关闭浮窗歌词
# 等待 1 秒
# 重新启用浮窗歌词

问题 2：歌词不同步

症状

  • 浮窗显示的歌词与播放进度不匹配
  • 歌词更新延迟明显

排查步骤

步骤 1：检查播放状态

# 查看播放服务日志
adb logcat | grep -i "KanadePlayback"

# 确认播放状态为 PLAYING

步骤 2：检查歌词格式

# 查看歌词解析日志
adb logcat | grep -i "LyricParser"

# 检查是否成功解析歌词
# 支持的格式：LRC、增强型 LRC、TTML

步骤 3：检查时间同步

# 查看位置更新日志
adb logcat | grep -i "Position updated"

# 检查时间戳是否正确更新

步骤 4：检查设备性能

  • 如果设备性能较低，可能导致更新延迟
  • 关闭其他应用释放资源
  • 检查 CPU 和内存使用情况

问题 3：应用崩溃

症状

  • 应用启动后立即崩溃
  • 启用浮窗歌词后崩溃
  • 播放音乐时崩溃

排查步骤

步骤 1：查看崩溃日志

# 清除日志
adb logcat -c

# 重现崩溃
# 查看错误日志
adb logcat | grep -i "FATAL\|Exception\|Error"

# 保存完整日志
adb logcat > crash_logs.txt

步骤 2：检查权限问题

# 查看权限相关错误
adb logcat | grep -i "Permission"

# 授予所有必需权限
adb shell pm grant org.parallel_sekai.kanade android.permission.READ_MEDIA_AUDIO
adb shell pm grant org.parallel_sekai.kanade android.permission.POST_NOTIFICATIONS
adb shell pm grant org.parallel_sekai.kanade android.permission.SYSTEM_ALERT_WINDOW

步骤 3：检查内存问题

# 查看内存相关错误
adb logcat | grep -i "OutOfMemory\|MemoryError"

# 清理应用数据
adb shell pm clear org.parallel_sekai.kanade

# 重新启动应用
adb shell am start -n org.parallel_sekai.kanade/.MainActivity

步骤 4：检查 Android 版本兼容性

# 查看设备 Android 版本
adb shell getprop ro.build.version.release

# 应用支持 Android 8.0 (API 26) 及以上
# 如果版本过低，可能导致兼容性问题

问题 4：无法读取音乐文件

症状

  • 音乐库为空
  • 无法播放本地音乐

排查步骤

步骤 1：检查权限

# 检查 READ_MEDIA_AUDIO 权限
adb shell pm list permissions -g | grep -A 5 "READ_MEDIA_AUDIO"

# 授予权限
adb shell pm grant org.parallel_sekai.kanade android.permission.READ_MEDIA_AUDIO

步骤 2：检查音乐文件

# 查看设备上的音乐文件
adb shell find /storage/emulated/0/Music -type f \( -name "*.mp3" -o -name "*.flac" -o -name "*.wav" \)

# 如果没有文件，推送测试文件
adb push test_music.mp3 /storage/emulated/0/Music/

步骤 3：刷新媒体库

# 强制刷新 MediaStore
adb shell am broadcast -a android.intent.action.MEDIA_SCANNER_SCAN_FILE -d file:///storage/emulated/0/Music/

# 或者重启应用
adb shell am force-stop org.parallel_sekai.kanade
adb shell am start -n org.parallel_sekai.kanade/.MainActivity

步骤 4：检查文件格式

# 查看文件信息
adb shell file /storage/emulated/0/Music/test_music.mp3

# 确保文件格式被支持
# 支持的格式：MP3、FLAC、WAV、OGG、M4A 等

问题 5：浮窗歌词显示乱码

症状

  • 浮窗显示的歌词是乱码或特殊字符

排查步骤

步骤 1：检查歌词文件编码

# 查看歌词文件编码
file -i /path/to/lyrics.lrc

# 应该是 UTF-8 编码
# 如果是其他编码，需要转换

步骤 2：检查字体支持

# 查看字体相关日志
adb logcat | grep -i "Font\|Typeface"

# 如果显示字体加载失败，可能导致乱码

步骤 3：检查歌词格式

# 查看歌词解析日志
adb logcat | grep -i "LyricParser"

# 确保歌词格式正确
# LRC 格式示例：
# [00:12.00]歌词内容
# [00:15.50]下一行歌词

步骤 4：重新导入歌词

  • 删除当前歌词文件
  • 使用正确编码（UTF-8）重新创建歌词文件
  • 重新启动应用

测试检查清单

基础功能检查

  • 应用能正常启动
  • 能读取本地音乐文件
  • 能播放音乐
  • 播放进度条正常工作
  • 暂停/继续功能正常
  • 下一曲/上一曲功能正常
  • 音量控制正常
  • 快进/快退功能正常

浮窗歌词功能检查

  • 能启用浮窗歌词
  • 浮窗能正常显示
  • 浮窗显示的歌词正确
  • 歌词随播放进度更新
  • 切歌时歌词立即更新
  • 浮窗可以拖动
  • 浮窗位置能保存
  • 能关闭浮窗歌词
  • 浮窗不会遮挡重要内容

权限检查

  • READ_MEDIA_AUDIO 权限已授予
  • POST_NOTIFICATIONS 权限已授予
  • SYSTEM_ALERT_WINDOW 权限已授予
  • INTERNET 权限已授予（如使用脚本音源）

日志检查

  • 无 FATAL 错误
  • 无 Exception 异常
  • 浮窗服务正常启动
  • 播放服务正常启动
  • 歌词解析成功

性能检查

  • 应用启动时间 < 3 秒
  • 歌词更新延迟 < 100ms
  • 内存占用合理（< 200MB）
  • CPU 占用不超过 20%（空闲时）
  • 无明显卡顿

兼容性检查

  • 在 Android 8.0 及以上版本测试
  • 在不同屏幕尺寸设备测试
  • 在不同 Android 版本测试
  • 在低端设备测试

快速测试命令

一键安装和启动

# 编译、安装并启动应用
./gradlew installDebug && adb shell am start -n org.parallel_sekai.kanade/.MainActivity

一键授予所有权限

# 授予所有必需权限
adb shell pm grant org.parallel_sekai.kanade android.permission.READ_MEDIA_AUDIO && \
adb shell pm grant org.parallel_sekai.kanade android.permission.POST_NOTIFICATIONS && \
adb shell pm grant org.parallel_sekai.kanade android.permission.SYSTEM_ALERT_WINDOW && \
adb shell pm grant org.parallel_sekai.kanade android.permission.INTERNET

一键查看关键日志

# 清除日志并显示关键日志
adb logcat -c && sleep 1 && adb logcat | grep -E "FloatingLyrics|KanadePlayback|LyricParser|Exception|Error"

一键清理并重启

# 清理应用数据并重启
adb shell pm clear org.parallel_sekai.kanade && \
adb shell am start -n org.parallel_sekai.kanade/.MainActivity

推送测试音乐

# 创建测试音乐目录并推送文件
adb shell mkdir -p /storage/emulated/0/Music && \
adb push test_music.mp3 /storage/emulated/0/Music/

测试报告模板

# Kanade 测试报告

## 测试环境
- 设备型号：[例如：Pixel 6]
- Android 版本：[例如：Android 13]
- 应用版本：[例如：1.0]
- 测试日期：[YYYY-MM-DD]

## 测试结果

### 基础功能
- [ ] 通过 / [ ] 失败：应用启动
- [ ] 通过 / [ ] 失败：音乐播放
- [ ] 通过 / [ ] 失败：播放控制

### 浮窗歌词
- [ ] 通过 / [ ] 失败：浮窗显示
- [ ] 通过 / [ ] 失败：歌词同步
- [ ] 通过 / [ ] 失败：切歌更新

### 问题描述
[描述遇到的任何问题]

### 日志文件
[附加相关日志文件]

## 签名
测试人员：[名字]
日期：[YYYY-MM-DD]

联系方式

如有问题或建议，请：

  1. 查看 GitHub Issues
  2. 提交详细的测试报告
  3. 附加相关日志文件和截图