用途
Polar Testing 是一份针对 Polar 支付集成的测试指南，核心是引导开发者在 Polar 沙箱（sandbox）环境中验证支付流程。沙箱是独立于生产环境的隔离服务器，可以随意试验，不会影响生产数据，也不会处理真实资金。
沙箱环境与设置
沙箱控制台地址为 https://sandbox.polar.sh，API 为 https://sandbox-api.polar.sh/v1。沙箱与生产完全隔离，需要单独的用户账户、组织、访问令牌和 webhook 端点。设置步骤如下：
- 访问 https://sandbox.polar.sh/start；
- 创建新账户（或从组织切换器选择“Go to sandbox”）；
- 创建测试组织；
- 在 Settings → Developers 中生成访问令牌。
SDK 配置时通过 server: "sandbox" 指定沙箱环境（生产环境改为 "production"），指南给出了 TypeScript、Python、Go 三种语言的示例代码。需要注意的沙箱限制包括：订阅在 90 天后自动取消、不处理真实资金、数据与生产隔离。
测试卡号
Polar 使用 Stripe 处理支付，指南列出了测试卡号：成功支付卡包括 Visa 4242 4242 4242 4242、Mastercard 5555 5555 5555 4444、Amex 3782 822463 10005、Discover 6011 1111 1111 1117；拒付测试卡覆盖通用拒绝、余额不足、挂失卡、被盗卡、过期卡、CVC 错误等场景；另有触发 3D Secure 认证的卡号。
本地 Webhook 测试
使用 Polar CLI 可将组织的 webhook 事件直接转发到本地服务器，无需隧道或公网 URL。安装命令为 npm install -g @polar-sh/cli，登录命令为 polar auth login --sandbox。在无浏览器的环境（如 CI、远程机器、云代理）中，可用组织访问令牌替代登录，需要 webhooks:read、webhooks:write、organizations:read 权限，并设置 POLAR_ENVIRONMENT=sandbox。
转发事件使用 polar webhook listen 3000/api/polar/webhook，该命令持续运行，需置于独立终端或后台进程。转发事件的签名使用本地密钥，可用 polar webhook listen --print-secret 获取并写入 .env。发送测试事件使用 polar webhook trigger order.paid，支持 --list --json 列出所有事件、--override 覆盖载荷字段、--seed 固定 ID。若处理程序返回非 2xx、连接错误或重定向，命令会打印响应体并以状态 1 退出；重定向通常意味着认证中间件拦截了 webhook 路由，需将其排除。
集成测试
指南给出了基于 Vitest 的集成测试示例，包括：创建测试产品并创建/获取结账会话；用 polar webhook trigger <event> --json --seed 1 生成真实载荷 fixture，再按 Standard Webhooks 规范（HMAC-SHA256 对 id.timestamp.body 签名、base64 编码）构造签名请求，测试 webhook 处理程序接受合法签名、拒绝非法签名；以及许可证密钥校验测试（有效与无效密钥）。
单元测试 Mock
可对整个 @polar-sh/sdk 进行 mock，模拟 checkouts、customers、subscriptions 等接口的返回值。webhook 载荷应使用 CLI 生成的 fixture，手写载荷容易与真实结构漂移并被 validateEvent 拒绝。
CI/CD 集成
指南提供了 GitHub Actions 工作流示例，在 CI 中设置 sandbox 令牌、webhook 密钥、组织 ID 和环境变量，依次运行单元测试与集成测试。建议为 CI 创建专用沙箱组织、专用访问令牌，提交 webhook fixture（处理程序测试用测试密钥签名，无需 webhook 端点），并将凭据存入 GitHub Secrets。
调试与常见问题
本地可通过 listen 日志和 trigger 的输出排查；已部署端点可在沙箱控制台的 Settings → Webhooks 查看投递历史、载荷和响应码。常见问题包括：webhook 签名不匹配（检查沙箱密钥、传入原始 body 而非解析后 JSON、时间戳在 5 分钟容差内）、结账未完成（使用测试卡、检查 successUrl）、API 返回 401（确认沙箱令牌配沙箱 API、未过期、权限足够）。
上线前测试清单
结账流程成功完成、webhook 接收并处理、订阅生命周期（创建、取消、撤销）、权益授予与撤销、许可证密钥校验、拒付错误处理、客户门户可访问、退款流程测试。