All jobs

Add Architecture Tests to a .NET Clean Architecture Solution

Yes. An agent reads your project graph and namespaces, writes NUnit architecture tests that fail when a layer reaches across the boundary, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the repository into its own cloud sandbox and reads the solution before it writes a test. In a solution like jasontaylordev/CleanArchitecture, CleanArchitecture.slnx lists seven projects under src/ (Domain, Application, Infrastructure, Web, Shared, ServiceDefaults, AppHost) and six under tests/. The ProjectReference lines give the intended direction: Application references Domain only, Infrastructure references Application and Shared, Web references Application, Infrastructure and ServiceDefaults, and Domain references nothing but the MediatR.Contracts package. The namespaces follow the folders: CleanArchitecture.Domain.Entities, CleanArchitecture.Domain.Events, CleanArchitecture.Application.Common.Behaviours, CleanArchitecture.Application.TodoItems.Commands.CreateTodoItem, and so on. Tests use NUnit with Shouldly, versions come from Directory.Packages.props (central package management, nunit 5.0.0, NUnit3TestAdapter 6.3.1, Shouldly 4.3.0), Directory.Build.props sets net10.0 with TreatWarningsAsErrors, and .github/workflows/build.yml runs dotnet restore, dotnet build --no-restore --configuration Release and dotnet test --no-build --configuration Release.

It also reads what the existing tests do not cover. tests/Domain.UnitTests has one folder, ValueObjects, and tests/Application.UnitTests holds mapping, behaviour and exception tests; nothing checks that the layering holds. One detail becomes the first assertion: Application.UnitTests.csproj references Infrastructure, which the tests themselves need, but nothing stops a handler in Application from importing an Infrastructure type once the reference exists somewhere in the build. The agent notes that Web endpoints call into Application through ISender (src/Web/Endpoints/TodoItems.cs) and that Infrastructure implements Application.Common.Interfaces, which is exactly the shape the tests should pin down.

It then adds tests/Architecture.Tests/Architecture.Tests.csproj, registered in the slnx under /tests/, with NetArchTest.Rules added as a PackageVersion in Directory.Packages.props and a PackageReference without a version in the new project, following how every other test project is written. The tests load each assembly by a marker type (BaseEntity for Domain, DependencyInjection for the others) and assert with Types.InAssembly(...).That()...ShouldNot().HaveDependencyOnAny(...): Domain depends on neither Application, Infrastructure nor Web; Application depends on neither Infrastructure nor Web; Infrastructure does not depend on Web; command and query handlers in Application are not public outside their feature folder; classes in Domain.Entities inherit BaseAuditableEntity or BaseEntity; and every IRequestHandler implementation lives in a namespace under CleanArchitecture.Application. Each failing rule reports the offending type names through GetResult().FailingTypeNames, which the test prints with Shouldly so the failure says what crossed the line.

It runs dotnet restore, dotnet build --configuration Release and dotnet test tests/Architecture.Tests --configuration Release in the sandbox, with TreatWarningsAsErrors making any analyzer warning a build failure, and then the full dotnet test to show the existing projects still pass alongside the new one. The CI workflow needs no change because it already tests the whole solution, and the agent says so instead of touching it. If a rule fails against the current code, it keeps the rule, lists the failing types in the pull request and marks the test with an Explicit attribute and a comment naming the violation, rather than loosening the rule to make the build green.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add architecture tests to this .NET solution. Read the solution file, every ProjectReference and the namespace layout first, then add a new NUnit test project under tests/ that uses NetArchTest.Rules to assert the dependency direction between Domain, Application, Infrastructure and Web, that handlers and their requests stay inside the Application project, and that entities derive from the shared base classes. Register the package through Directory.Packages.props and the project in the solution file, following the existing test projects. Run the new tests and the full dotnet test, report any rule the current code already breaks without weakening it, and open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request on its own branch that adds tests/Architecture.Tests/ with its project file and test classes, adds one PackageVersion line to Directory.Packages.props and one Project line to CleanArchitecture.slnx. The description lists each rule in plain words next to the assembly it inspects, shows the dotnet test output for the new project and for the whole solution from the sandbox, and names any type that already violates a rule.

The run's record keeps the restore, build and test commands with their output, so a reviewer can see the tests ran on the net10.0 target the solution pins and that nothing else changed.

Before merging, a reviewer reads the rule list and decides which ones are policy for this team, for example whether Web may reference Infrastructure at all or only through dependency injection registration, and whether any Explicit test should become a fix in the offending project instead.

Run it on every pull request that adds a project reference

After the merge, the tests themselves do the ongoing work: every pull request runs them through the existing build.yml, and a handler that imports from the wrong layer fails the build with the type name in the log. In the console, an automation in the Project that has the repository, with a github trigger on pull_request.opened and pull_request.synchronize and branch_patterns for your default branch, starts one run per pull request, with the pull request as its context; its prompt asks the run to comment with the rule to add when the pull request adds a ProjectReference or a new src/ project that the architecture tests do not yet know about, and to stop otherwise.

For several solutions, a script sends one POST /o/{org}/sessions per repository with this body, each with a fresh UUID as request_id so a retry returns the run already started. Each run reads that solution's own project graph, so the rules match its layers rather than a template.

The use case this job follows, with its automation and trigger: Write the missing tests.

Why run it on Rush?

Layer violations are cheap to make and expensive to find later: one using of an Infrastructure type in a handler compiles fine today and is a refactor in a year. The rules only have value when they are written against the real project graph, and the agent reads that graph, the namespaces and the base classes from the repository, runs the tests in its sandbox and reports which rules the code already fails instead of asserting only what passes.

The sandbox is its own computer with the .NET SDK from global.json, and every restore, build and test stays in the run's record. Several solutions can be covered at once in separate sandboxes, each with a rule set and a pull request of its own.

Frequently asked questions

Does this change any production project?

No. The change is a new test project, one package version line and one solution entry. The src/ projects are read, not edited, and if a rule finds a violation the agent reports it rather than moving code.

Why NetArchTest rather than another library?

It runs inside the NUnit project the solution already uses, needs one package and expresses rules as fluent predicates over assemblies and namespaces, which matches the way the solution is organised. If you prefer ArchUnitNET, the prompt can name it and the rules translate one for one.

What happens when a rule fails against the current code?

The agent keeps the rule, lists the failing type names in the pull request and marks that one test Explicit with a comment naming the violation, so the build stays green and the debt is visible. Loosening the rule is a reviewer's decision, not the agent's.

Will the tests slow down CI?

They load a handful of assemblies that the build has already produced and inspect types with reflection. The pull request shows the test project's duration from the sandbox run next to the existing projects, and the workflow needs no new step.

More .NET jobs

The same job on other stacks

More jobs like this: Write the missing tests

Keep reading