[iOS][XCTest] XCDevice 真机内存快照(memgraph)采集:单轮 measure + 独立测试工程

[nzcv]

[iOS][XCTest] XCDevice 真机内存快照(memgraph)采集:单轮 measure + 独立测试工程

场景:Unity 导出的 Xcode 工程(XPrj,App bundle id com.rm42.TrashDash),用 idevice 的 XCDevice.test() 在 物理真机 上跑一个与 App 工程解耦的独立 XCUITest,执行「启动游戏 → 延时 10s → 开始采集 → 延时 30s → 结束采集 → 结束游戏」,采集内存指标并导出 .memgraph 内存图。

总链路

独立测试工程 UITestsTemplate (UI Testing Bundle, 无 host app)
   → xcodebuild test (XCDevice.test) 针对真机
   → 测试内用 XCUIApplication(bundleIdentifier:) 启动已安装的 App
   → XCTMemoryMetric 采集 + -enablePerformanceTestsDiagnostics YES 产出 pre/post memgraph
   → xcresulttool export attachments 导出 memgraphset

方案一(推荐):测试工程固定、与频繁重导出的 App 工程完全解耦。测试用例通过 bundle id 启动「已安装」的 App,Unity 怎么重导出都不影响测试工程。

1. 独立测试工程的必要配置

UITestsTemplate.xcodeproj 是一个 UI Testing Bundle(无 target application),可驱动任意已安装 App。要在真机上跑通需配置两点:

1.1 签名团队(否则测试 runner 无法在真机签名)

project.pbxproj 里给测试 target 设置:

DEVELOPMENT_TEAM = TB8YV4RNJT;   # 用 App 工程同一个 Team
CODE_SIGN_STYLE = Automatic;

1.2 被测 App 的 bundle id

测试用例通过环境变量 APP_BUNDLE_ID 决定启动哪个 App:

private let defaultBundleID = "com.example.app"
private var bundleID: String {
    ProcessInfo.processInfo.environment["APP_BUNDLE_ID"] ?? defaultBundleID
}
let app = XCUIApplication(bundleIdentifier: bundleID)

在 UITests.xcscheme 的 TestAction 注入:

<TestAction
   ...
   shouldUseLaunchSchemeArgsEnv = "NO">   <!-- 关键:必须为 NO -->
   <EnvironmentVariables>
      <EnvironmentVariable key = "APP_BUNDLE_ID" value = "com.rm42.TrashDash" isEnabled = "YES"/>
   </EnvironmentVariables>
   <Testables> ... </Testables>
</TestAction>

⚠️ 坑:shouldUseLaunchSchemeArgsEnv = "YES" 时,Test action 会继承 Run action 的(空)环境变量,忽略 TestAction 自己的 <EnvironmentVariables>,导致测试仍去启动默认的 com.example.app(设备上没装 → FBSApplicationLibrary returned nil)。改为 NO 即可。

2. 内存快照用例(单轮 + 可抓 memgraph)

import XCTest

final class GameplayUITests: XCTestCase {

    private let defaultBundleID = "com.example.app"
    private var bundleID: String {
        ProcessInfo.processInfo.environment["APP_BUNDLE_ID"] ?? defaultBundleID
    }

    private let warmupSeconds: UInt32 = 10
    private let captureSeconds: UInt32 = 30

    override func setUpWithError() throws { continueAfterFailure = false }

    // 结束游戏放在 tearDown,保证 post memgraph 抓取时 App 仍存活
    override func tearDownWithError() throws {
        XCUIApplication(bundleIdentifier: bundleID).terminate()   // 结束游戏
    }

    func testGameplayMemory() throws {
        let app = XCUIApplication(bundleIdentifier: bundleID)

        let options = XCTMeasureOptions()
        options.invocationOptions = [.manuallyStart, .manuallyStop]
        options.iterationCount = 1   // 只测一轮(block 跑 iterationCount+1 次,首次 warmup 被忽略)

        measure(metrics: [XCTMemoryMetric(application: app)], options: options) {
            app.launch()                                          // 启动游戏
            XCTAssertTrue(app.wait(for: .runningForeground, timeout: 15))
            sleep(warmupSeconds)                                  // 延时 10s
            startMeasuring()                                      // 开始采集
            sleep(captureSeconds)                                 // 延时 30s
            stopMeasuring()                                       // 结束采集
        }
    }
}

