一套 commonTest 跑通 iOS/Android:Compose Multiplatform 订阅怎么测

一句话版:业务写在 commonMain、付费墙 UI 双端一致,但 Google Play 与 StoreKit 仍是两套沙盒 — JVM 里根本模拟不了购买。RevenueCat 的 Test Store(test_ API key)把开发期购买收到自家沙盒;再用 PaywallsRepository + FakePaywallsRepository 把 SDK 挡在 commonTest 外,单元 / 仪器化 / 平台边缘 三层分工,同一套 Kotlin 逻辑从 PR 测到真收据。

为什么值得读

Compose Multiplatform(CMP) 把订阅 UI 和 CustomerInfo 流统一到一份 Kotlin 里,很爽;坐到测试台前却常发现:同一产品仍要维护两套 license tester、StoreKit 配置文件、两套 CI,而且 Play 与 App Store 的购买记录互不相通。更糟的是:Google Play 无法在 JVM 单测里假购买;StoreKit 配置又只活在模拟器 —— 标准建议是「全扔集成测试」,结果 真正碰 Purchases 的路径几乎不测,KMP 的「写一次测一次」在付费边界断掉。

RevenueCat 工程文用官方 demo cat-paywalls-kmp 走通整条链路(文内代码布局与仓库一致,可直接对照抄)。下文压缩:Test Store 接线 → 可测边界 → Fake 单测 → 仪器化三按钮弹窗 → 三层策略与 CI;推广味压到最低,步骤可照抄。

对 移动 indie:订阅往往是唯一变现,却最怕「改一行 gating 逻辑不敢发版」—— 这篇给的是 可重复的测试分层,不是换栈广告。

痛点:一个产品,两套沙盒

原生 Android 订阅测试就要折腾:license tester、内测/封闭轨道、android.test.purchased、BillingClient 各种边角。iOS 再加 StoreKit 配置、沙盒账号、加速续期、TestFlight 限流。双端上架 = 两套流程都要跑,还要自己 reconcile:Play 封闭轨道里买的订阅不会出现在 App Store Connect;StoreKit 沙盒里的 Transaction 也不会走 Android 的 PurchasesUpdatedListener。

单元测试层面更致命:Play 不在 JVM 里模拟购买;StoreKit 配置也进不了 kotlinx-coroutines-test。demo 里 CatArticlesDetailViewModel 一类代码 — customerInfo 的 StateFlow、文章正文是否淡出、CTA 何时出现、网络失败怎么降级 — 与收据来自 Google 还是 Apple 无关,但若 PaywallsRepository.fetchCustomerInfo() 背后必须连真 SDK,这些逻辑永远进不了 commonTest。KMP 省下的重复 UI 代码,常在付费边界把测试优势一并丢掉。

Test Store:开发期别绑两家商店沙盒

RevenueCat Test Store 是平台侧沙盒(非 Play / App Store)。Dashboard 配一次,App 里换 test_ 前缀的 API key(区别于 goog_ / appl_),SDK 走自家购买弹层,而不是拉起原生商店对话框。

用户点 Paywall 上「Subscribe」后,弹层只有三个按钮:Test valid Purchase、Test failed Purchase、Cancel(与仪器化里 Espresso/XCUITest 的 withText 一致,注意 Purchase 首字母大写)。成功路径与线上一致:后端验收据、awaitPurchase 返回 StoreTransaction、CustomerInfo 里 entitlements["premium"].isActive == true,门禁 UI 解锁。另两个按钮覆盖失败与取消,无需手写异常。

要点(可抄):

• SDK purchases-kmp ≥ 2.2.2(demo 钉 2.10.2+17.55.1 量级即可)
• test_ key 仅 debug;打进 release 会被服务端拒绝 — 与 debug 签名同级对待
• 无需 Play Console / ASC 测试账号;模拟器、真机 debug、CI 可用;续期加速(月订约 5 分钟一轮,年订约 1 小时,各最多 5 次续期)
• Dashboard 里 Test Store 购买与生产数据同项目可见 — webhook、CustomerInfo 字段、entitlement 迁移 与上线形态一致,减少「沙盒过了、线上字段不对」的惊吓

