Imposter Documentation

Imposter applies specific matching rules for different parameter types when working with generics:

1. Input Parameters: Setups on a generic argument type (e.g., Animal) match calls made with that type or any derived type (e.g., Cat). However, a setup on a derived type (Cat) will not match a call made with a base type (Animal).
2. Output Parameters: Setups on a derived type (Cat) can be invoked even if the method is called using a base type (IAnimal) as the output parameter. The value is assigned and observable through the base-typed variable.
3. Ref Parameters: Matching is strict based on the exact static generic argument. A setup on a base type (IAnimal) does not match a ref argument of a derived type (Cat).
4. Generic Return Types: Setups for a specific derived type (Cat) work when the method is invoked with a base return type (IAnimal). Conversely, setups for a base type (IAnimal) will not be used when the method is invoked with a derived return type (Cat), resulting in a default value.

When using ImposterMode, the behavior of methods depends on whether a setup has been defined using .Returns() or .ReturnsAsync().

Implicit Mode: Returns default(T) for any method call without a setup.

Explicit Mode: Throws MissingImposterException for any method call without a setup.

Example setup for both modes:

// Implicit behavior
var imposter = new IMyServiceImposter(ImposterMode.Implicit);
var service = imposter.Instance();
int n = service.GetNumber(); // Returns 0

imposter.GetNumber().Returns(42);
service.GetNumber(); // Returns 42

// Explicit behavior
var imposter = new IMyServiceImposter(ImposterMode.Explicit);
var service = imposter.Instance();
// service.GetNumber(); // Throws MissingImposterException

imposter.GetNumber().Returns(42);
service.GetNumber(); // Returns 42

using Imposter.Abstractions;

[assembly: GenerateImposter(typeof(IMyService))]

public interface IMyService
{
    int GetNumber();
    System.Threading.Tasks.Task<int> GetNumberAsync();
}

Imposter provides two modes via the ImposterMode enum that determine how the generated imposter behaves when a method, property, or indexer is called without a prior setup.

Implicit Mode

In ImposterMode.Implicit, calls to members without setups are handled gracefully:

• Methods: Return default(T).
• Properties: Getters return default(T); setters are ignored (do nothing).
• Indexers: Getters return default(T); setters are ignored.
• Best Use Case: Use this during prototyping or spikes where receiving default values is acceptable and you want to avoid boilerplate setups.

Explicit Mode

In ImposterMode.Explicit, calls to members without setups are treated as errors:

• Methods, Properties, and Indexers: Any access (get, set, or call) that lacks a corresponding setup throws a MissingImposterException.
• Best Use Case: Use this as the default for unit tests to ensure all interactions with the dependency are intentionally configured and to catch missing setups early.

Open generics allow you to register a single generic interface or class (using the open generic syntax typeof(T<>)) and automatically generate imposters for any concrete type used at the call site.

Key behaviors of Open Generics:

• Isolation: Each closed generic type (e.g., IAsyncObservable<string> vs IAsyncObservable<int>) receives its own unique imposter type, setup, and call tracking history. They do not share state.
• Scoped Verification: Verification is scoped to both the specific concrete type argument and the specific imposter instance. Calls made to an int instance will not satisfy verification requirements for a string imposter.
• Member Independence: Isolation applies to all members (methods, properties, indexers, and events) of the generic type.

// Register the open generic type
[assembly: GenerateImposter(typeof(IAsyncObservable<>))]

public interface IAsyncObservable<T>
{
    void OnNext(T item);
}

Properties and indexers follow the same logic regarding ImposterMode:

Implicit Example:

var imposter = new IPropertySetupSutImposter(ImposterMode.Implicit);
var sut = imposter.Instance();

int n = sut.Age; // 0 (default)
sut.Age = 10;    // Ignored

int value = sut[1, "key"]; // 0 (default)
sut[1, "key"] = 10;       // Ignored

Explicit Example:

var imposter = new IPropertySetupSutImposter(ImposterMode.Explicit);
var sut = imposter.Instance();

// sut.Age;       // Throws MissingImposterException
// sut.Age = 10;  // Throws MissingImposterException

// var value = sut[1, "missing"]; // Throws MissingImposterException
// sut[1, "missing"] = 10;       // Throws MissingImposterException