两个关键点

• 只测一轮:XCTMeasureOptions.iterationCount 控制测量次数;measure 实际跑 iterationCount+1 次(首次是被忽略的 warmup)。设 1 后指标 measurements 只有 1 个值;默认是 5。耗时从 ~5.4min 降到 ~2.5min。
• memgraph 与「结束游戏」的顺序冲突:-enablePerformanceTestsDiagnostics YES 会额外追加一次迭代,在测量迭代开始/结束时分别抓 pre_* / post_* memgraph。post 图在迭代结束那一刻抓取,所以不能在 measure {} 块内提前 app.terminate(),否则 post 图抓不到存活进程。把「结束游戏」挪到 tearDownWithError()。

3. 用 idevice 运行(开启 memgraph 诊断)

XCDevice.test() 支持 enable_performance_diagnostics,内部追加 -enablePerformanceTestsDiagnostics YES:

from idevice.device import XCDevice

xc = XCDevice("/path/to/XPrj")   # Unity 导出工程 / .xcodeproj 路径
result_bundle = xc.test(
    test_project="examples/UITestsTemplate/UITestsTemplate.xcodeproj",
    scheme="UITests",
    udid="00008101-00161DAE14B8001E",
    only_testing=["UITests/GameplayUITests/testGameplayMemory"],
    enable_performance_diagnostics=True,
)
print(result_bundle)   # .../build/TestResults.xcresult

等价的 xcodebuild 命令:

xcodebuild test \
  -project examples/UITestsTemplate/UITestsTemplate.xcodeproj \
  -scheme UITests \
  -destination 'platform=iOS,id=00008101-00161DAE14B8001E' \
  -only-testing:UITests/GameplayUITests/testGameplayMemory \
  -enablePerformanceTestsDiagnostics YES \
  -resultBundlePath ./TestResults.xcresult

设备 UDID 获取:xcrun devicectl device info details --device <coredevice-id> 看 hardwareProperties.udid。

4. 导出并查看 memgraph

xcrun xcresulttool export attachments \
  --path TestResults.xcresult \
  --output-path memgraph_output

导出的附件是一个 memgraphset 的 .tar.gz(文件名为 UUID .gz,真实名见 manifest.json 的 suggestedHumanReadableName),解包后得到两张图:

pre_TrashDash_<时间>.memgraph     # 测量迭代开始
post_TrashDash_<时间>.memgraph    # 测量迭代结束(相隔 ≈30s 采集窗口)

tar -xzf <uuid>.gz -C extracted

5. 分析

# pre/post 增长对比
heap -diffFrom pre_*.memgraph post_*.memgraph

# 泄漏 / 大对象 / 虚存摘要
leaks --fullContent post_*.memgraph
heap post_*.memgraph -sortBySize
vmmap --summary post_*.memgraph

也可 open *.memgraph 用 Xcode 可视化查看。

实测样例(iPhone 12 Pro / iOS 26.3.1,com.rm42.TrashDash):

项	pre	post
Physical footprint	411.1 MB	413.0 MB
Physical footprint (peak)	443.1 MB	443.1 MB

XCTMemoryMetric 指标:峰值物理内存 ≈456 MB,泄漏计数 84。

注意事项 / 踩坑总结

1. memgraph 仅真机可靠,模拟器不生成。
2. 必须加 -enablePerformanceTestsDiagnostics YES,否则只有内存数值、没有 .memgraph。
3. shouldUseLaunchSchemeArgsEnv 必须为 NO,否则 scheme 里 TestAction 的环境变量(APP_BUNDLE_ID)被忽略。
4. 测试 runner 需 DEVELOPMENT_TEAM 才能在真机签名运行。
5. app.terminate() 不能放在 measure {} 块内(会破坏 post memgraph 抓取),放 tearDown。
6. XCDevice.test() 每次运行前会 rmtree 同名 TestResults.xcresult;要留存结果用 result_bundle_path= 指定不同路径,或及时复制 memgraphset。
7. iterationCount 最小有效值为 1(=1 warmup + 1 measured);设 0 无测量结果。