开发期把沙盒从两家商店 上移到 RevenueCat,后面 repository/Fake/仪器化才有统一数据面可依赖。

KMP 接线:一行 local.properties + 选 key

Android composeApp/build.gradle.kts — 从 local.properties 注入(文件默认 gitignore):

val localProperties = Properties().apply {  rootProject.file("local.properties").takeIf { it.exists() }    ?.inputStream()?.use { load(it) }}android {  defaultConfig {    buildConfigField("String", "REVENUECAT_TEST_API_KEY","\"${localProperties.getProperty("revenuecat.test.api.key", "")}\"",    )  }  buildFeatures { buildConfig = true }}

本机 local.properties 一行:

revenuecat.test.api.key=test_YOUR_KEY_HERE

Application 里「有 test key 用 test,否则生产」 — 无需单独 product flavor:

val apiKey = BuildConfig.REVENUECAT_TEST_API_KEY  .takeIf { it.isNotBlank() } ?: REVENUECAT_API_KEYPurchases.configure(PurchasesConfiguration(apiKey = apiKey) { appUserId = null })

commonMain不必知道当前连的是 Test Store 还是生产;SDK 按 key 前缀选后端,行为一致。没配 test key 的开发者/干净 CI 自动走生产 key,编译仍过。

iOS: 共享模块起运行时读同一配置;Swift 入口同理 — Purchases.configure(withAPIKey: testStoreApiKey ?? "ios_prod_key"),key 放 .xcconfig / Info.plist / 本地 build setting。

可测边界:PaywallsRepository 挡住 Purchases

即使接了 Test Store,也不该让每个单测依赖 Purchases.sharedInstance — commonTest 里没有 Android Context、BillingClient、StoreKit 监听。

在 core/data 定义唯一出入口:

interfacePaywallsRepository{funfetchOffering(): Flow<Result<Offering>>funfetchCustomerInfo(): Flow<Result<CustomerInfo>>funawaitPurchase(packageId: String): Flow<Result<StoreTransaction>>}

设计要点:

1. 全返回 Flow<Result<…>> — 方便 ViewModel map/stateIn,实现可冷流可缓存
2. 类型来自 purchases-kmp 的 common 模型 — 测试侧可持有(构造能力见下)
3. 全仓库仅 PaywallsRepositoryImpl 一处import Purchases.sharedInstance

生产实现用 flow { … awaitCustomerInfo() … }.flowOn(Dispatchers.IO) 包一层即可。ViewModel、Compose、测试 只面对接口 — 这是 commonTest 能活的前提。

反模式:在 ViewModel 里直接 Purchases.sharedInstance — 每个平台测试都要起 Billing/StoreKit,commonTest 直接废掉。正模式:新加任何 SDK 调用先问「能不能塞进 repository 接口」。

commonTest:别用 MockK,用 Fake + Turbine

KMP 的 commonTest不能依赖 MockK/Mockito(反射代码生成,iosTest 链接会炸)。demo 的 libs.versions.toml 里甚至声明了 MockK 却未使用 — 一旦 convention plugin 让 commonTest 双端跑,共享代码里就不能 import。

可用:kotlin-test、kotlinx-coroutines-test、Turbine。建议在 convention plugin 里给所有 feature 模块统一挂上,避免「想写测却懒得配依赖」;feature 模块自身往往只需 implementation(projects.core.data) 一项测试依赖。

为何 Fake 优于 Mock(即便在 JVM 也成立)

PaywallsRepository 只有三个 Flow<Result<…>> 方法 — 手写 Fake 比堆 every { } 更短。Fake 故意从「全未配置」起步,测试只填当前场景槽位;改一个错误路径不必把其它方法全 stub 一遍。订阅域又常要 有状态 的「先 offering 失败再 customerInfo 成功」—— Fake 的 setter 比 mock 链更接近业务语言。

