Karthik Rajesh Shet（karthikrshet）· 仓库创建于 2026-10-19；作者公告于 2026-10-20
主源：LocalPay · Compatibility matrix
支付集成最难测试的部分，常常不是下单成功，而是银行失败、请求超时后迟到授权、webhook 重复或乱序。等待真实环境偶然出现这些事件，既慢又不容易重现。LocalPay 把它们做成本地可控输入：应用仍调用 Razorpay 风格 API，由模拟器驱动订单和支付状态，再向本机业务端发送签名事件。
它的意义是缩短失败路径的开发反馈，而不是建立真实支付网络。仓库仍处于 pre-1.0；兼容性文档明确说还没有从真实测试账户录制的 fixture，API 和事件都标为 partial。这个事实决定了阅读定位：它适合研究本地模拟与故障注入怎样组合，不能因为接口相似就视为已验证的网关等价实现。
一个状态引擎连接 API、界面和事件
系统核心以命令驱动状态机，支持订单、支付、退款、订阅等对象；每次变化追加到事件日志。REST provider 负责输入校验、响应形状和签名约定，webhook dispatcher 将事件转换成通知，dashboard 展示同一份状态。持久化与重放也围绕日志，而不是让几个模块各自维护一套事实。
一次典型交互是：业务服务创建订单，浏览器打开测试 checkout，选择成功或失败场景；支付进入 created、authorized、captured、refunded 或 failed 等相应状态，随后生成业务可见的回调和 webhook。展示成功的弹窗与服务端确认并非同一件事；模拟器让二者的差异成为可测试路径。
可注入时钟控制退款处理、支付链接过期、订阅续费和结算。推进时间会触发期间应发生的事件，而无需等几天；种子化 ID 和相同输入帮助固定预期。这里更适合验证状态转换和处理顺序，不宜把虚拟时间当作真实分布式服务的延迟模型。
故障注入应该打在消费边界上
webhook 层可制造重复、乱序、延迟和缺失签名，并提供重试、日志与重放。REST 层还能注入限流、服务端错误及 API 延迟。两层故障覆盖不同责任：前者检查事件消费者怎样处理重送与过时消息，后者检查请求发起方怎样判断失败并重试。
官方 dashboard 展开一条 webhook，保留事件内容与发送记录，并提供重放、重复发送和无签名发送按钮。
例如，业务已经依据 payment.captured 记账，再收到重复事件时，正确目标通常是避免再次产生业务副作用。旧事件迟到也不应随意把较新的本地状态回退。这些是使用模拟器可构造的测试目标，不是 README 已证明每个接入应用都能满足的性质。缺失签名则提供明确的拒绝路径，用于检查消费者是否真的执行验证。
UPI 先失败后授权的场景更有价值：客户端看到超时，不代表支付生命周期已结束。如果业务立刻重新下单，之后又收到迟到成功，如何关联订单与支付就成为问题。LocalPay 提供事件驱动的可控情景，但真实网关对冲突支付的具体处理仍需独立确认，不能从模拟器的规则反推生产语义。
从人工点击变成回归用例
仓库提供 15 个 YAML 场景，包含超时重试、授权未 capture、部分退款、续费失败和迟到授权等。场景可断言产生了哪些事件、不同状态的支付数量。录制后重发 webhook，则适合在业务 handler 修改后检查消费逻辑是否回归。
从系统测试角度，更有价值的断言应指向业务不变量：一次支付不能重复发货，退款总额不能超过已支付金额，未知或非法状态转换不能静默成功。仓库本身使用 property tests 检查类似金额状态约束。把本地快反馈与真实环境契约样本分开，才能避免“模拟器和测试一起写错却都通过”的闭环。
Node.js 接入使用 shim 改 SDK 目标地址；Python SDK 提供 base_url 参数。兼容表把 Node 2.9.8 和 Python 2.0.1 的连接方式列为 supported，PHP、Java、Go 则尚未检查。这里 supported 指 SDK 连接验证，不会自动把所有 API、响应字段和 webhook 语义从 partial 升级。
具体差异比一个覆盖率数字更重要
当前模拟器 webhook 重试是五次：立即、5 秒、30 秒、2 分钟和 10 分钟，真实网关会更久。订单的 first_payment_min_amount 被接收但未强制执行，一些 expand 参数被忽略，订阅 pause/resume 尚未实现。真实限流额度也没有建模，429 仅由故障配置触发。这些差异会影响应用测试，应按用到的接口逐项核对。
README 声称有 500 多项单元、契约与属性测试，并报告核心与 provider 约 98.7% 行覆盖。这反映项目自测工作量，不能替代真实录制样本的兼容性证据；尤其文档已明确尚无此类录制。也没有可用于判断减少多少生产故障的对照结果，因此不把工具功能扩写成可靠性提升百分比。
如何区分一次失败和一次重复观察
事件日志让一个细节变得清楚：支付对象的变化、通知投递尝试和业务副作用是三种不同记录。一次 captured 事件可以被发送多次，每次尝试可能有不同 HTTP 结果；业务端只应依据其自身幂等约束决定是否执行动作。若测试只断言“收到了一个 HTTP 200”，就可能漏掉重复发货，也可能漏掉收到事件却没有更新订单的情况。
本地工具的优势是能够在同一初始状态下重放不同交付顺序，把这些记录关联起来观察。举例说，可以先让成功事件触达业务端，再重放较旧消息，然后比较最终订单状态与副作用次数。这个用例是基于已提供重放功能的工程推导，不是项目作者报告的实验结果。它强调的是测试问题设计：应故意改变交付路径，同时固定支付事实，才能知道应用是在处理新状态，还是被同一事实的重复通知推动。
这也解释了为什么记录 fixture 是重要的后续步骤。本地状态机给出可控因果链，真实样本补充外部协议细节；只有二者衔接，故障覆盖的广度才不会掩盖接口语义的偏差。
默认仅绑定 localhost、拒绝 live key、测试界面无真实卡号表单，是减少把模拟环境误当生产的设计选择。对于工程团队，合理的使用方式是把可重复故障放进日常回归，再用真实测试模式确认关键契约。LocalPay 值得关注的进展，是将状态机、事件、虚拟时钟和消费端故障放在同一个轻量测试工具中；成熟度的下一步应是补齐真实 fixture 与语义差异，而非先扩大支持功能清单。