revenuecat-testing-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

revenuecat-testing-setup: set up a testing environment for RevenueCat purchases

revenuecat-testing-setup：搭建无需真实付费的RevenueCat购买测试环境

Use this skill when the user wants to test purchases against RevenueCat without charging real money. Each store has its own testing channel, and each channel has different fidelity and iteration cost.

当用户希望在不产生真实付费的情况下测试基于RevenueCat的购买功能时，可使用此技能。每个应用商店都有各自的测试渠道，不同渠道的保真度和迭代成本各不相同。

1. Detect the platform

1. 检测平台

Inspect the working directory and pick the first match, from top to bottom:

React Native:
```
package.json
```
has a
```
react-native-purchases
```
entry, or
```
react-native
```
as a dependency → read
```
platforms/react-native.md
```
. If
```
expo
```
is also a dependency, note it as an Expo project.
Flutter:
```
pubspec.yaml
```
exists at the project root → read
```
platforms/flutter.md
```
.
Kotlin Multiplatform:
```
build.gradle.kts
```
contains a
```
kotlin { … }
```
multiplatform source sets block, or depends on
```
com.revenuecat.purchases:purchases-kmp*
```
→ read
```
platforms/kmp.md
```
.

Android (native):

build.gradle(.kts)

applies

com.android.application

(and is not KMP) → read

platforms/android.md

iOS (native):

Package.swift

*.xcodeproj

*.xcworkspace

, or

Podfile

at the project root → read

platforms/ios.md

If several match (e.g. an

ios/

folder inside a Flutter project), pick the outermost project, the one that owns the build. If still ambiguous, ask the user which platform they want to configure.

检查工作目录，从上到下选择第一个匹配项：

React Native：
```
package.json
```
中包含
```
react-native-purchases
```
条目，或依赖
```
react-native
```
→ 查看
```
platforms/react-native.md
```
。如果同时依赖
```
expo
```
，则标记为Expo项目。
Flutter：项目根目录存在
```
pubspec.yaml
```
→ 查看
```
platforms/flutter.md
```
。

Kotlin Multiplatform：

build.gradle.kts

包含

kotlin { … }

多平台源码集块，或依赖

com.revenuecat.purchases:purchases-kmp*

→ 查看

platforms/kmp.md

。

Android（原生）：
```
build.gradle(.kts)
```
应用了
```
com.android.application
```
（且非KMP项目） → 查看
```
platforms/android.md
```
。
iOS（原生）：项目根目录存在
```
Package.swift
```
、
```
*.xcodeproj
```
、
```
*.xcworkspace
```
或
```
Podfile
```
→ 查看
```
platforms/ios.md
```
。

如果多个平台匹配（例如Flutter项目内包含

ios/

文件夹），请选择最外层的项目，即负责构建的项目。若仍存在歧义，请询问用户想要配置哪个平台。

2. Shared concepts (all platforms)

2. 通用概念（所有平台）

You cannot charge real money during development

开发过程中不能产生真实付费

Each store has a dedicated testing channel. Choosing the right channel depends on what you want to test.

每个应用商店都有专门的测试渠道。选择合适的渠道取决于你想要测试的内容。

Testing channels by fidelity vs iteration cost

按保真度与迭代成本划分的测试渠道

Higher fidelity exercises more of the real purchase pipeline. Lower fidelity iterates faster.

RevenueCat Test Store (lowest fidelity, fastest iteration, deterministic). A synthetic store hosted by RevenueCat. The SDK is configured with a
```
test_…
```
API key from the dashboard. Purchases open a Test Store dialog where you pick the outcome by hand: Successful Purchase, Failed Purchase, or Cancel. Purchases trigger entitlements, update
```
CustomerInfo
```
, and appear on the dashboard, but no Apple or Google call happens. Best for paywall iteration, integration tests, and CI smoke runs.
iOS StoreKit Configuration File (low fidelity, Apple synthetic). Xcode stubs the store locally. Purchases succeed instantly with no App Store Connect round trip. Useful when you need StoreKit specific behavior. RevenueCat transactions in this mode may or may not appear on the dashboard depending on SDK version and intended routing, so it is not a faithful dashboard test.
iOS Sandbox (real sandbox Apple ID) / Android Internal Testing (license tester). Real store backends, real RevenueCat dashboard ingestion, real receipts. Slower to iterate: build, install, wait for Play propagation or App Store Connect to register the product.
TestFlight (iOS) / Closed or Open Testing (Android). Behaves very close to production. Receipts are production style. Transactions land in the production RevenueCat dashboard, not the Sandbox view.
Production. Real money. Do not use for testing.

