把iPhone功能搬上Mac:spoti.pw harness离线测试体系深度剖析
把iPhone功能搬上Mac:spoti.pw harness离线测试体系深度剖析
spoti.pw 是一款免越狱(no jailbreak)的 Spotify iOS 主题修改,以 Liquid Glass(液态玻璃)风格重构 Spotify 界面。它基于 Theos 框架(Objective-C + Logos)注入 Spotify 应用,而仓库中的 harness/ 目录则是一套完整的离线测试体系:无需真机、无需联网,在 Mac 上就能对修改代码进行编译、运行和验证。本文将拆解这套测试体系的原理、组成和亮点。
一、harness 是什么:为真机痛点而生的离线测试体系
🔍 先说痛点。spoti.pw 的界面修改全部依赖 Hook Spotify 内部类,而 iOS 的 UI 渲染、玻璃质感、动画过渡只有真机或模拟器才能看到效果。如果每次改动都要"编译 → 签名 → 装到 iPhone → 截图确认",效率极低。
harness 的思路是:在 Mac 上造一个最小化的"假 Spotify"——用真实视图树数据搭建出和真机一模一样的页面骨架,再把 spoti.pw 的真实源代码编译进去运行。这样:
- 界面布局、动画、状态切换都能在 Mac 上截图验证;
- 音频引擎、节拍分析等逻辑可以直接跑成 Mac 原生程序,逐帧输出数据;
- 修 bug 时可以"修复前 vs 修复后"对比,而不是凭感觉。
整个体系的入口很简单:每个子目录都有自己的 build.sh 和 README.md,例如 harness/lyrics/README.md 中只用了 4 行命令就能跑起一个歌词演示程序。
二、核心原理:真源码 + 假页面 + 模拟器三件套
1️⃣ 基于真实视图树的 mock 页面
Spotify 的界面结构从哪来?项目用 FLEX 检查器通过 USB 把 iPhone 上每个页面的视图树(类名、可访问性标识、布局参数)录制到 trees/clean/ 目录,脚本是 scripts/record-trees.py。
harness 里的 mock 页面就照着这些真实数据 1:1 复现:比如 harness/player/README.md 说明,播放器 mock 直接沿用了 trees/clean/player/01.txt 中的真实类名和可访问性标识;harness/tabbar/README.md 甚至标注了 Spotify 源码中的地址(0x1008409a8),说明 tab bar 的 49pt 安全区、64pt 正在播放栏等参数都是从真机逆向读出的。
关键点:mock 页面的类名与 Spotify 完全一致,所以 spoti.pw 的 Logos Hook(
.x文件)能原样命中,测试的就是真实生效的代码路径。
2️⃣ 真实修改源码 + stubs.m 补位
编译时,build.sh 先用 logos.pl -c generator=internal 把 Logos 的 .x 钩子文件编译成 C,再链接真实的 tweak/Sources/Core/ 和 tweak/Sources/Redesigned/Kit/ 源码;无法在 harness 里运行的部分(如网络、真实播放器)由每个目录的 stubs.m 打桩替代。
以 harness/album/README.md 为例:专辑页的 mock 包含 Spotify 原生的头部、元数据行、浮动播放/随机按钮、曲目列表和页脚,而真正被测试的是 Redesigned/Album/ 的四个真实 .x 文件。
3️⃣ 三步在 Mac 上跑起来
THEOS=$HOME/theos ./build.sh # 编译出 PlayerHarness.app
xcrun simctl install booted build/PlayerHarness.app # 装入 iOS 26 模拟器
xcrun simctl launch booted com.vojta.playerharness # 启动并自动播放脚本场景
xcrun simctl io booted screenshot shot.png # 截图留证
配合 xcrun simctl io recordVideo 录屏,还能用 ffmpeg 把动画裁成逐帧条带(frame strip)逐格检查过渡效果——这是 harness/morph/README.md 验证"播放器上滑展开"动画的标准做法。
三、19 个 harness 组件:从 UI 到音频引擎全覆盖
harness/ 下共有 19 个子目录,按测试目标可分为三类:
| 类型 | 组件 | 测试内容 |
|---|---|---|
| UI 页面 mock | player、album、playlist、artist、library、tabbar、menu、morph |
各页面重绘、头部折叠、状态切换、动画过渡 |
| 音频/歌词引擎 | lyrics、audio-effects、speed、pitch、haptics |
歌词渲染、DSP 引擎、变速变调、音乐节拍触发的振动 |
| 功能与设置页 | update、donate、lockart、glass、haptics-page、audio-effects-page |
更新检查、打赏弹窗、锁屏动态封面、玻璃效果、设置页交互 |
几个有代表性的设计:
🎤 Lyrics(歌词)harness:用自己的时钟"放歌",调用真实的 SGTTML.m 解析 TTML 时间轴歌词。测试曲目全部经过 harness/lyrics/fixtures/anonymise.py 匿名化处理(保留时值结构、替换词文本),覆盖了二重唱叠句、日文罗马音注音、西语翻译、RTL 右向左文字、13 秒纯器乐间奏等 9 种真实场景。
🎛️ Audio effects(音频效果)harness:分两半——Mac 原生程序直接跑 SGDSP*.m 引擎,验证 EQ、混响、交叉渐变、限幅器等逐项指标;sim/ 子目录则在模拟器里用真实 AudioUnit 重建 Spotify 的音频链路(converter → mixer → RemoteIO),确保 Hook 的接管方式和真机完全一致。
⚡ Player(播放器)harness 的 artwork 场景最能体现"回归测试"价值:它模拟封面图晚到 3.5 秒、连续切歌且旧图最后返回等竞态,日志最后输出 artwork checks: n of 4 right -- PASS/FAIL。修复 issue #58 之前这里只能得 1 of 4,修复后 4 of 4。
四、值得借鉴的 3 个工程细节
1. 可以"时光倒流"复现历史问题
所有 build.sh 都支持 SRC=<另一个检出>/tweak/Sources OUT=<dir> 参数,即可以旧提交的源码编译同一个 harness。这样修复 bug 后,同一个场景在新旧代码上各跑一遍,差异一目了然(见 harness/player/README.md 和 harness/glass/README.md)。
2. 每个 README 都写明"不覆盖什么" harness 诚实地标注边界。例如 harness/glass/README.md 承认:模拟器不折射玻璃效果,所以 issue #39 那种"字形被玻璃吞掉"的 bug 仍只能靠真机区分,harness 只负责证明"形状依然居中、位于字形后方"。这种"能力清单"比模糊的"测试通过"可靠得多。
3. 音频指标是量化打分,不是听感 harness/haptics/score.py 用 mir_eval 把节拍触发的振动与 librosa 提取的 onset 一一匹配(50ms 容差),输出精确率/召回率,并与"随机节拍"基线对比:
| Follows 选项 | 对照 | precision | recall | 随机基线 |
|---|---|---|---|---|
| Everything, Beat | 混音鼓点 onset | 0.73 | 0.68 | 0.30 |
| Everything, Beat | 鼓部分离声轨 | 0.66 | 0.89 | 0.21 |
| Bass | 150Hz 以下低频 | 0.84 | 0.70 | 0.22 |
五、新手快速上手:三步体验
- 准备一台装有 Xcode 的 Mac,Theos 位于
~/theos(安装步骤见 Makefile 与 README.md 的 Build 章节); - 进入任一 harness 目录,如
harness/lyrics/,先读它的README.md,运行./build.sh; xcrun simctl install+xcrun simctl launch装入 iOS 26 模拟器,screenshot截图、recordVideo录屏、log stream看日志,即可完成一次完整验证。
📚 更多背景可参考 docs/tweaks.md(每个模块都注明了"Tested against harness/xxx")和 AGENTS.md(项目分层与构建规范)。
六、总结
spoti.pw 的 harness 体系展示了"移动端 UI 修改如何做到无真机可测"的完整答案:真实视图树驱动 mock、真实源码保证测的就是线上代码、模拟器 + 脚本化场景保证可重复、量化指标保证结论可信。对于任何需要频繁修改 UI 的 iOS 项目,这套"Mac 上跑假机"的思路都极具参考价值。

