Testability Obstacle

Resolve a Testability Obstacle

Introduce the smallest behavior-preserving seam needed to test a specific C# behavior, then add deterministic tests that prove both the behavior and the seam. The production edit is a means to the requested test, not an invitation to redesign adjacent code.

When to Use

• A requested test would otherwise read/write the real filesystem.
• Behavior depends on the current time, delay, random value, environment, console, process, or another ambient dependency.
• The user explicitly permits or requests a safe production seam.
• Existing tests cannot control a dependency without process-global mutation.

When Not to Use

• The dependency is already injected or passed as an argument. Write tests with a fake through the existing seam using code-testing-agent.
• The user wants a repository-wide testability audit. Use detect-static-dependencies.
• The user wants wrappers generated but not call sites/tests changed. Use generate-testability-wrappers.
• The user requests a broad mechanical migration. Use migrate-static-to-wrapper, then generate tests separately.
• The user already selected an existing replacement such as TimeProvider or IFileSystem and asks to migrate call sites to it. Use migrate-static-to-wrapper, which also updates affected tests.
• The code is not C#/.NET.

Inputs

Workflow

Step 1: Prove the obstacle

Read the target production path and its existing tests. Identify the exact ambient operation preventing a deterministic test and the behavior that must remain unchanged. Do not run a repository-wide static scan for a single-class request.

If an adequate seam already exists, stop refactoring and use it. This skill adds no value when a fake can already be supplied.

Step 2: Select the smallest safe seam

Choose by dependency and repository constraints:

The scoped AsyncLocal<T> rule applies to every static API that must retain its public static shape — clocks, filesystem access, environment lookups, identity generation, and randomness. The scope captures and restores the previous value; never implement Dispose() as an unconditional assignment to null. Store the provider/value itself in AsyncLocal<T>. Do not put a mutable Stack<T>, list, or other shared mutable collection in the slot: child execution contexts can inherit the same object and corrupt each other's nesting. When the provider itself is mutable (for example an in-memory store or fake time provider), establish a fresh provider inside each parallel flow rather than mutating one inherited instance from a parent context.

Constructor injection is the default for instance classes. Reuse the repository's DI and naming conventions, but do not add a DI container to a class library just to satisfy this workflow.

Preserve the existing public construction surface unless the user authorizes an API change. Keep a public parameterless constructor as the real-dependency default and place a test-only delegate/provider constructor at the narrowest visibility the test project can reach. Do not turn the seam into a new public optional parameter merely for test convenience.

For a static class or a public API that cannot change, use a scoped ambient seam only when constructor/parameter injection is impossible. The override must:

• flow across await (AsyncLocal<T>, not [ThreadStatic]);
• return IDisposable and restore the previous value, including nested scopes;
• default to the real production dependency;
• avoid a process-global mutable fake that makes tests non-parallel.

Use built-in fake-time-aware overloads instead of inventing an IDelay wrapper:

Test delayed behavior by starting the operation, proving it is incomplete, advancing FakeTimeProvider, then awaiting it. For a deadline or boundary, advance to immediately before the deadline and assert the task is still incomplete before advancing across it; an immediate post-start assertion alone does not prove the boundary. Never wait for wall-clock time.

For a nested ambient override, each scope captures the value active when it starts and restores that value exactly once. Dispose scopes in LIFO order with using/finally; never reset the slot unconditionally to null. Tests must observe the outer value after an inner scope ends normally and, when requested, after an exception unwinds the inner scope. Use distinct values so clearing the slot cannot accidentally pass. Also overlap independent async flows and assert that each sees only its own fresh override. Do not mutate process environment variables to test an environment seam.

var previous = s_provider.Value;
s_provider.Value = provider;
return new RestoreScope(() => s_provider.Value = previous);

Step 3: Preserve behavior and API shape

Keep the production change mechanical:

• Wrap only members used by the target behavior.
• Default implementations delegate directly to the original API.
• Preserve exceptions, path handling, time zone, and DateTime.Kind.
• Keep existing public signatures unless the user explicitly permits an API change.
• Do not move business logic into the wrapper or fix unrelated production bugs.

Deterministic serialized text is a deliberate exception to preserving ambient platform formatting. If the user asks for exact reproducible output across platforms, use the format's explicit separator (use literal \n when none is specified) and assert that literal content. Keep Environment.NewLine only when platform-native output is part of the existing contract.

For time replacements:

• DateTime.UtcNow -> timeProvider.GetUtcNow().UtcDateTime
• DateTime.Now -> timeProvider.GetLocalNow().LocalDateTime
• DateTimeOffset.UtcNow -> timeProvider.GetUtcNow()
• DateTimeOffset.Now -> timeProvider.GetLocalNow()

Step 4: Keep production defaults wired

Update every composition root or constructor call affected by the seam. Production must still use real time/filesystem/etc. by default. If the project uses DI, register the default implementation with the lifetime matching repository conventions. If it does not use DI, compose explicitly; do not introduce a container. An existing manual factory must pass the real dependency explicitly (for example, new ExpirationPolicy(TimeProvider.System)). Do not move responsibility into an optional constructor or add an optional provider parameter to the factory.

Build the affected production project before writing tests. A compile failure here is a seam problem, not a test problem.