generate-testability-wrappers
Generate C# testability wrappers and their DI registration. Use only when C# source calls an ambient/static dependency and no injectable seam exists: first-time TimeProvider, IHttpClientFactory, or System.IO.Abstractions adoption; minimal Environment/Console/Process wrappers; IProcessRunner; DI registration; or an ambient seam that preserves a static API. DO NOT USE when the target already consumes an injected interface or built-in abstraction such as IFileSystem or TimeProvider, even if the request says "generate a wrapper"; no new wrapper is needed. Exclude static detection (detect-static-dependencies), migration to an existing/registered abstraction (after wrapper creation, the user invokes /deniz-dotnet-general:migrate-static-to-wrapper separately), behavior-test requests whose seam is still open, and general interface design.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- generate-testability-wrappers
- license
- MIT
- description
- Generate C# testability wrappers and their DI registration. Use only when C# source calls an ambient/static dependency and no injectable seam exists: first-time TimeProvider, IHttpClientFactory, or System.IO.Abstractions adoption; minimal Environment/Console/Process wrappers; IProcessRunner; DI registration; or an ambient seam that preserves a static API. DO NOT USE when the target already consumes an injected interface or built-in abstraction such as IFileSystem or TimeProvider, even if the request says "generate a wrapper"; no new wrapper is needed. Exclude static detection (detect-static-dependencies), migration to an existing/registered abstraction (after wrapper creation, the user invokes /deniz-dotnet-general:migrate-static-to-wrapper separately), behavior-test requests whose seam is still open, and general interface design.
- disable-model-invocation
- true
03 SKILL.md 正文
Generate Testability Wrappers
Generate wrapper interfaces, default implementations, and DI service registration code for untestable static dependencies. For statics that already have .NET built-in abstractions (TimeProvider, IHttpClientFactory), guide adoption of the built-in. For statics without built-in alternatives, generate custom minimal wrappers.
When to Use
- After running
detect-static-dependenciesand identifying which statics to wrap - When the user asks to make a class testable by replacing statics with injected abstractions
- When adopting
TimeProvider(.NET 8+) orSystem.IO.Abstractions - When creating a custom wrapper for
Environment.*,Console.*, orProcess.* - When a released static API needs an ambient seam because signatures cannot change
When Not to Use
- The user wants to find statics first (use
detect-static-dependencies) - The user wants to bulk-replace call sites (after wrapper creation, the user
invokes
/deniz-dotnet-general:migrate-static-to-wrapperseparately) - The static is already behind an interface
If the target already consumes an injected interface or built-in abstraction, stop: do not add a second wrapper, project, registration, or test around that seam.
A missing DI package does not by itself force an ambient seam. For an instantiable class, prefer constructor injection and compose it explicitly or show the requested registration. Use Step 5 when the API is static and its signatures must stay static, or when the user explicitly forbids caller construction/DI changes.
Inputs
| Input | Required | Description |
|---|---|---|
| Static category | Yes | Which category: time, filesystem, environment, network, console, process |
| Target framework | Yes | The TargetFramework from .csproj (affects which built-in abstractions exist) |
| Composition | No | Existing DI framework, explicit/manual construction, or immutable static API |
| Namespace | No | Target namespace for generated wrapper code |
Workflow
Step 1: Determine the abstraction strategy
Based on the category and target framework:
| Category | .NET 8+ | .NET 6-7 | .NET Framework |
|---|---|---|---|
| Time | TimeProvider (built-in) |
TimeProvider via Microsoft.Bcl.TimeProvider NuGet |
Custom ISystemClock |
| File system | System.IO.Abstractions (NuGet) |
Same | Same |
| HTTP | IHttpClientFactory (built-in) |
Same | Same |
| Environment | Custom IEnvironmentProvider |
Same | Same |
| Console | Custom IConsole |
Same | Same |
| Process | Custom IProcessRunner |
Same | Same |
The table picks which abstraction. How it reaches the code under test is a separate axis:
- instantiable class: constructor injection, even if current callers compose the object manually;
- existing container: add compile-ready registration following its conventions;
- public static API/signatures that cannot change: Step 5's ambient seam.
Check for a host builder, IServiceCollection, existing registrations, and
construction sites. Do not infer "must remain static" merely because the project
currently has no container.
An existing manual factory passes the real dependency explicitly (for example,
new ExpirationPolicy(TimeProvider.System)). Do not move that responsibility into
an optional constructor parameter or add an optional provider parameter to the
factory.
Constructor injection through a public constructor is the default. Only when all
three hold, take the narrower branch: the type is released public API, the user
has not authorized an API change, and the exact test assembly is known. Then keep
the public parameterless constructor as the real-dependency default, make the
injecting constructor internal, and add InternalsVisibleTo for that one
test assembly, or follow an existing friend-assembly convention. Outside that
branch, add no InternalsVisibleTo.
Write every generated test in the test project's existing framework,
global-using, and assertion conventions, with the framework packages it already
references; the examples in this skill use xUnit-style assertions. Never add a
hand-rolled FactAttribute, a substitute test-framework type, or unrelated
test-project plumbing to make a test compile.
Step 2: Generate built-in abstraction adoption (Time, HTTP)
TimeProvider (.NET 8+)
No wrapper code needed. Complete all four parts: production registration,
constructor injection, a FakeTimeProvider test, and the testing package.
- Register in DI:
builder.Services.AddSingleton(TimeProvider.System);
- Inject into classes:
public class OrderProcessor(TimeProvider timeProvider)
{
public bool IsExpired(Order order)
=> timeProvider.GetUtcNow() > order.ExpiresAt;
}
- Test with
FakeTimeProvider:
// Requires Microsoft.Extensions.TimeProvider.Testing NuGet
var fakeTime = new FakeTimeProvider(new DateTimeOffset(2026, 1, 15, 0, 0, 0, TimeSpan.Zero));
var processor = new OrderProcessor(fakeTime);
fakeTime.Advance(TimeSpan.FromDays(1));
Assert.True(processor.IsExpired(order));
The assertion must prove a time-dependent result after the fake is pinned or
advanced. Merely constructing FakeTimeProvider is not a test. When the project
has no container but the target is an instantiable class, inject
TimeProvider anyway and show explicit production construction with
TimeProvider.System; do not replace it with a custom static clock.
Before calling the adoption complete, verify the repository contains or the answer supplies every required artifact: the testing package reference, the production composition/registration, every affected constructor call, and a runnable fake-time test. A code fragment that omits one of those integration points is guidance, not a completed adoption.
TimeProvider (pre-.NET 8)
Guide: install Microsoft.Bcl.TimeProvider NuGet. Same API as above.
IHttpClientFactory
No wrapper code needed. Register a typed client via
builder.Services.AddHttpClient<MyService>() and inject HttpClient directly
into the class constructor. Preserve cancellation by passing the caller's token
to the HTTP operation.
For tests, provide a complete fake HttpMessageHandler whose SendAsync
returns a deterministic HttpResponseMessage, construct HttpClient with that
handler, and exercise the typed client without network access. Compile and run
the focused test when the task asks for implementation; do not stop at a
schematic handler method.
When production uses a typed-client registration, test that same registration
pipeline: configure its primary handler in ServiceCollection, resolve the typed
client, and call it. A test that manually constructs HttpClient proves the class
but not the DI registration the task asked to adopt.
Step 3: Generate custom wrappers (Environment, Console, Process)
For categories without built-in abstractions, follow this template:
Interface — define the minimal surface
Only include methods that were actually detected in the codebase. Do NOT generate a wrapper for every possible member — wrap only what is used.
Prefer a stateless operation-shaped interface. For example, if a caller only
needs to start a process, wait, and return its exit code, expose one Run
operation rather than a stateful wrapper that leaks Process lifecycle.
namespace <Namespace>;
/// <summary>
/// Abstraction over <static class> for testability.
/// </summary>
public interface I<WrapperName>
{
// One method per detected static call
<return type> <MethodName>(<parameters>);
}
Default implementation — delegate to the real static
namespace <Namespace>;
/// <summary>
/// Default implementation that delegates to <static class>.
/// </summary>
public sealed class <WrapperName> : I<WrapperName>
{
public <return type> <MethodName>(<parameters>)
=> <StaticClass>.<Method>(<arguments>);
}
DI registration
// In Program.cs or Startup.cs:
builder.Services.AddSingleton<I<WrapperName>, <WrapperName>>();
Treat registration as a deliverable, not a sentence in the summary. Add it to the repository's existing registration surface when one exists. Otherwise show the exact compile-ready statement and identify where the caller should place it. Stateless delegating wrappers are singleton; if state must be retained, explain why a shorter lifetime is required.
Step 4: Generate file system wrapper adoption
Prefer the established System.IO.Abstractions NuGet package over custom wrappers:
- Install the package:
dotnet add package System.IO.Abstractions
- Register in DI:
builder.Services.AddSingleton<IFileSystem, FileSystem>();
- Inject
IFileSysteminto classes:
public class ConfigLoader(IFileSystem fileSystem)
{
public string LoadConfig(string path)
=> fileSystem.File.ReadAllText(path);
}
- Test with
MockFileSystem:
dotnet add <TestProject> package System.IO.Abstractions.TestingHelpers
var mockFs = new MockFileSystem(new Dictionary<string, MockFileData>
{
{ "/config.json", new MockFileData("{\"key\": \"value\"}") }
});
var loader = new ConfigLoader(mockFs);
Assert.Equal("{\"key\": \"value\"}", loader.LoadConfig("/config.json"));
Package-first adoption is exclusive: add both package references, use
IFileSystem in production, register or explicitly compose FileSystem, and
seed MockFileSystem before exercising the consumer. Do not also generate a
second custom filesystem interface, and do not present an unseeded mock whose
test could pass without proving the requested read/write behavior.
Step 5: Generate a signature-preserving ambient context
Use this pattern when the API must remain static or its released signatures cannot accept a dependency:
public static class Clock
{
private static readonly AsyncLocal<Func<DateTime>?> s_override = new();
public static DateTime UtcNow
=> s_override.Value?.Invoke() ?? TimeProvider.System.GetUtcNow().UtcDateTime;
internal static IDisposable Override(DateTime fixedUtcTime)
{
if (fixedUtcTime.Kind != DateTimeKind.Utc)
throw new ArgumentException("The override must be UTC.", nameof(fixedUtcTime));
var previous = s_override.Value;
s_override.Value = () => fixedUtcTime;
return new Scope(() => s_override.Value = previous);
}
private sealed class Scope : IDisposable
{
private Action? _restore;
public Scope(Action restore)
{
_restore = restore;
}
public void Dispose() =>
Interlocked.Exchange(ref _restore, null)?.Invoke();
}
}
Key trade-offs: AsyncLocal<T> ensures parallel tests don't interfere; production cost is one null check per call; the static readonly field is essentially free.
Store the provider or value itself in AsyncLocal<T>. Do not put a mutable
stack, list, or other shared collection in the slot: child execution contexts
can inherit the same object and corrupt each other's nesting. When the provider
is mutable, create a fresh provider inside each parallel flow rather than
mutating one inherited from a parent context.
Three properties this pattern must keep, because each has broken a real migration:
- Scope the override and make it reversible. Return an
IDisposablethat restores the previous value, so a test cannot leak a pinned time into the next one. A bare setter, or a manualtry/finallyat each call site, puts that burden on every test author. - Use
AsyncLocal<T>, never[ThreadStatic].[ThreadStatic]does not flow acrossawait, so the override silently disappears mid-test. - Preserve the semantics of the member you are replacing. Substituting
DateTime.UtcNowwith a local-time source changes theDateTimeKindevery existing caller and stored value depends on — pairUtcNowwithGetUtcNow(), andNowwithGetLocalNow(). - Prove the test assembly can reach the override. An
internaloverride is inaccessible from a separate test assembly unless the production project adds the exactInternalsVisibleTofor that test assembly. Otherwise use an already-public seam only when a public API change is authorized. Never show a test calling an inaccessible member.
The same shape works for non-time statics: swap TimeProvider.System.GetUtcNow() for the real static call and keep the override slot, the disposable scope, and the original semantics.
Test nested restoration across exception unwinding. Observe the outer value
after the exception leaves the inner using scope but before disposing the
outer scope:
var outerTime = new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc);
var innerTime = outerTime.AddDays(1);
using var outer = Clock.Override(outerTime);
Assert.Equal(outerTime, Clock.UtcNow);
Assert.Throws<InvalidOperationException>(() =>
{
using var inner = Clock.Override(innerTime);
Assert.Equal(innerTime, Clock.UtcNow);
throw new InvalidOperationException("test");
});
Assert.Equal(outerTime, Clock.UtcNow);
Also overlap two async flows that each establish a fresh override and assert that each sees only its own value. The nested test catches an inner dispose that clears the slot; the parallel test catches cross-flow leakage.
On .NET 8+, do not wrap delays. The BCL already accepts a TimeProvider:
| Ambient operation | Replacement |
|---|---|
Task.Delay(delay, token) |
Task.Delay(delay, timeProvider, token) |
new CancellationTokenSource(delay) |
new CancellationTokenSource(delay, timeProvider) |
PeriodicTimer(period) |
new PeriodicTimer(period, timeProvider) when the target framework provides it |
Test delayed behavior by starting the operation and proving it is incomplete
before advancing FakeTimeProvider. For a deadline, advance to immediately
before the boundary and assert that the task is still incomplete before
advancing across it. Never wait for wall-clock time.
Step 6: Place generated files
Generate files following the project's existing conventions:
- If there is an
Abstractions/orInterfaces/folder, place the interface there - If there is an
Infrastructure/orServices/folder, place the implementation there - Otherwise, create files next to the code that uses the static
Always generate:
- The interface file (or adoption instructions for built-in abstractions)
- The default implementation file
- The compile-ready DI registration, applied to an existing registration surface or shown at the exact composition point.
- A deterministic substitution example or focused test that exercises the consumer without the ambient resource.
Skip registration entirely on the ambient-seam path: there is no container to register into, and offering one anyway is the failure mode that made a user ask for the seam in the first place.
Before reporting completion, verify the delivered output contains every item the prompt requested. In particular, do not summarize "singleton registration" when no registration code was added or shown, and do not claim testability without demonstrating how the consumer receives a fake. For console wrappers, exercise the consumer with a fake that both captures the prompt and supplies the returned input; a build or banner-only run does not prove the prompt flow.
Validation
- [ ] Generated interface only wraps statics that were actually detected (not speculative)
- [ ] Default implementation delegates to the real static with no behavior changes
- [ ] DI registration uses
AddSingletonfor stateless wrappers,AddTransientfor stateful ones - [ ] NuGet packages are recommended where established libraries exist (System.IO.Abstractions, etc.)
- [ ] For .NET 8+,
TimeProvideris recommended over customISystemClock - [ ] TimeProvider adoption includes injection, production composition,
FakeTimeProvider, its testing package, and an assertion on a time-dependent result - [ ] HTTP adoption includes a complete fake-handler test and preserves cancellation
- [ ] On injection paths, registration or explicit composition is compile-ready, and a fake demonstrates the consumer without the real ambient dependency
- [ ] Ambient context pattern includes
AsyncLocal<T>, a scopedIDisposablethat restores the previous value, and trade-off explanation - [ ] Nested exception unwinding restores the outer override and overlapping async flows remain isolated
- [ ] On the ambient-seam path, no
IServiceCollectionregistration is proposed, the separate test assembly can reach the override, and the replaced member's return type and semantics (UtcNowvsNow, and itsDateTimeKind) are preserved
Common Pitfalls
| Pitfall | Solution |
|---|---|
| Treating "no DI package" as "must be ambient" | Inject into instantiable classes and compose explicitly; reserve Step 5 for static/signature-preserving APIs |
| Wrapping ALL members of a static class | Only wrap methods actually called in the codebase |
| Custom time wrapper on .NET 8+ | Use built-in TimeProvider instead |
| Custom file system wrapper | Prefer System.IO.Abstractions NuGet — battle-tested, complete |
| Registering scoped when singleton suffices | Stateless wrappers should be AddSingleton |
| Forgetting test helper packages | Microsoft.Extensions.TimeProvider.Testing for time, System.IO.Abstractions.TestingHelpers for filesystem |
Ambient context without AsyncLocal |
Non-async [ThreadStatic] breaks with async/await — always use AsyncLocal<T> |
| Showing an internal ambient override to external tests | Add the exact friend assembly or use an authorized public seam; compile the test project |
04 同仓库更多 Skills
writing-tunit-tests
Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.
dotnet-walls
Walls for a .NET change in a repository without its own quality gates — pinned, ephemeral analyzer, format, clone and scanner commands for the verify step, their identity ratchet, and the build traps. Use during a walls preflight, or when a worker's verify step needs .NET quality gates.
csharp-15
Write, review and modernize C# 15 (.NET 11) code correctly. Covers every C# 15 feature - collection expression arguments (`[with(...), ...]`), union types (`union`, `[Union]`, `IUnion`, custom unions), closed class hierarchies (`closed`), extension indexers, labeled `break`/`continue`, non-virtual static interface members on runtimes without default interface methods, and the preview memory-safety model (`unsafe(expr)`, `safe`, requires-unsafe members). Use when code targets net11.0 or LangVersion 15/preview, when the user mentions any of these features, when replacing marker interfaces, OneOf-style results, `goto`/flag loop exits or capacity/comparer boilerplate, or when the build reports CS8121, CS8509, CS8655, CS8510, CS0121/CS0411 on a `with(...)` element, CS9370, CS9380 or CS9363.
verified-waves
Run one task as verified multi-agent waves. Plans the fan-out, sends findings to fresh skeptics, keeps a ledger, and reports N of M done; small tasks stay solo.
harness
The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.
delegating-to-worker-models
Use when you hand off implementation, a plan, research a decision will rely on, or a review, and you brief the worker and check what comes back. A subagent that searches, reads in parallel, or keeps your context small is ordinary tool use. Covers what stays with you, the mechanism, assigning work by strength, the walls preflight, prompts without contradictions, the worker contract and model profiles, evidence from your own run, review, and the fix-up loop.