推荐组合

固定独立 UITest 工程(方案一)+ APP_BUNDLE_ID 环境变量切换被测 App + iterationCount=1 单轮 + enable_performance_diagnostics=True + xcresulttool export attachments 导出 → heap -diffFrom 分析增量。Unity 重导出 App 工程不影响测试工程,维护成本最低。

[nzcv]

XCUITest 真机访问局域网后端（192.168.1.9:8080）连不上 —— 本地网络隐私权限

场景：独立 XCUITest 工程驱动内存测量，测试代码里用 URLSession 轮询 Mac 上的 FastAPI 后端 http://192.168.1.9:8080/api/...。同一 Wi-Fi 下「访问不了」，但手机浏览器却能正常打开。

排查结论（逐层定位）

1. 后端正常：uvicorn 监听 *:8080（所有网卡），Mac IP 就是 192.168.1.9，防火墙关闭；本机 curl http://192.168.1.9:8080/api/health 返回 {"status":"ok"}。
2. / 返回 404 是正常的：后端只定义了 /api/...，没有根路由。浏览器打开 http://192.168.1.9:8080/ 一定是 Not Found，别被误导，要测就测 /api/health。
3. 手机浏览器能访问 → 网络通、ATS 也不是问题。
4. 真正原因：EndlessRunnerTest-Runner 的网络权限里只有「蜂窝数据」，没有「无线局域网与本地网络」开关 → 这是 iOS 14+ 的本地网络隐私权限（Local Network Privacy） 没授权。访问 192.168.x.x 这类局域网 IP 必须有该权限，否则系统静默拦截；浏览器是系统应用早已授权，所以能通。

参考：Apple TN3179《Understanding local network privacy》。自动生成的 XCTRunner 本身已带 NSLocalNetworkUsageDescription，所以 iOS 18 也能弹出授权框。

解决方案（UI 测试里授权 + 缓存）

可靠做法：把 XCTRunner 切到前台 → 发一个请求触发系统授权弹窗 → 用代码点「允许」。授权会被系统缓存，之后每次跑测试不再弹。

同时把「网络一报错就 XCTFail」改成静默轮询重试，否则首个连接错误会直接终止测试，弹窗都来不及点。

关键代码（Swift / XCUITest）

override func setUpWithError() throws {
    continueAfterFailure = false
    grantLocalNetworkPermissionIfNeeded()
}

private func grantLocalNetworkPermissionIfNeeded() {
    // 系统把弹窗归属给前台 App，所以先把 XCTRunner 切前台再发请求
    let runner = XCUIApplication(bundleIdentifier: Self.runnerBundleIdentifier) // 默认 com.idevice.EndlessRunnerTest.xctrunner
    runner.activate()

    let probe = URLSession.shared.dataTask(with: Self.url(path: "/api/health")) { _, _, _ in }
    probe.resume()

    let springboard = XCUIApplication(bundleIdentifier: "com.apple.springboard")
    let alert = springboard.alerts.firstMatch
    guard alert.waitForExistence(timeout: 10) else { return } // 没弹 = 已决定（缓存），直接返回

    for label in ["Allow", "允许", "允許"] {
        let button = alert.buttons[label]
        if button.exists { button.tap(); return }
    }
    // 兜底：本弹窗的“允许”是最后一个按钮
    let buttons = alert.buttons
    if buttons.count > 0 { buttons.element(boundBy: buttons.count - 1).tap() }
}

// 轮询：网络错误静默重试，不 XCTFail
private func waitForOK(at url: URL) {
    while true {
        if let json = Self.fetchJSON(from: url),
           json["status"] as? String == "ok" {
            return
        }
        sleep(1)
    }
}

Runner bundle id 规律

UI 测试 target 的 bundle id 加后缀 .xctrunner 即 Runner 的 bundle id：

com.idevice.EndlessRunnerTest  →  com.idevice.EndlessRunnerTest.xctrunner

操作步骤

