把iPhone功能搬上Mac:spoti.pw harness离线测试体系深度剖析

原创2026-10-25 20:13:202,191 阅读

把iPhone功能搬上Mac:spoti.pw harness离线测试体系深度剖析

spoti.pw 是一款免越狱(no jailbreak)的 Spotify iOS 主题修改,以 Liquid Glass(液态玻璃)风格重构 Spotify 界面。它基于 Theos 框架(Objective-C + Logos)注入 Spotify 应用,而仓库中的 harness/ 目录则是一套完整的离线测试体系:无需真机、无需联网,在 Mac 上就能对修改代码进行编译、运行和验证。本文将拆解这套测试体系的原理、组成和亮点。

spoti.pw Liquid Glass 主页界面效果

一、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。

spoti.pw Liquid Glass 专辑页界面效果

四、值得借鉴的 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

五、新手快速上手:三步体验

  1. 准备一台装有 Xcode 的 Mac,Theos 位于 ~/theos(安装步骤见 Makefile 与 README.md 的 Build 章节);
  2. 进入任一 harness 目录,如 harness/lyrics/,先读它的 README.md,运行 ./build.sh;
  3. 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 上跑假机"的思路都极具参考价值。

登录后查看全文
spoti.pw