Start with the lowest fidelity that answers the question, then move up. UI and paywall iteration belongs in the fast channel. "Does my entitlement actually flip?" belongs in sandbox or internal testing.

保真度越高，越能模拟真实购买流程的更多环节；保真度越低，迭代速度越快。

RevenueCat Test Store（保真度最低、迭代最快、结果可预测）：由RevenueCat托管的模拟商店。SDK使用控制台中带有
```
test_
```
前缀的API密钥进行配置。购买操作会打开Test Store对话框，你可以手动选择结果：购买成功、购买失败或取消。购买会触发权益更新、更新
```
CustomerInfo
```
并显示在控制台上，但不会调用苹果或谷歌的接口。最适合付费墙迭代、集成测试和CI冒烟测试。
iOS StoreKit配置文件（低保真度，苹果模拟环境）：Xcode在本地模拟商店。购买会立即成功，无需与App Store Connect进行往返通信。当你需要测试StoreKit特定行为时非常有用。在此模式下，RevenueCat交易是否会显示在控制台上取决于SDK版本和预设路由，因此无法作为控制台的忠实测试环境。
iOS沙箱（真实沙箱Apple ID）/ Android内部测试（许可证测试员）：真实的商店后端、真实的RevenueCat控制台数据接收、真实的收据。迭代速度较慢：需要构建、安装，等待Play商店传播或App Store Connect注册产品。
TestFlight（iOS）/ 封闭或开放测试（Android）：行为与生产环境非常接近。收据为生产环境格式。交易记录会进入生产环境的RevenueCat控制台，而非沙箱视图。
生产环境：真实付费。请勿用于测试。

从能满足测试需求的最低保真度渠道开始，再逐步升级。UI和付费墙迭代适合使用快速渠道；而“我的权益是否真的会更新？”这类测试适合在沙箱或内部测试渠道进行。

Test Store: when to reach for it before sandbox

Test Store：何时优先选择它而非沙箱

RevenueCat's Test Store is a synthetic store provider configured per project on the dashboard. It produces real RevenueCat backend records (

CustomerInfo

updates, entitlement transitions, dashboard transactions) without calling App Store or Google Play. The price of that speed is fidelity. Test Store does not simulate Ask to Buy approval flows, region specific pricing, server side receipt validation specifics, store level review or rejection paths, or full subscription renewal cadence (Test Store renews up to five times on a compressed clock).

Use Test Store when you want to iterate on UI quickly, write integration tests with deterministic outcomes, or run CI checks. Move up to App Store Sandbox or Google Play Internal Testing for anything that exercises store side behavior.

Setup. In the dashboard, go to Apps and providers → Test configuration section → Test Store → Create / Enable. The Test Store API key appears under Project Settings → API keys with a

test_

prefix. Configure the SDK with the test key in debug builds and the production key (

appl_…

goog_…

) in release builds. The platform files show the per platform key swap pattern.

Test Store keys must never ship to production. Gate the key behind your build configuration so release binaries cannot route through Test Store.

RevenueCat的Test Store是在控制台按项目配置的模拟商店提供商。它会生成真实的RevenueCat后端记录（

CustomerInfo

更新、权益变更、控制台交易记录），但不会调用App Store或Google Play接口。这种速度的代价是保真度。Test Store不会模拟“请求购买批准”流程、地区特定定价、服务器端收据验证细节、商店层面的审核或拒绝路径，也不会模拟完整的订阅续订周期（Test Store会在压缩时钟下最多续订五次）。

当你想要快速迭代UI、编写结果可预测的集成测试或运行CI检查时，使用Test Store。任何需要测试商店端行为的场景，请升级到App Store沙箱或Google Play内部测试。

设置步骤：在控制台中，进入应用与提供商 → 测试配置 部分 → Test Store → 创建/启用。带有

test_

前缀的Test Store API密钥会显示在项目设置 → API密钥下。在调试构建中使用测试密钥配置SDK，在发布构建中使用生产密钥（

appl_…

goog_…

）。各平台文档展示了对应平台的密钥切换方式。

Test Store密钥绝对不能用于生产环境。通过构建配置限制密钥，确保发布版本不会通过Test Store路由请求。

Sandbox transactions appear separately on the dashboard

沙箱交易在控制台中单独显示

