revenuecat-testing

RevenueCat 测试

帮助开发者在发布前系统地验证 RevenueCat 集成是否正常工作，将“我接入了 RevenueCat，它到底能不能用？”转化为一份具体、可检查的 QA 计划。完整的用例矩阵、测试方法、平台差异，以及每个用例的可验证信号都列在 references/use_cases.md 中。请阅读该文件，了解确切的事件名称和前置条件；本文是操作指南。

组织原则： RevenueCat 的每种行为都有一个可验证信号——特定的仪表板事件（INITIAL_PURCHASE、TRANSFER、EXPIRATION、PRODUCT_CHANGE、CANCELLATION）、period_type 值，或 CustomerInfo/调试日志状态。测试不是“应用有没有崩溃”，而是“客户的历史记录中是否出现了包含正确字段的预期事件”。务必将测试与其信号关联起来，否则它就不算真正的测试。

如何使用此技能

1. 了解设置信息：平台（iOS / Android / 跨平台 / Web 账单）、SDK（原生、RN、Flutter 等）、是否已启用调试日志和沙盒账号，以及他们具体想验证什么，或为什么认为出了问题。
2. 先确认前置条件——大多数“购买无法使用”的问题，都是购买前就能发现的配置问题：
   • 在 configure() 之前启用调试日志（iOS Purchases.logLevel = .debug；Android setLogLevel(LogLevel.DEBUG)），并检查是否有 "Invalid Product Identifiers" 和错误级别日志。处理好这些问题后再测试购买流程。
   • 配置好沙盒环境；如果涉及账号切换，请准备多个沙盒测试 ID。
   • 引导用户使用调试浮层（debugRevenueCatOverlay() / DebugRevenueCatBottomSheet），以便预览产品包并快速运行测试购买。
3. 从参考资料中将目标映射到用例，并制定计划（如下）。

参考实现（尤其适用于 Flutter）： RevenueCat 提供官方 Purchase Tester 示例应用，地址为 github.com/RevenueCat/purchases-flutter/tree/main/revenuecat_examples/purchase_tester。这是一个可运行的应用，用于测试本技能涵盖的流程，其中包含专门用于产品更改（product_change_testing_screen.dart）、付费墙和付费墙页脚、客户中心、虚拟货币、挽回优惠以及自定义付费墙展示测试的屏幕，还包含端到端集成测试 integration_test/app_test.dart。请 Flutter 用户使用该应用：（a）运行已知正常的构建，以判断问题出在他们的代码，还是商店/RevenueCat 配置；（b）参照 app_test.dart 为自己的 integration_test 编写 widget 测试。对于非 Flutter SDK，RevenueCat 在各 SDK 仓库中也提供了对应的 Purchase Tester 应用。

五个测试领域

从 references/use_cases.md 中提取具体条目；以下是测试范围：

1. 订阅生命周期 — 购买、免费试用／优惠首购（period_type = TRIAL／INTRO）、续订、升级／降级（PRODUCT_CHANGE）、取消、到期、退款。务必指出的平台注意事项： iOS 沙盒环境不支持退款 — App Store 会将用户引导至 Apple 支持，且 CANCELLATION／CUSTOMER_SUPPORT 事件可能需要约 24 小时才会出现；Google Play 退款由控制台操作。
2. 配置 — 匿名与已识别的 App User ID（通过调试日志和 CustomerInfo 验证）、产品组合展示，以及登录／登出 — 主要风险是账户之间发生非预期的数据合并。
3. 恢复流程 — 账户切换／转移矩阵。这是价值最高、最容易出错的领域：syncPurchases()、恢复到新 ID、三 ID 冲突情形（转移到空 ID 成功，但转移到已拥有订阅的 ID 时出错），以及禁用转移时的行为。整个流程的判断信号是是否触发 TRANSFER 事件（或是否按预期未触发）。
4. 付费墙 — 展示与购买、本地化（设备／商店账户所在国家 → 语言和本地化价格），以及新用户的优惠首购资格展示。
5. RevenueCat Billing（Web） — 购买、试用自动转为付费、到期。

交付内容

• QA 测试计划 — 列出适用于其应用的用例清单（仅面向移动端的应用跳过 Web Billing，没有试用的应用跳过试用），每行格式为：操作 → 预期事件／信号 → 查看位置。这是主要交付内容；请整理成可直接复制到 QA 文档或问题跟踪器中的格式。
• 诊断具体故障 — 对照参考资料判断原因：是前置条件问题（产品 ID 无效、日志已关闭、沙盒账户错误）？对信号的预期有误（例如，在禁用转移时仍期待 TRANSFER）？还是平台差异（iOS 退款无法在沙盒中测试）？指出预期事件及其显示位置，再从用户实际看到的情况倒推原因。
• 恢复／转移说明 — 如果用户对账户切换感到困惑，请针对具体 ID 配置说明每个 ID 预期会出现 TRANSFER 还是错误，因为这是文档着墨最多的领域。
• 沙盒设置指南 — 根据用户的平台和 SDK 调整前置条件部分的说明。

每条建议都要关联到 references/use_cases.md 中可验证的信号 — 该文件底部的事件速查表列出了每个事件所能证明的内容。