1. 重新 build-for-testing 并跑测试，让新代码上设备。
2. 首次运行会弹「"…Runner" 想访问本地网络上的设备」——代码自动点允许；万一机型/语言没点上，手动点一次「允许」，之后缓存。
3. 放行测量信号（否则一直轮询等待）：

curl -X POST http://192.168.1.9:8080/api/control/<device_id>/start
curl -X POST http://192.168.1.9:8080/api/control/<device_id>/stop

易混淆点小结

• 别用 / 验证后端，用 /api/health（/ 必 404）。
• 手机浏览器能访问 ≠ App 能访问：浏览器已有本地网络权限，App 需单独授权。
• 这是「本地网络隐私权限」问题，不是 ATS、不是防火墙、不是 uvicorn 绑定（0.0.0.0 已 OK）。
• 授权弹窗只会在 前台 App 发起本地网络请求 时出现，所以必须先 runner.activate()。

[nzcv]

XCUITest 测量期间自动点掉系统弹窗（每 1s 检查、持续 30s）

场景：在 XCTMemoryMetric 长跑测量中，需要在不影响现有测量业务的前提下，定期检查系统弹窗（如本地网络 / 权限提示），出现时默认点第一个按钮。

关键坑：后台线程跑 XCUI 查询会崩

最初把轮询放到后台队列里：

DispatchQueue.global(qos: .utility).async {
    let deadline = Date().addingTimeInterval(30)
    while Date() < deadline {
        let alert = springboard.alerts.firstMatch
        if alert.exists { ... }          // ❌ 在这里抛异常
        Thread.sleep(forTimeInterval: 1)
    }
}

运行时报：

Current context must not be nil (NSInternalInconsistencyException)

原因：XCUITest 的元素查询 / 交互（alert.exists、.tap() 等）必须运行在持有 XCTestCase 测试上下文的主线程上。DispatchQueue.global() 后台线程没有这个上下文，一执行查询就崩。

解决思路

不开后台线程，而是把轮询放回主线程，并且只利用 measure 块本来就在空等控制信号的那段空闲时间来做检查：

• 用 signal.wait(timeout: .now() + 1) 代替原来的阻塞式 signal.wait()；
• 每次 1s 超时就检查一次系统弹窗，存在则点第一个按钮；
• 信号一旦到达立即返回，业务语义与原阻塞等待完全一致；
• 超过 30s 监控窗口后停止轮询、退回普通阻塞等待，绝不会因超时提前放行而破坏业务。

这样：① 始终在合法测试上下文里（不再崩）；② 不引入任何额外阻塞、不改变现有流程。

实现

/// 阻塞当前（主/测试）线程直到 signal 被触发，语义与 signal.wait() 一致。
/// 空闲期间每秒轮询一次系统弹窗并点掉第一个按钮，最多持续 watchDuration 秒。
private func wait(
    _ signal: DispatchSemaphore,
    dismissingSystemAlertsFor watchDuration: TimeInterval,
    interval: TimeInterval = 1
) {
    let springboard = XCUIApplication(bundleIdentifier: "com.apple.springboard")
    let watchDeadline = Date().addingTimeInterval(watchDuration)

    while signal.wait(timeout: .now() + interval) == .timedOut {
        guard Date() < watchDeadline else {
            signal.wait()   // 超出监控窗口：退回普通阻塞等待
            return
        }
        let alert = springboard.alerts.firstMatch
        if alert.exists {
            let buttons = alert.buttons
            if buttons.count > 0 {
                buttons.element(boundBy: 0).tap()   // 默认点第一个
            }
        }
    }
}

调用处（替换原来的 startSignal.wait() / stopSignal.wait()）：

app.launch()
XCTAssertTrue(app.wait(for: .runningForeground, timeout: 30))

// 等待 /api/startMeasuring；空闲时每 1s 点掉系统弹窗，最多 30s
wait(startSignal, dismissingSystemAlertsFor: 30)
startMeasuring()

// 等待 /api/stopMeasuring；同样的弹窗处理
wait(stopSignal, dismissingSystemAlertsFor: 30)
stopMeasuring()

小结

