aweXpect.Reflection 4.0.0-pre.3

aweXpect.Reflection

aweXpect.Reflection contains expectations for reflection types.

Installation

dotnet add package aweXpect.Reflection

The package brings Expect.That with it, but not the expectations for strings, numbers or collections, so reference aweXpect as well. The expectations live in the namespace aweXpect; the sources In and Types, their filters and the customization need using aweXpect.Reflection;, and a stored selection like Filtered.Types needs using aweXpect.Reflection.Collections;.

At a glance

Write architecture and convention tests as plain, readable expectations: select the assemblies, types or members you care about with In or Types, then expect a rule on them with Expect.That.

// "Every async method must end in 'Async'"
await Expect.That(In.AssemblyContaining<PlaylistService>()    // ① pick a source
        .Methods()                                            // ② navigate to a member kind
        .WhichAreAsync())                                     // ③ filter it down
    .HaveName("Async").AsSuffix();                            // ④ expect

Every expectation follows the same four-part shape:

Steps ② and ③ are optional. You can verify a single Type, MethodInfo, … or a whole Assembly directly, and every expectation works the same whether the subject is one item or a collection (Assembly[], IEnumerable<Type?>, …).

The supported reflection subjects are Assembly, Type, ConstructorInfo, EventInfo, FieldInfo, MethodInfo and PropertyInfo.

Real-world examples

// Verify all test classes (those containing a [Fact] or [Theory] method) follow the naming convention
await Expect.That(In.AllLoadedAssemblies()
        .Public.Classes()
        .WhichContainMethods(m => m.With<FactAttribute>().OrWith<TheoryAttribute>()))
    .HaveName("Tests").AsSuffix();

// Verify all async methods have an "Async" suffix
await Expect.That(In.AssemblyContaining<PlaylistService>()
        .Methods().WhichAreAsync())
    .HaveName("Async").AsSuffix();

// Verify all methods with an "Async" suffix return Task or ValueTask
await Expect.That(In.AssemblyContaining<PlaylistService>()
        .Methods().WithName("Async").AsSuffix())
    .Return<Task>().OrReturn<ValueTask>();

// Verify controllers follow the naming convention
await Expect.That(In.AllLoadedAssemblies()
        .Types().WhichInheritFrom<ControllerBase>())
    .HaveName("Controller").AsSuffix();

// Verify each event handler is named after the event it handles (e.g. "OnTrackAdded")
await Expect.That(In.AssemblyContaining<Playlist>()
        .Methods().Which(m => m.GetParameters().Length == 1))
    .HaveName(method => "On" + method.GetParameters()[0].ParameterType.Name);

// Verify each serializable type has exactly one parameterless constructor
await Expect.That(In.AllLoadedAssemblies()
        .Types().With<SerializableAttribute>())
    .ContainConstructors(c => c.WithNoParameters()).Exactly(1);

Overview

Each filter narrows a selection and its expectation counterpart verifies it, e.g. .WhichArePublic() and .IsPublic() (.ArePublic() for collections):

• Common filters: access modifiers, attributes, the obsolete marker, names and namespaces of types and members, e.g. WhichArePublic / IsPublic or With<TAttribute> / Has<TAttribute>
• Assemblies: name, target framework, version, strong name and dependencies, e.g. WhichTarget / Targets or WhichDependOn / DependsOn
• Types and inheritance: kinds of types, base classes, interfaces and contained members, e.g. WhichAreClasses / IsAClass or WhichInheritFrom<T> / InheritsFrom<T>, and how inherited members count
• Methods, operators and constructors: return types and parameters, e.g. WhichAreAsync / IsAsync, WhichReturn<T> / Returns<T> or WithParameter<T> / HasParameter<T>
• Properties, fields and events: member types, nullability and accessors, e.g. WhichAreOfType<T> / IsOfType<T> or WhichAreRequired / IsRequired

The overview lists all topics, including combined filters, custom predicates (Which / Satisfies, Except) and quantifiers.

Each filter and expectation has its negation where it makes sense, e.g. WithoutName / DoesNotHaveName, WithoutNamespace / DoesNotHaveNamespace, WhichAreNotOfType<T> / IsNotOfType<T>, WhichDoNotReturn<T> / DoesNotReturn<T>, WithoutParameter<T> / DoesNotHaveParameter<T> or WhichDoNotTarget / DoesNotTarget. On a collection, a negated expectation (DoNotReturn<T>, AreNotOfType<T>, …) verifies that none of the items match. The tables in Filters and expectations list every negation in a Negated column.

The name filters and expectations accept the string matching options like AsPrefix(), AsSuffix() or AsWildcard(). Filters and expectations documents the complete vocabulary.

Architecture rules

There is no separate rule engine: a "layer" is just a reusable type selection, and an architecture rule is just an expectation on it. Combine several rules into a single verification with Expect.ThatAll:

Filtered.Types domainTypes         = Types.InNamespace("MusicStore.Domain");
Filtered.Types infrastructureTypes = Types.InNamespace("MusicStore.Infrastructure");

await Expect.ThatAll(
    Expect.That(domainTypes).DoNotDependOn(infrastructureTypes),
    Expect.That(domainTypes).AreSealed());

A failing rule reports all violations, numbered per expectation:

Expected all of the following to succeed:
 [01] Expected that types within namespace "MusicStore.Domain" in all loaded assemblies all do not depend on types within namespace "MusicStore.Infrastructure" in all loaded assemblies
 [02] Expected that types within namespace "MusicStore.Domain" in all loaded assemblies all are sealed
but
 [01] it contained types with the dependency
 [02] only 1 of 3 were

[01] Not matching items:
[
  PlaylistService
]

[02] Not matching items:
[
  Album,
  Track
]

[02] Collection:
[
  Album,
  PlaylistService,
  Track
]

The dependency rules (DependOn / DependOnlyOn / HaveDependenciesOutside), dependency cycle detection (HaveNoDependencyCycles) and exemptions (Except) are documented in Architecture rules.

Customization

Set a value under Customize.aweXpect.Reflection() for the current async flow, or under Customize.aweXpect.Global.Reflection() for all tests.

Documentation

The full documentation is available at docs.testably.org:

• Selecting types and members: the In and Types sources and navigating between assemblies, types and members
• Filters and expectations: the complete reference for all subject kinds, string matching options and quantifiers
• Architecture rules: type dependencies, dependency cycles and layers as type selections
• Customization: assembly exclusions, compiler-generated members and the dependency resolver
• Comparisons: feature maps against FluentAssertions and against NetArchTest and ArchUnitNET