I have worked on many .NET Projects. Often, as the project grows, maintaining architecture becomes harder than writing new features.

Developers unintentionally add dependencies between layers, violate module boundaries, or create classes without interfaces, which can weaken your testability and design. Over months, your architecture drifts away from its original rules, and refactoring becomes risky and expensive.

Every .NET developer knows the importance of unit tests and integration tests - they verify that code works correctly. However, even the most complete test suite cannot tell you whether your codebase structure still follows your intended architectural design.

Then I found that Architecture Tests can prevent such issues.

Architecture Tests ensure that your system's design rules are enforced and that your code follows the architecture you've set up.

In this post, we will explore:

• What architecture tests are and why they matter
• Writing your first architecture tests in .NET with NetArchTest
• Enforcing Clean Architecture and layer isolation
• Testing modular boundaries in Modular Monoliths

Let's dive in.

Architecture tests are automated checks that verify the high-level design rules of your system. Not just whether methods or API endpoints return correct results, but whether your project structure and dependencies match your intended architecture.

They ensure that your layers, modules, classes, and namespaces interact correctly. For example:

• The Domain layer should not depend on the Infrastructure layer.
• The Application layer should reference Domain, but not the Presentation project.
• Modules inside a Modular Monolith should communicate through public contracts, not directly reference each other.
• All entities should inherit from a common base Entity class.
• All your application handlers should have the Handler suffix in their names.

You can think of architecture tests as unit tests for your architecture, which verify the structure.

Let's say you have the following .NET solution:

1OrdersApi.sln
2│
3├── Domain
4├── Application
5├── Infrastructure
6└── Presentation

When a project starts, architecture is nice and clean. Each developer understands that the layer boundaries and dependencies are simple.

But as the project grows, developers make shortcuts:

• "Let's just call the repository directly from the controller."
• "We need a helper class from Infrastructure inside the Domain."
• "We can reuse this service across modules - just add a reference."
• Forget to add essential prefixes and suffixes to class names.
• Forget to inherit their classes from a common base class or an interface.

These small violations accumulate silently. Without architecture tests, no one notices - the build succeeds, the app runs.

Yet, your architecture starts to drift — and by the time it becomes visible, refactoring becomes costly.

With architecture tests, the build would fail immediately, warning the team that the dependency violates the architecture.

This turns your architecture into enforceable documentation.

For writing Architecture tests, you can use one of the two libraries:

• NetArchTest
• ArchUnitNET

I have mainly used NetArchTest, so let's see how to get started with it.

For architecture tests, I create a separate test project with xUnit.

To get started with NetArchTest, add the NuGet package to your test project:

bash
1dotnet add package NetArchTest.Rules

Let's write our first architecture test.

With NetArchTest, you can enforce conventions.

Let's verify that all Controllers have the [ApiController] attribute:

csharp
1[Fact]
2public void Controllers_Should_Have_ApiController_Attribute()
3{
4    // Act
5    var result = Types
6        .InAssembly(ApiAssembly)
7        .That()
8        .HaveNameEndingWith("Controller")
9        .Should()
10        .HaveCustomAttribute(typeof(Microsoft.AspNetCore.Mvc.ApiControllerAttribute))
11        .GetResult();
12
13    // Assert
14    Assert.True(result.IsSuccessful, FormatFailure(result));
15}
16
17private static string FormatFailure(TestResult result)
18{
19    if (result.FailingTypes is null || !result.FailingTypes.Any())
20    {
21        return "Architecture rule failed.";
22    }
23
24    return "Architecture rule failed. Offending types: " +
25       string.Join(", ", result.FailingTypeNames);
26}

Let's explore another practical example.

In most Clean Architecture or DDD-style .NET solutions, you define a base Entity class in your Domain layer.

Every aggregate root and entity should inherit from this class to ensure:

• Consistent identity handling
• Equality comparison
• Using Domain events implementation
• Common conventions across your Domain.

