aweXpect.Reflection 4.0.0-pre.4

aweXpect.Reflection

aweXpect.Reflection extends aweXpect with expectations for reflection types, so you can write architecture and convention tests for assemblies, types and members.

Installation

dotnet add package aweXpect.Reflection --prerelease

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;.

The examples write That(...) instead of Expect.That(...), which needs using static aweXpect.Expect; (see Getting started).

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 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 That(In.AllLoadedAssemblies()
        .Public.Classes()
        .WhichContainMethods(m => m.With<FactAttribute>().OrWith<TheoryAttribute>()))
    .HaveName("Tests").AsSuffix();

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

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

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

// Verify each event handler is named after the event it handles (e.g. "OnTrackAdded")
await 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 That(In.AllLoadedAssemblies()
        .Types().With<SerializableAttribute>())
    .ContainConstructors(c => c.WithNoParameters()).Exactly(1);

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(
    That(domainTypes).DoNotDependOn(infrastructureTypes),
    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.

Overview

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

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.

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