Testing as a First-Class Citizen of Architecture

Gáspár Nagy dropped a few interesting ideas and thoughts during the keynote of Living Documentation Event 2025. One of them was about testing and clean architecture, Or hexagonical-, union- or port and adaptors- architecture for that matter. Here is a quick recap of what clean architecture is about.

The core concept is that all business rules and logic are encoded in Application & Domain. The layers Api / UI, sometimes called Presentation, and Infra (Infrastructure) keep the core clean from external influence like user interfaces, database details and such. The goal is that the core stays clean from all kinds of implementation details that do not contribute to actual business logic.

Gáspár Nagy pointed out that Test could or berhaps should be a first-class citizen of the clean architecture as depicted below.

Then later in a Reqnroll workshop by Bas Dijkstra and Gáspár I was reminded that the use of BDD style test using Gherkin (Given… When… Then…) only makes sense when you actually treat them as specifications. Because that is what it is a way to make specifications executable. If it is just about testing then there are probably easier ways to write them without the need of the extra complexity that Gherkin brings. It is a good reminder because I sometimes tend to get a bit carried away with Reqnroll…..

During that same workshop some people asked why anyone would actually need Reqnroll if there are already so many other tools. Why would you bother having another tool? For me that was a simple answer: “I work mostly in .NET and to get things adopted quickly it really helps that underlying technology is known already.”. So as a developer I understand that every language needs som sort of BDD tool. But from a testing (or actually specification) point of view it might not be so obvious to have all these different tools on the market. And I under stand that why should you use Reqnroll if you are happily using Cucumber to call an API and asserts the results? There is no good reason to your BDD framework to be the same as the technology as the software under test if all you do is JSON over HTTP.

How it all falls together

And then I realized. You do need Reqnroll if the software under test is written in C#! It is all about having specifications that are executable. I believe that when executing clean architecture properly, then most of the specifications (e.g. business logic) is encoded in the core (Application & Domain). Usually quite some effort is spent into keeping the core clean by making sure that an API call or the UI follow the same C# call into the core logic for example. This means that such calls should allow specifications to be executed without the need of any UI, Api or underlying Database. And to do so you do need a BDD framework that is able to make those C# calls! Also this very much makes these test very much a first-class citizen of the architecture. Any specification that cannot be checked in that manner might be feedback on how well the clean architecture is executed.

Sure you still need to assure that the whole thing works in an integrated way. But testing and specification checking should absolutely be an integral part of the architecture.

I help organisations and developers to build better software faster. Feel free to reach out if you want to know more.