Idioms

Use AutoFixture.Idioms to verify guard clauses and other coding idioms in your API.

The AutoFixture.Idioms package provides assertions that use AutoFixture to exercise constructors, methods, and properties — so you do not write the same boilerplate tests by hand.

Prerequisites

Install

<PackageReference Include="AutoFixture.Idioms" Version="5.0.0-rc.1" />

Example scenario

You are hardening a public API. You want to verify guard clauses, constructor initialization, writable properties, and equality comparers without one repetitive test per member.

Guard clauses

GuardClauseAssertion invokes members with null and invalid inputs and checks that the right exceptions are thrown.

Constructor:

var fixture = new Fixture();
var assertion = new GuardClauseAssertion(fixture);
var constructor = typeof(GuardedOrderProcessor).GetConstructors().Single();

var exception = Record.Exception(() => assertion.Verify(constructor));

Assert.Null(exception);

Method:

var method = typeof(GuardedOrderProcessor).GetMethod(nameof(GuardedOrderProcessor.Process));

var exception = Record.Exception(() => assertion.Verify(method!));

Assert.Null(exception);

Sweep a whole type:

var exception = Record.Exception(() => assertion.Verify(typeof(GuardedOrderProcessor)));

Assert.Null(exception);

Pass an Assembly, Type, or individual ConstructorInfo / MethodInfo / PropertyInfo to Verify depending on how much of the surface you want to check.

Constructor-initialized members

ConstructorInitializedMemberAssertion checks that a read-only property or field holds the value passed to the matching constructor parameter:

var fixture = new Fixture();
var assertion = new ConstructorInitializedMemberAssertion(fixture);
var store = typeof(GuardedOrderProcessor).GetProperty(nameof(GuardedOrderProcessor.Store));

var exception = Record.Exception(() => assertion.Verify(store!));

Assert.Null(exception);

Writable properties

WritablePropertyAssertion assigns a value through the setter and checks that the getter returns the same value:

var fixture = new Fixture();
var assertion = new WritablePropertyAssertion(fixture);
var name = typeof(Person).GetProperty(nameof(Person.Name));

var exception = Record.Exception(() => assertion.Verify(name!));

Assert.Null(exception);

Read-only properties are skipped automatically.

Equality comparers

EqualityComparerAssertion exercises IEqualityComparer<T> implementations for null handling, symmetry, transitivity, and consistent GetHashCode:

var fixture = new Fixture();
var assertion = new EqualityComparerAssertion(fixture);

var exception = Record.Exception(() => assertion.Verify(typeof(ProductCodeComparer)));

Assert.Null(exception);

Composite assertions

CompositeIdiomaticAssertion runs several IIdiomaticAssertion instances against the same target. EqualityComparerAssertion is itself a composite of the individual equality-comparer checks.

Combine built-in assertions for a type:

var fixture = new Fixture();
var assertion = new CompositeIdiomaticAssertion(
    new GuardClauseAssertion(fixture),
    new ConstructorInitializedMemberAssertion(fixture));

var exception = Record.Exception(() => assertion.Verify(typeof(GuardedOrderProcessor)));

Assert.Null(exception);

Each child assertion receives the same Verify call — constructor, method, property, type, or assembly.

Custom assertions

Implement IIdiomaticAssertion directly, or subclass IdiomaticAssertion and override the Verify overloads you need. The base class walks assemblies, types, and members for you.

This example encodes a team rule — exactly one public constructor, and AutoFixture must be able to construct the type:

using System.Reflection;
using AutoFixture.Kernel;
using AutoFixture.Idioms;

public sealed class SinglePublicConstructorAssertion(ISpecimenBuilder builder) : IdiomaticAssertion
{
    public ISpecimenBuilder Builder { get; } = builder ?? throw new ArgumentNullException(nameof(builder));

    public override void Verify(Type type)
    {
        if (type is null)
            throw new ArgumentNullException(nameof(type));

        var constructors = type.GetConstructors();
        if (constructors.Length != 1)
        {
            throw new InvalidOperationException(
                $"Type '{type.FullName}' must expose exactly one public constructor, but found {constructors.Length}.");
        }

        _ = new SpecimenContext(Builder).Resolve(type);
    }
}

Use it like any built-in assertion:

var fixture = new Fixture();
var assertion = new SinglePublicConstructorAssertion(fixture);

var exception = Record.Exception(() => assertion.Verify(typeof(GuardedOrderProcessor)));

Assert.Null(exception);

Add your custom assertion to a CompositeIdiomaticAssertion when you want it in a standard API sweep.

How it works

  • GuardClauseAssertion — null/invalid inputs on constructors and methods must throw
  • ConstructorInitializedMemberAssertion — constructor parameters flow into matching members
  • WritablePropertyAssertion — setter/getter round-trip for writable properties
  • EqualityComparerAssertion — composite checks for custom IEqualityComparer<T> types
  • CompositeIdiomaticAssertion — runs multiple assertions against the same reflection target
  • Custom IdiomaticAssertion — override selected Verify overloads for team-specific rules
  • Verify(...) overloads — target a single member, a type, or an entire assembly

All assertions take an ISpecimenBuilder (usually new Fixture()) to create the arguments and owners they need.

Next steps

API

Data annotations

Seed extensions