FakePaywallsRepository 模式(摘自 demo 思路):

• 三个可写槽:offeringResult、customerInfoResult、purchaseResults[packageId]
• 未配置时 emit(Result.failure(IllegalStateException("No customer info configured"))) — 漏配立刻炸,比空 Flow 挂死好查
• 辅助方法:simulateCustomerInfoError()、setPurchaseResult(packageId, result) 等

单测骨架:

@BeforeTestfunsetup() {  Dispatchers.setMain(StandardTestDispatcher())  fakeRepository = FakePaywallsRepository()}@AfterTestfuntearDown() { Dispatchers.resetMain() }@TestfunwhenCustomerInfoFetchFails_stateIsError() = runTest {  fakeRepository.simulateCustomerInfoError("Failed to fetch customer info")val vm = SubscriptionManagementViewModel(fakeRepository)  vm.uiState.test {    assertIs<SubscriptionManagementUiState.Loading>(awaitItem())    testDispatcher.scheduler.advanceUntilIdle()val err = awaitItem()    assertIs<SubscriptionManagementUiState.Error>(err)    assertEquals("Failed to fetch customer info", err.message)    cancelAndIgnoreRemainingEvents()  }}

StateFlow 会先 replay 当前态 → advanceUntilIdle() 再收下一态。Loading / 各类 Error / 取消路径 各用一个 fake setter + Turbine,无网络、无 BillingClient,同文件跑 JVM + iOS target。

Fake 的硬限制:Offering / CustomerInfo 暂无公开构造器 — 「购买成功且 entitlement 激活」 无法在纯 Fake 里断言,必须交给下一层的 Test Store 仪器化测试。这也是三层分工里第 2 层存在的理由,不是 Fake 设计失败。

仪器化:同一枚 Test Store 三按钮

Android androidTest: 放在 composeApp/src/androidTest/...,用 InstrumentationRegistry.getInstrumentation().targetContext(真进程,不是 JVM 单测)。@Before 里 Purchases.configure 钉死 BuildConfig.REVENUECAT_TEST_API_KEY,可加 purchasesAreCompletedBy(REVENUECAT) 与线上一致。测试流程:awaitOfferings() 取 test-offering 下第一个 package → 起 TestPurchaseActivity 触发购买 → 先 delay 约 2s 等 Test Store 弹层进视图树 → Espresso 点 「Test valid Purchase」 → withTimeout(如 30s) 轮询直到回调里 customerInfo.entitlements.active 非空(含真网络验票)。另两按钮:Test failed Purchase — entitlement 仍 inactive、错误能传到 domain;Cancel — SDK 抛 PurchaseCancelled,domain 层应映射为 no-op,别误报成用户可见错误。

iOS XCUITest: XCUIApplication 点 Subscribe → Test valid Purchase → waitForExistence 门禁文案(如「Premium Article」)。与 Android 行数几乎对称。

和纯 StoreKit 配置对比:.storekit 只覆盖 iOS,不进 PaywallsRepository,也不进 RevenueCat Dashboard。CMP 团队若维护两套驱动 + 两套数据面,漂移很快。Test Store 让 同一 commonMain + 同一 key 在双端走同一弹层、同一后端;原生 StoreKit/Play 套件缩到 边缘个案 即可。

若还要测 家长控制、沙盒过期、地区限制,保留 小规模 .storekit / Play closed track — 别用它扛主路径。

三层策略 + CI 三 job(对照表)

CI 形状:

1. ./gradlew allTests — commonTest 全 target,快反馈
2. connectedAndroidTest + 模拟器 — 密钥用 repo secret 写入 local.properties,勿给 fork/release;不必每个 PR 都跑(含真网与续期消耗)
3. xcodebuild test — 同一 Test Store 项目,Dashboard 双端可见

多数覆盖应落在 跑得最勤的第 1 层;避免只剩 closed track + StoreKit 文件那种「慢测才测购买」的倒挂。

