当 C#/.NET 测试因…

为需要控制时间、文件、环境、随机等环境依赖的 C#/.NET 行为引入最小且保持行为不变的生产接缝，并编写确定性测试同时验证行为与接缝。

适用场景

解决思路

1. 先证明障碍：阅读目标生产路径及其现有测试，找出阻止确定性测试的具体环境操作以及必须保持不变的行为；不要为单个类请求做全仓库静态扫描。
2. 若已有可用接缝，停止重构并直接使用它；当已能注入 fake 时本技能无价值。
3. 按依赖选择最小安全接缝：当前时间/计时器注入 TimeProvider 并在测试用 FakeTimeProvider；文件系统优先用现有仓库抽象，单次读写可在约定允许时用注入委托，否则用单成员接口或已接受的 System.IO.Abstractions；HTTP 用现有 typed HttpClient/handler 或 IHttpClientFactory 接缝；随机性单值用注入委托并以 Random.Shared 为生产默认，多操作/状态则注入 Random 或最小生成器接口；环境/控制台/进程用仅含目标所用成员的最小接口。
4. 对必须保留公共静态形态的静态 API（时钟、文件系统、环境查找、身份生成、随机）使用作用域 AsyncLocal<T> 规则：作用域捕获并恢复先前值，绝不把 Dispose() 实现为无条件赋 null；槽中存 provider/值本身，不要放可变 Stack<T>、列表或其他共享可变集合，因为子执行上下文可能继承同一对象并破坏嵌套；当 provider 本身可变（如内存存储或 fake 时间 provider）时，在每个并行流内建立全新 provider，而不是从父上下文修改继承实例。
5. 实例类默认用构造函数注入；复用仓库的 DI 与命名约定，但不要仅为满足本流程而给类库添加 DI 容器。
6. 除非用户授权改 API，否则保留现有公共构造面：保留公共无参构造函数作为真实依赖默认，并把仅测试用的委托/provider 构造函数放在测试项目可达的最窄可见性；不要仅为测试方便把接缝变成新的公共可选参数。
7. 仅当构造函数/参数注入不可能时，才对静态类或不可改的公共 API 使用作用域环境接缝；覆盖必须跨 await 流动（用 AsyncLocal<T> 而非 [ThreadStatic]）、返回 IDisposable 并恢复先前值（含嵌套作用域）、默认使用真实生产依赖、避免使测试无法并行的进程级可变 fake。
8. 使用内置的 fake-time 感知重载而非自造 IDelay 包装：Task.Delay(delay, token) 改为 Task.Delay(delay, timeProvider, token)；new CancellationTokenSource(delay) 改为 new CancellationTokenSource(delay, timeProvider)；PeriodicTimer(period) 在目标框架提供时改为 new PeriodicTimer(period, timeProvider)。
9. 测试延迟行为时：启动操作、证明其未完成、推进 FakeTimeProvider、再 await；对截止/边界，先推进到截止前一刻并断言任务仍未完成，再跨过截止推进；仅启动后立即断言不足以证明边界；绝不等墙钟时间。
10. 嵌套环境覆盖时每个作用域拥有其启动时生效的值；用 using（生成 try/finally）或显式 finally 按 LIFO 顺序释放作用域，释放内层恢复外层值而非无条件 null；异常测试必须在内层 using 作用域已抛出异常逃逸之后、外层作用域释放之前观察外层值；同时重叠两个各自建立新覆盖的异步流并断言每个流只看到自己的值，仅并行测试无法捕获常见的“dispose 置 null”缺陷；这些测试不要修改进程环境变量，作用域读取器才是确定性输入；外层值要选与生产回退值不同的值，以免清空槽位意外通过恢复断言。
11. 保持生产改动机械：只包装目标行为用到的成员；默认实现直接委托原 API；保留异常、路径处理、时区和 DateTime.Kind；除非用户明确允许改 API，否则保留现有公共签名；不要把业务逻辑搬进包装器或顺手修无关生产缺陷。
12. 确定性序列化文本是保留环境平台格式的刻意例外：若用户要求跨平台精确可复现输出，使用该格式的显式分隔符（未指定时用字面量 \n）并断言该字面内容；仅当平台原生输出属于现有契约时才保留 Environment.NewLine。
13. 时间替换：DateTime.UtcNow -> timeProvider.GetUtcNow().UtcDateTime；DateTime.Now -> timeProvider.GetLocalNow().LocalDateTime；DateTimeOffset.UtcNow -> timeProvider.GetUtcNow()；DateTimeOffset.Now -> timeProvider.GetLocalNow()。
14. 保持生产默认接线：更新受接缝影响的每个组合根或构造函数调用，生产仍默认使用真实时间/文件系统等；若项目用 DI，按仓库约定生命周期注册默认实现；若不用 DI，显式组合，不要引入容器；现有手动工厂必须显式传入真实依赖（如 new ExpirationPolicy(TimeProvider.System)），不要把职责移入可选构造函数或给工厂加可选 provider 参数。
15. 在写测试前先构建受影响的生产项目；此处编译失败是接缝问题而非测试问题。
16. 使用仓库现有测试项目；若不存在，先调用 scaffold-dotnet-test-project。
17. 测试必须提供受控依赖：固定/可推进时间而非等墙钟；内存 fake 文件系统或手写 fake 而非临时/真实文件；不修改环境、不启外部进程、不读控制台输入、不访问网络。
18. 编写测试前检查其测试项目并遵循现有框架、global-using 与断言约定；使用该项目已引用的框架包；绝不添加手写 FactAttribute、替代测试框架类型或无关测试项目管道来让测试编译。
19. 断言所请求的业务结果以及至少一个证明 fake 依赖驱动了该路径的交互/状态可观察量；仅当能保持确定性时才包含生产默认测试；绝不要仅为证明适配器委托而触碰真实文件系统。
20. 选择支持该行为的最窄接缝：单次 File.WriteAllText 调用可用带真实默认的注入 Action<string, string>；除非仓库约定或多次操作证明合理，否则不要创建接口、实现、friend-assembly 设置和额外项目接线。
21. 保留公共 API 表面及现有签名；不要仅为测试添加公共依赖注入构造函数；当类当前只有隐式公共无参构造函数且确切测试程序集已知时，保留该构造函数行为并把仅测试用构造函数设为 internal；此窄场景下 InternalsVisibleTo 是合理的，因为它防止接缝成为公共 API；若仓库已有 friend-assembly 约定则优先使用。
22. 当现有公共接缝已能接受 fake 或测试项目能以其他方式提供时，不要添加 InternalsVisibleTo；仅当所选最小构造函数/委托接缝必须保持 internal 以保留公共 API 且确切测试程序集已知时，friend-assembly 访问才合理。
23. 验证完整路径：运行受影响的生产构建、目标测试项目和仓库级测试命令；重读 diff 并确认：每处生产改动都是接缝所需；新测试不使用真实环境资源；当前时间语义与公共行为保持不变；现有测试未被替换或重复。
24. 检查测试摘要而非仅退出码；零发现测试、未运行所请求测试的构建、任何失败/报错测试都意味着任务未完成；报告成功前修复发现/执行并重跑。
25. 当新测试无法编译时，先针对现有测试框架修正其导入、断言重载或异步测试形态，再改生产接缝；不要在源码中模拟缺失的框架 API。
26. 对静态环境接缝，完成要求已执行测试覆盖替换、嵌套恢复和重叠异步流隔离；仅生产编译永远不够；在交接中记录通过的测试数或所请求测试名；若无测试被发现或输出未证明执行，修正项目/测试源码并重跑，而不是报告接缝已验证。
27. 输出紧凑的 Requirement | Evidence 表，引用生产接缝、生产默认接线、确切测试名和通过命令；若包还原或构建阻塞验证，报告该阻塞而非声称测试通过。
28. 验证清单：原始障碍具体且在所请求路径中；可用时复用现有接缝；新抽象只暴露目标行为所需成员；生产默认仍委托原依赖；内部测试接缝足够时未扩大公共 API；时间转换保留本地/UTC 与 DateTime.Kind 语义；静态环境覆盖异步安全、有作用域、可嵌套、可逆；新测试使用固定/内存依赖且无真实 I/O 或墙钟；生产构建与目标/仓库测试通过且至少发现一个所请求测试。
29. 常见陷阱纠正：未证明障碍就重构 -> 复用现有接缝并直接写测试；包装整个静态 API -> 只暴露目标用到的成员；用 .DateTime 转换 UtcNow -> 用 .UtcDateTime 保留 DateTimeKind.Utc；测试共享可变静态 fake -> 用构造函数注入或作用域 AsyncLocal<T> 覆盖；给无容器库加 DI -> 显式组合依赖；用临时文件走捷径 -> 提供内存 fake，该场景不需要真实 I/O；重构能编译就停 -> 编写并运行证明接缝合理的行为测试；把零测试运行报告为成功 -> 修复发现并要求所请求测试执行并通过。

适用边界 · 注意事项

• 依赖已被注入或作为参数传入时——应通过现有接缝用 fake 编写测试，而不是重构。
• 用户想要仓库级可测试性审计、仅生成包装器而不改调用点/测试、或大范围机械迁移时——应使用相应专用技能。
• 用户已选定现有替代（如 TimeProvider 或 IFileSystem）并要求迁移调用点时——应使用 migrate-static-to-wrapper。
• 代码不是 C#/.NET 时。