做法	结果
后台线程 DispatchQueue.global 轮询 XCUI	❌ Current context must not be nil
主线程 + 把轮询嵌进 semaphore.wait(timeout:) 空闲期	✅ 不崩、零额外阻塞、不改业务

要点：XCUITest 元素查询只能在主测试线程上跑；想做并发式的弹窗监控，正确姿势是复用主线程本来就在等待的空闲时间，而不是另起后台线程。

[nzcv]

XCTMemoryMetric 报错 Invalid parameter not satisfying: _data(harvestData 断言)

真机跑 XCUITest 用 XCTMemoryMetric 测安装包内存,启动即崩:

*** Assertion failure in -[MXMMemoryMetric harvestData:error:], MXMMetric.m:279
EndlessRunnerTest.swift:39: error: ... testInstalledTrashDashMemory : Invalid parameter not satisfying: _data (NSInternalInconsistencyException)

当时的疑问:是不是没加 -enablePerformanceTestsDiagnostics YES?(答案:不是)

结论先行

1. 跟 -enablePerformanceTestsDiagnostics YES 无关。 该 flag 只决定测试失败/回归时是否额外抓诊断数据(非内存指标抓 ktrace、内存指标抓 memgraph 附件),不参与 harvestData 采基础 footprint 这一步,开不开都不会消除这个断言。
2. 真正根因:invocationOptions 与 stopMeasuring() 不匹配。 只设了 .manuallyStart,却在 block 里显式调用了 stopMeasuring(),属于 API 误用,导致测量窗口被关两次,block 结束时 memory metric 去 harvest 拿到 nil → 断言。这也解释了"进程没死也会报错"。

触发原理

• XCTMemoryMetric 在测量窗口关闭那一刻读取目标进程内存 footprint。
• Apple 契约:stopMeasuring() 只能在 invocationOptions 含 .manuallyStop 时调用;startMeasuring() 只能在含 .manuallyStart 时调用。
• WWDC21 官方范例中,只用 [.manuallyStart] 时是靠 block 自然结束来停止,并不调用 stopMeasuring()。
• 本例只有 .manuallyStart 却调了 stopMeasuring():sleep 后先关一次窗口,block 结束框架再停/采一次,此时 meter 已 finished → _data == nil。

错误写法

let options = XCTMeasureOptions()
options.invocationOptions = [.manuallyStart]   // 缺 .manuallyStop
options.iterationCount = 1

measure(metrics: [XCTMemoryMetric(application: app)], options: options) {
    startMeasuring()
    sleep(10)
    stopMeasuring()   // 与 invocationOptions 不匹配 → 误用
}

修复

手动控制开始/结束窗口时,两个选项要成对:

let options = XCTMeasureOptions()
options.invocationOptions = [.manuallyStart, .manuallyStop]   // 成对
options.iterationCount = 1

measure(metrics: [XCTMemoryMetric(application: app)], options: options) {
    startMeasuring()
    sleep(10)
    stopMeasuring()   // 现在是合法的窗口关闭点
}

另一种等价做法:保持 [.manuallyStart] 但删掉 stopMeasuring(),靠 block 自然结束停止。若需要外部(HTTP 控制服务器)手动决定何时停,则必须用 .manuallyStop。

其他注意点

• XCTMemoryMetric 若进程在窗口期内崩溃 / 被 jetsam 杀掉,同样会出现 _data == nil 断言。可在 stopMeasuring() 前用 app.state 兜底确认进程存活(但若是真崩溃要先修 App)。
• 改的是测试代码,需重新 build-for-testing 编进 .xctest,不要 SKIP_BUILD=1。
• 想拿 memgraph 附件时,用带 -enablePerformanceTestsDiagnostics YES 的脚本,并确认 APP_BUNDLE_IDENTIFIER 传对(易出现各脚本 bundle id 不一致的坑)。

推荐组合

[.manuallyStart, .manuallyStop] + 成对的 startMeasuring()/stopMeasuring() + 真机运行 + 保证窗口期内目标进程存活。

[nzcv]

EndlessKeeper：用 Rust CLI 封装 xcodebuild 内存测量流程 + MallocStackLogging 踩坑