The RevenueCat dashboard has a toggle between Sandbox and Production views. Sandbox purchases only appear under Sandbox. If a test transaction does not appear there, the SDK is not reporting it (check API key,

configure

call, and network), or the purchase was against a StoreKit config file that does not hit RevenueCat's backend.

RevenueCat控制台有沙箱和生产环境视图的切换按钮。沙箱购买仅会显示在沙箱视图中。如果测试交易未出现在此处，说明SDK未上报（检查API密钥、

configure

调用和网络），或者购买是针对不会触发RevenueCat后端的StoreKit配置文件进行的。

Accelerated renewal in sandbox

沙箱中的加速续订

Subscription renewals run on accelerated test clocks in sandbox. This lets you exercise renewal logic in minutes instead of weeks.

iOS sandbox renewal cadence (per Apple's documentation): daily → every 3 minutes, weekly → every 3 minutes, monthly → every 5 minutes, 2 months → every 10 minutes, 3 months → every 15 minutes, 6 months → every 30 minutes, yearly → every hour. Subscriptions auto-renew a maximum of 6 times then expire.
Android sandbox renewal cadence is documented in Google Play Console → Subscriptions testing. License tester subscriptions renew on the same accelerated clock.

在沙箱环境中，订阅续订会使用加速测试时钟。这让你可以在数分钟内而非数周内测试续订逻辑。

iOS沙箱续订周期（根据苹果文档）：每日→每3分钟，每周→每3分钟，每月→每5分钟，2个月→每10分钟，3个月→每15分钟，6个月→每30分钟，每年→每小时。订阅最多自动续订6次后到期。
Android沙箱续订周期记录在Google Play控制台 → 订阅测试中。许可证测试员的订阅会使用相同的加速时钟。

Use a fresh test user for first purchase flows

使用新的测试用户测试首次购买流程

Purchase history is attached to the test account (sandbox Apple ID or license tester Gmail) and persists. Testing "first purchase" logic, introductory offers, or free trials against an account that has already used them produces misleading results. Create a new sandbox tester for clean first purchase scenarios.

购买记录会附加到测试账户（沙箱Apple ID或许可证测试员邮箱）并持久保存。如果使用已用过首次购买、介绍性优惠或免费试用的账户测试这些逻辑，会产生误导性结果。请创建新的沙箱测试员来测试干净的首次购买场景。

Confirm against the dashboard, not the device

以控制台为准，而非设备

A purchase succeeding on the device is not the same as RevenueCat recording it. Always confirm:

The transaction appears on the RevenueCat dashboard (Sandbox view).
The expected appUserID owns the transaction.
The expected entitlement is now active on that user.

If the device shows success but the dashboard shows nothing, something is wrong in the configuration path, not the store.

设备上显示购买成功并不等同于RevenueCat已记录该交易。请始终确认：

交易记录出现在RevenueCat控制台的沙箱视图中。
预期的appUserID拥有该交易记录。
该用户的预期权益已激活。

如果设备显示成功但控制台无记录，说明配置路径存在问题，而非商店端问题。

3. Implementation

3. 实施步骤

Read the platform file that matches detection:

```
platforms/ios.md
```
```
platforms/android.md
```
```
platforms/kmp.md
```
```
platforms/flutter.md
```
```
platforms/react-native.md
```

查看与检测结果匹配的平台文档：

```
platforms/ios.md
```
```
platforms/android.md
```
```
platforms/kmp.md
```
```
platforms/flutter.md
```
```
platforms/react-native.md
```

4. Verify

4. 验证

Your testing environment is set up once:

A test purchase succeeds end to end from a test user.
The transaction appears on the RevenueCat dashboard Sandbox view, attached to the appUserID you logged in with.
The expected entitlement is active on
```
customerInfo
```
after the purchase completes.
Restoring purchases on a fresh install of the app restores the entitlement to the same test user.

If any of those four steps fails, the environment is not ready. The

revenuecat-troubleshoot

skill covers the usual root causes.

满足以下条件时，测试环境即搭建完成：

测试用户的购买流程从端到端成功完成。
交易记录出现在RevenueCat控制台的沙箱视图中，并与你登录使用的appUserID关联。
购买完成后，
```
customerInfo
```
中的预期权益已激活。
在全新安装的应用中恢复购买，可将权益恢复到同一测试用户账户。

如果以上四个步骤中有任何一个失败，说明环境尚未准备就绪。

revenuecat-troubleshoot

技能涵盖了常见的根本原因。