Let's write an architecture test that verifies this rule:

csharp
1[Fact]
2public void All_Domain_Entities_Should_Inherit_From_Base_Entity()
3{
4    // Arrange
5    var result = Types
6        .InAssembly(DomainAssembly)
7        .That()
8        .ResideInNamespace(DomainNamespace)
9        .And()
10        .AreClasses()
11        .Should()
12        .Inherit(typeof(Common.Domain.Entity))
13        .GetResult();
14
15    // Assert
16    Assert.True(result.IsSuccessful, FormatFailure(result));
17}

In Clean Architecture, you have a Domain layer, an Application layer, an Infrastructure layer and a Presentation layer.

Here are the layer boundaries:

• Domain → should not depend on any other layers
• Application → can only depend on the Domain layer
• Presentation → can depend on Domain and Application
• Infrastructure → can depend on Application and Domain

We can enforce this with NetArchTest.

Domain should not depend on any other layers:

csharp
1using NetArchTest.Rules;
2using Xunit;
3
4namespace Shipments.Tests.Architecture;
5
6public class CleanArchitectureTests
7{
8    private const string Domain = "Shipments.Domain";
9    private const string Application = "Shipments.Application";
10    private const string Infrastructure = "Shipments.Infrastructure";
11    private const string Api = "Shipments.Api";
12
13    [Fact]
14    public void Domain_Should_Not_Depend_On_Application_Infrastructure_Or_Api()
15    {
16        var result = Types
17            .InAssembly(DomainAssembly)
18            .That()
19            .ResideInNamespace(Domain)
20            .ShouldNot()
21            .HaveDependencyOn(Application)
22            .AndShouldNot()
23            .HaveDependencyOn(Infrastructure)
24            .AndShouldNot()
25            .HaveDependencyOn(Api)
26            .GetResult();
27
28        Assert.True(result.IsSuccessful, FormatFailure(result));
29    }
30}

This test finds all types in Shipments.Domain. It asserts that none of them depend on Shipments.Application, Shipments.Infrastructure or Shipments.Api.

If someone adds a reference, the test fails and shows the offending types. This is exactly how we stop accidental design drift.

Let's add more rules to match a typical Clean Architecture setup:

csharp
1public class CleanArchitectureTests
2{
3    [Fact]
4    public void Application_Should_Depend_On_Domain_Only()
5    {
6        var result = Types
7            .InAssembly(ApplicationAssembly)
8            .That()
9            .ResideInNamespace(Application)
10            .ShouldNot()
11            .HaveDependencyOn(Infrastructure)
12            .AndShouldNot()
13            .HaveDependencyOn(Api)
14            .GetResult();
15
16        Assert.True(result.IsSuccessful, FormatFailure(result));
17    }
18
19    [Fact]
20    public void Api_Should_Not_Depend_On_Infrastructure()
21    {
22        var result = Types
23            .InAssembly(ApiAssembly)
24            .That()
25            .ResideInNamespace(Api)
26            .ShouldNot()
27            .HaveDependencyOn(Infrastructure)
28            .GetResult();
29
30        Assert.True(result.IsSuccessful, FormatFailure(result));
31    }
32}

Architecture tests are also very useful in Modular Monoliths as they have the following requirements:

• Modular Monolith has clear boundaries between its modules.
• Modules can't access a database of other modules directly.
• Modules can talk with each other only via a public API.

A modular monolith organizes code into separate modules that handle different business capabilities.

These boundaries are not just folders or namespaces. They represent business domains that should remain independent of each other.

When boundaries are clear, teams can work on different modules without affecting other modules.

The problem is that boundaries in a modular monolith are logical, not physical. Unlike microservices, where modules run in separate processes, all modules in a modular monolith share the same codebase. This makes it easy to violate boundaries.

A developer working on the Shipments module needs carrier information. Instead of using the proper integration API, they reference the Carriers.Domain namespace directly.