把原本的几个 shell 脚本(launch_with_xcodebuild.sh / run_endless_runner_memory_xcuitest.sh)收敛成一个 Rust(clap)CLI EndlessKeeper,提供 run / export / server 三个子命令,驱动物理 iOS 设备上的 XCUITest 内存测量(XCTMemoryMetric),并导出内存快照(memgraph)。期间发现 MallocStackLogging 被错误地加到了 Runner 进程上,记录原因与修法。

子命令设计

• run:xcodebuild ... build-for-testing → 用 PlistBuddy 改写生成的 .xctestrun(注入环境变量)→ xcodebuild -xctestrun ... test-without-building -only-testing:<id>。
• export:xcrun xcresulttool export attachments,再递归筛出 memgraph 类附件(*.memgraphset / *.memgraph / *memgraphset*.tar.gz)。
• server:占位(todo)。

关键默认值:

• --device-udid 默认 00008101-00161DAE14B8001E(只给 UDID 时展开成 platform=iOS,id=<UDID>;--destination 优先级更高,原样透传给 xcodebuild -destination)。
• --result-bundle 与 export --result-bundle 共用默认路径 build/EndlessRunnerTest/EndlessRunnerTest.xcresult,export --output 默认 build/EndlessRunnerTest/attachments,这样 run 产出、export 直接消费,无需传参。
• run 默认带 -enablePerformanceTestsDiagnostics YES(--performance-diagnostics false 可关)。
• run 默认开启 stack logging(--stack-logging false 可关)。

--destination 是什么

直接传给 xcodebuild -destination,逗号分隔的 key=value,用来指定运行目的地:

platform=iOS,id=00008101-00161DAE14B8001E      # 真机,按 UDID
platform=iOS Simulator,name=iPhone 15,OS=17.5  # 模拟器
generic/platform=iOS                            # 通用占位

MallocStackLogging 踩坑

现象

日志里出现:

EndlessRunnerTest-Runner(6082) MallocStackLogging: could not tag MSL-related memory as no_footprint ... No such file or directory (2)
EndlessRunnerTest-Runner(6082) MallocStackLogging: recording malloc (and VM allocation) stacks using lite mode

行首是 Runner 进程,不是被测 app。

根因

最初把 MallocStackLogging=1 注入进 .xctestrun 的 EnvironmentVariables / TestingEnvironmentVariables,而这些是 Runner 进程的环境变量。libmalloc 在进程启动时读到它,于是 Runner 自己也开了 MSL(副作用)。我们真正想要的是被测 app 带 MSL。

补充:XCUIApplication 不会把 Runner 的环境变量自动传给被测 app,所以必须在测试里显式设置 app.launchEnvironment。

影响

could not tag ... no_footprint(No such file or directory)在 iOS 真机上基本必现:把 MSL 记账内存排除出 footprint 的机制在 iOS 上不可用。后果是 任何开了 MSL 的进程,其 footprint 都会被 MSL 自身开销抬高。对 app 而言,这会让 XCTMemoryMetric 量到的内存偏高,且与「不开 MSL」的跑分不可比。

修法(让 MSL 只作用在 app 上)

1. Rust 端不再注入会触发 Runner 开 MSL 的 MallocStackLogging,改注入私有信号量 APP_STACK_LOGGING=1:

if args.stack_logging {
    // Signal only; the test forwards MallocStackLogging to the app's
    // launch environment. Injecting MallocStackLogging here would also
    // enable MSL on the runner process itself (unwanted overhead).
    plist::set_env_var(&xctestrun, env_path, "APP_STACK_LOGGING", "1")?;
}

2. Swift 端读这个信号量,只把 MallocStackLogging=1 设到 app 的 launch environment:

// Config
static var stackLogging: Bool { env("APP_STACK_LOGGING") == "1" }

// relaunchApp(),冷启动前设置
if Config.stackLogging {
    app.launchEnvironment["MallocStackLogging"] = "1"
}
app.launch()

取舍

• 要「带分配调用栈的 memgraph」(查泄漏)→ 开 MSL(--stack-logging true),但 footprint 数值偏高。
• 要「准确 footprint 基线」→ 关 MSL(--stack-logging false)。
• 建议把两者作为两种独立跑法,不要混用比较。