原文结语里的三个「小改动」值得记住:沙盒上移到 RevenueCat 把双平台问题收成一套;repository 接口 把 commonTest 从 SDK 里救回来;Fake 替代 MockK 让同一份测试在 JVM 与 Native 目标都能链上。单独看都不大,叠在一起才从「两套测试套件」回到「一套 Kotlin 逻辑、三层 runner」。

踩坑速查(本地 / CI)

译者按

Flutter / React Native 读者:退路在哪

本文栈是 Kotlin CMP + RevenueCat KMP SDK。若你是 Flutter / RN,不必为文换技术栈,下列可原样迁移:

• Test Store 概念仍可用 — Flutter 用 purchases_flutter,RN 用 react-native-purchases,同样是 test_ key + Dashboard Test Store,开发期不必双端各配一套商店沙盒账号;本地用 --dart-define / .env / react-native-config 注入 key,逻辑与 Android local.properties 相同
• 可测边界照样抄: 用 Repository / Service 接口 包住 Purchases,Widget/组件测试、Jest 单测里 手写 Fake(Dart/TS 的 mock 生态比 KMP 友好,但 「只配当前场景槽位」的 Fake 仍比巨型 mock 好读,尤其订阅有多步 Result 链时)
• 三层分工不变: 单测扛状态机 → 集成/E2E(Detox、Maestro、Patrol 等)扛「点 Subscribe → 三按钮 → entitlement 变 true」→ 原生商店边缘个案少量保留
• 常见坑:在 build() 里直接 Purchases.getCustomerInfo() — 与在 ViewModel 里调 SDK 一样,会让测试只能上真机;先抽到 SubscriptionRepository 再谈覆盖率

纪律就两条:SDK 不渗进 UI 状态机;开发期购买尽量走 Test Store,别默认绑 Play/ASC 沙盒。

KMP + RevenueCat 对移动 indie 的价值

• 一份 PaywallsRepository + 一份 Fake* 同时服务 Android/iOS 单测,省掉「逻辑改两遍、测两遍漂移」
• Test Store 让 solo 在笔记本上 就能跑通购买与 webhook 同形的 CustomerInfo,不必等 ASC 沙盒或 Play 内测轨道排期
• 与「只写 UI、购买全扔原生」相比,付费规则留在 commonMain 时,测试投资回报最高 — 尤其适合 小团队、双端同发、订阅是核心变现 的 App

下周可做的最小一步

1. Dashboard 开 Test Store,本机 local.properties 写 test_ key
2. 抽 PaywallsRepository(或你栈里的等价物),现有 Purchases 调用迁到唯一 Impl
3. 为当前订阅 ViewModel 写 1 条失败路径 commonTest(Fake + Turbine/等价物)
4. 再补 1 条androidTest/XCUITest:只测「Test valid Purchase → 门禁解锁」,先别追求全矩阵

对照清单(发版前自检)

[ ] 生产包未打入 test_ API key[ ] ViewModel/Bloc 无直接 Purchases 调用[ ] commonTest 覆盖 Loading / Error / Cancel 至少各 1[ ] 仪器化测过 Test valid Purchase(真网络,CI secret 已配)[ ] 边缘:StoreKit .storekit 或 Play closed track 仅保留必要条数

demo 仓库:cat-paywalls-kmp(与原文 snippet 路径一致);本地要跑仪器化层需自备 RevenueCat 项目与 Test Store key,无额外「必须买的企业功能」才能验证文中三层。

改写自 RevenueCat Engineering《Testing subscriptions on Compose Multiplatform: one test suite for iOS and Android》。本文压缩 Test Store 配置、PaywallsRepository/FakePaywallsRepository、commonTest 与仪器化模式及三层测试/CI 分工,删去文末产品 CTA 与重复推销,并补充 Flutter/RN 对照与移动 solo 最小步骤;代码结构与官方 cat-paywalls-kmp demo 一致。