The compiler allows it. The code works. But the architecture is broken.

Let's explore an application with three core modules: Shipments, Carriers and Stocks:

• Shipments Module: Handles creating orders for shipments.
• Carriers Module: Maintains information about shipping partners and registers shipments for delivery.
• Stocks Module: Manages product inventory levels.

Each module exposes an interface that allows other modules to call it. Under the hood, it's a method call in the same process.

Each module has its own database schema and DbContext for EF Core, providing clear separation of data.

When creating a shipment, the Shipments Module needs to:

1. Checks if a Shipment for a given OrderId is already created in its database
2. Calls the Stocks Module to check the products' availability
3. Creates a Shipment in the database
4. Calls the Carrier Module to save the shipment details
5. Calls the Stocks Module to update stock levels

Here is a project's structure:

Architecture tests need to reference the assemblies they will check. Let's create a helper class that holds all module assembly references:

csharp
1internal static class ModuleAssemblies
2{
3    // Shipments module assemblies
4    internal static readonly Assembly ShipmentsDomainAssembly = Shipments.Domain.AssemblyReference.Assembly;
5    internal static readonly Assembly ShipmentsFeaturesAssembly = Shipments.Features.AssemblyReference.Assembly;
6    internal static readonly Assembly ShipmentsInfrastructureAssembly = Shipments.Infrastructure.AssemblyReference.Assembly;
7
8    // Stocks module assemblies
9    internal static readonly Assembly StocksDomainAssembly = Stocks.Domain.AssemblyReference.Assembly;
10    internal static readonly Assembly StocksFeaturesAssembly = Stocks.Features.AssemblyReference.Assembly;
11    internal static readonly Assembly StocksInfrastructureAssembly = Stocks.Infrastructure.AssemblyReference.Assembly;
12    internal static readonly Assembly StocksPublicApiAssembly = Stocks.PublicApi.AssemblyReference.Assembly;
13
14    // Carriers module assemblies
15    internal static readonly Assembly CarriersDomainAssembly = Carriers.Domain.AssemblyReference.Assembly;
16    internal static readonly Assembly CarriersFeaturesAssembly = Carriers.Features.AssemblyReference.Assembly;
17    internal static readonly Assembly CarriersInfrastructureAssembly = Carriers.Infrastructure.AssemblyReference.Assembly;
18    internal static readonly Assembly CarriersPublicApiAssembly = Carriers.PublicApi.AssemblyReference.Assembly;
19}

This approach requires each project in every module to have an AssemblyReference class:

csharp
1public static class AssemblyReference
2{
3    public static readonly Assembly Assembly = typeof(AssemblyReference).Assembly;
4}

This is a simple marker class. It exists only to provide a type that belongs to the assembly. The test project references this type, which forces the assembly to be loaded at runtime.

Here is how we can test that the Stocks module does not depend on any other module:

csharp
1private const string ShipmentsNamespace = "Modules.Shipments";
2private const string CarriersNamespace = "Modules.Carriers";
3private const string StocksNamespace = "Modules.Stocks";
4
5[Fact]
6public void StocksModule_ShouldNotHaveDependencyOn_AnyOtherModule()
7{
8    var result = Types.InAssemblies(GetStocksModuleAssemblies())
9        .Should()
10        .NotHaveDependencyOnAny(
11            CarriersNamespace,
12            ShipmentsNamespace)
13        .GetResult();
14
15    Assert.True(result.IsSuccessful, string.Join(", ", result.FailingTypeNames ?? []));
16}

This test loads all assemblies in the Stocks module and checks every type. If any type has a using statement, field, parameter, or property that references the Carriers or Shipments namespaces, the test fails.

You can download the full source code for this project from my .NET Backend Template.

Let's write a test that checks that the Shipments module references only Public API projects from Carriers or Stocks:

csharp
1private const string ShipmentsNamespace = "Modules.Shipments";
2private const string CarriersNamespace = "Modules.Carriers";
3private const string StocksNamespace = "Modules.Stocks";
4
5// Project namespaces
6private const string CarriersDomainNamespace = CarriersNamespace + ".Domain";
7private const string CarriersInfraNamespace = CarriersNamespace + ".Infrastructure";
8private const string CarriersFeaturesNamespace = CarriersNamespace + ".Features";
9private const string CarriersPublicApiNamespace = CarriersNamespace + ".PublicApi";
10
11private const string StocksDomainNamespace = StocksNamespace + ".Domain";
12private const string StocksInfraNamespace = StocksNamespace + ".Infrastructure";
13private const string StocksFeaturesNamespace = StocksNamespace + ".Features";
14private const string StocksPublicApiNamespace = StocksNamespace + ".PublicApi";
15
16[Fact]
17public void ShipmentsModule_ShouldOnlyReference_PublicApiProjects()
18{
19    var shipmentsAssemblies = GetShipmentsModuleAssemblies();
20
21    // Check that the Shipments module doesn't reference internal Carriers projects
22    var carriersInternalResult = Types.InAssemblies(shipmentsAssemblies)
23        .Should()
24        .NotHaveDependencyOnAny(
25            CarriersDomainNamespace,
26            CarriersInfraNamespace,
27            CarriersFeaturesNamespace)
28        .GetResult();
29
30    Assert.True(carriersInternalResult.IsSuccessful,
31        $"Shipments module should not reference internal Carriers projects: {string.Join(", ", carriersInternalResult.FailingTypeNames ?? [])}");
32
33    // Check that the Shipments module doesn't reference internal Stocks projects
34    var stocksInternalResult = Types.InAssemblies(shipmentsAssemblies)
35        .Should()
36        .NotHaveDependencyOnAny(
37            StocksDomainNamespace,
38            StocksInfraNamespace,
39            StocksFeaturesNamespace)
40        .GetResult();
41
42    Assert.True(stocksInternalResult.IsSuccessful,
43        $"Shipments module should not reference internal Stocks projects: {string.Join(", ", stocksInternalResult.FailingTypeNames ?? [])}");
44
45    // Verify that it DOES reference the PublicApi projects (optional positive test)
46    var hasCarriersPublicApiDep = Types.InAssemblies(shipmentsAssemblies)
47        .That()
48        .HaveDependencyOn(CarriersPublicApiNamespace)
49        .GetTypes()
50        .Any();
51
52    var hasStocksPublicApiDep = Types.InAssemblies(shipmentsAssemblies)
53        .That()
54        .HaveDependencyOn(StocksPublicApiNamespace)
55        .GetTypes()
56        .Any();
57
58    Assert.True(hasCarriersPublicApiDep || hasStocksPublicApiDep,
59        "Shipments module should reference at least one PublicApi project");
60}
61
62private static Assembly[] GetShipmentsModuleAssemblies()
63{
64    return [
65        ModuleAssemblies.ShipmentsDomainAssembly,
66        ModuleAssemblies.ShipmentsInfrastructureAssembly,
67        ModuleAssemblies.ShipmentsFeaturesAssembly
68    ];
69}

This test has three parts.

The first check ensures Shipments does not reference Carriers.Domain, Carriers.Infrastructure, or Carriers.Features. These are internal to the Carriers module.

The second check does the same for the Stocks module.

The third verifies that Shipments references only the Public API projects of the Carriers and Stocks modules.

Architecture tests are a powerful tool in a developer's toolbox. They ensure that your architecture is consistent and enforces the rules you set.

They work better than any documentation. A developer can forget some rules, and the tests will catch them.

Architecture tests are easy to write, and usually I copy a set of tests from one project to another.

Architecture tests are just regular tests; that's why I recommend running them in the CI/CD pipeline when building your application.

Hope you find this newsletter useful. See you next time.