A bad system will beat a good person every time.

– Edwards Deming

To efficiently develop software, it is crucial to control its quality, particularly the architecture and code structure. In Java, ArchUnit, a library for testing certain aspects of architecture and design, can help. In this article, I’ll present ten practical ArchUnit tests based on my experiences with developing a Spring Framework-based application.

While ArchUnit is a powerful tool, it can be challenging to fully utilize its capabilities and determine what is worth testing initially. The tests I describe didn’t come about all at once. I started with two or three simple tests and then, over the years, added more or redefined existing ones as design rules were broken. These rules can be violated for various reasons: in the rush of changes, it’s easy to forget certain principles, and new team members might not be aware of existing design constraints. Writing these rules as tests is a way to formally express architecture and design, helping maintain project quality.

As a result, I have developed a practical set of tests that I can apply to my projects, ensuring their consistency and compliance with architectural assumptions. Below, I present these tests using the ArchUnit library, which I employ in almost every Java project. If you find them useful, simply copy them into your project.

Context

Some of the described tests are universal, while others are more tied to the project structure. To better understand and adapt them, here’s an example package structure:

pl.tfij.example
+--- users
|    |--- domain
|    \--- infrastructure
+--- orders
|    |--- domain
|    \--- infrastructure
+--- products
|    |--- domain
|    \--- infrastructure
\--- commons

This structure is not a typical layered architecture. Therefore, in this post, you won’t find tests like “controllers use services, and services use repositories”.

Secondly, I place all ArchUnit tests in a single test class, where I declare two constants useful for the tests. When describing the tests in this article, I assume they are embedded in such a class:

class ArchitectureTest {
    private static final String PROJECT_PACKAGE = "pl.tfij.example";

    private static final JavaClasses ALL_SERVICE_CLASSES = new ClassFileImporter()
            .withImportOption(new ImportOption.DoNotIncludeTests())
            .importPackages(PROJECT_PACKAGE);
    
    // ...
}

When writing about architecture tests, it’s worth mentioning a good practice. If an architectural rule is documented, for example, in an ADR (Architecture Decision Record), it’s beneficial for the test verifying this rule to link to that document. The test should clearly indicate why a particular invariant is important. We should avoid situations where a failing test leaves a developer wondering, “But why? What’s wrong with doing it this way?”. Such situations can lead to the test being removed, and the original architectural assumptions being lost.

1. Cycles in the Project

One of the most popular ArchUnit tests is cycle verification. It’s a simple yet important test to start with.

@Test
@DisplayName("Packages should be free of cycles")
void packagesShouldBeFreeOfCycles() {
    slices()
            .matching("%s.(**)".formatted(PROJECT_PACKAGE))
            .should().beFreeOfCycles()
            .check(ALL_SERVICE_CLASSES);
}

2. Module Dependencies

In the previously presented package structure, the first-level modules are users, orders, products, and commons. It’s crucial for these modules’ dependencies to be clear and in line with assumptions, for instance, users should not depend on products. ArchUnit doesn’t have a module abstraction but provides a way to test layered architecture, like ensuring controllers depend on services and services on repositories. Treating modules as layers, we can define a test to verify module dependencies.

@Test
@DisplayName("Each module should depend only on declared modules")
void modulesDependencyTest() {
    layeredArchitecture()
            .consideringOnlyDependenciesInLayers()
            .ensureAllClassesAreContainedInArchitectureIgnoring(PROJECT_PACKAGE)
            .layer("users")   .definedBy("pl.tfij.example.users..")
            .layer("orders")  .definedBy("pl.tfij.example.orders..")
            .layer("products").definedBy("pl.tfij.example.products..")
            .layer("commons") .definedBy("pl.tfij.example.commons..")
            .whereLayer("users")   .mayOnlyAccessLayers("commons")
            .whereLayer("orders")  .mayOnlyAccessLayers("users", "products", "commons")
            .whereLayer("products").mayOnlyAccessLayers("commons")
            .whereLayer("commons") .mayNotAccessAnyLayer()
            .check(ALL_SERVICE_CLASSES);
}

Representing modules as layers introduces some noise into the test, but it is the most concise solution in ArchUnit for achieving the goal of verifying module dependencies.

3. Code Compliance with Documentation

Another way to verify dependencies between modules is by using a PlantUML diagram, which also helps control if documentation is up-to-date (if the documentation, including the PlantUML diagram, is stored alongside the code). In the described case, we can define a component diagram in PlantUML:

@startuml

component users <<..users..>>
component products <<..products..>>
component orders <<..orders..>>

users <-- orders
products <-- orders

@enduml

I intentionally omitted the commons module from the diagram to maintain readability, especially important for more complex systems with many modules. Below is the rendered version of the diagram.

ArchUnit has built-in support for PlantUML. Although only a subset of the syntax is supported, our code can be verified against a simple diagram like the one above. The test to achieve this looks like:

@Test
@DisplayName("The code should follow the architecture diagram")
void codeShouldFollowArchitectureDiagram() {
    classes()
            .should(adhereToPlantUmlDiagram(
                    "doc/KeyModulesDependencies.puml",
                    consideringOnlyDependenciesInDiagram()))
            .check(ALL_SERVICE_CLASSES);
}

It should be noted that this test has certain limitations. If the diagram shows a dependency A on B, the test will pass even if such a dependency is not present in the code. In other words, the diagram defines possible transitions, which may or may not appear in the code.

4. Domain Should Not Depend on Infrastructure

A fundamental rule of hexagonal architecture, ports and adapters, onion architecture, or clean architecture is the dependency inversion principle – high-level modules should not directly depend on low-level modules. Specifically, the domain should not depend on the infrastructure; rather, the infrastructure may depend on the domain. This rule can be verified with a simple test:

@Test
@DisplayName("Domain should not depend on infrastructure")
void domainShouldNotDependOnInfrastructure() {
    classes()
            .that().resideInAPackage("..domain..")
            .should().onlyDependOnClassesThat().resideOutsideOfPackage("..infrastructure..")
            .check(ALL_SERVICE_CLASSES);
}

If the project strictly follows hexagonal architecture guidelines, we can define tests like:

@Test
@DisplayName("The order module should follow the onion architecture")
void verifyOrdersOnion() {
    onionArchitecture()
            .domainModels("pl.tfij.example.orders.domain.model..")
            .domainServices("pl.tfij.example.orders.domain.service..")
            .adapter("persistence", "pl.tfij.example.orders.infrastructure.persistence..")
            .adapter("rest", "pl.tfij.example.orders.infrastructure.rest..");
}

In this case, we must define a separate test for each module. This test more strictly controls adherence to principles of consistency and responsibility of individual packages.

5. Domain Should Not Depend on Database Internals

So far, we have ensured that the domain package does not depend on infrastructure. However, there is no guarantee that a class from the infrastructure is placed in the correct location. In one project, it turned out that a class containing SQL code ended up in the domain. To prevent such mistakes, we added a test:

@Test
@DisplayName("Domain should not depend on database internals")
void domainShouldNotDependOnDatabaseInternals() {
    classes()
            .that().resideInAPackage("..domain..")
            .should().onlyDependOnClassesThat().resideOutsideOfPackages(
                    "org.springframework.jdbc.**",
                    "java.sql.**",
                    "jakarta.persistence.**")
            .check(ALL_SERVICE_CLASSES);
}

Similarly, we can exclude packages related to Kafka, JSON serialization, or other technologies that should not appear in the domain. These types of tests help ensure that domain code remains clean and independent of technical details, which is key to maintaining clarity and flexibility in architecture.

Alternatively, instead of defining packages that are prohibited in the domain, you can define a set of packages that are allowed. Personally, however, I prefer defining a blacklist, as the test is more stable in the face of changes, especially in the early stages when the project is rapidly evolving.

6. Constructor Injection

A good practice in Spring is to inject dependencies (dependency injection – not to be confused with the aforementioned dependency inversion) through the constructor, not through fields or setters. There are many articles online on this topic, such as Reflectoring: Constructor Injection. To ensure that there is no field-based injection, we just need to check that no field is annotated with @Autowired or @Value.

@Test
@DisplayName("Should not inject by field (required injection by constructor)")
void shouldNotInjectByField() {
    fields()
            .should().notBeAnnotatedWith(Autowired.class)
            .andShould().notBeAnnotatedWith(Value.class)
            .check(ALL_SERVICE_CLASSES);
}

This test ensures that all dependencies are constructor-based, which is considered best practice in Spring.

7. Metrics

In Spring, it’s easy to collect metrics using Micrometer, and good metrics are a crucial element in maintaining an application in a production system. Specifically, we should have data on every endpoint. Therefore, every public controller method should be annotated with @Timed. It’s easy to forget to add such an annotation. Fortunately, we can safeguard against this with an ArchUnit test:

@Test
@DisplayName("Controller public methods should be annotated with @Timed")
void controllerPublicMethodsShouldBeAnnotatedWithTimed() {
    methods()
            .that().areDeclaredInClassesThat().haveNameMatching(".*Controller")
            .and().areDeclaredInClassesThat().areNotInterfaces()
            .and().areNotPrivate()
            .should().beAnnotatedWith(Timed.class)
            .check(ALL_SERVICE_CLASSES);
}

In my projects, service classes are the entry points to the domain. Therefore, I also collect metrics for each public method in the service classes.

@Test
@DisplayName("Service public methods should be annotated with @Timed")
void servicePublicMethodsShouldBeAnnotatedWithTimed() {
    methods()
            .that().areDeclaredInClassesThat().haveNameMatching(".*Service")
            .and().areDeclaredInClassesThat().areNotInterfaces()
            .and().areNotPrivate()
            .should().beAnnotatedWith(Timed.class)
            .check(ALL_SERVICE_CLASSES);
}

8. Naming Conventions

In different projects, controllers might have various names such as *Controller, *Endpoint, *Resource, *Api, *Handler. However, a naming standard is often not consistently maintained within a single project. It’s worth defining ArchUnit tests to ensure that all controller classes end with, for example, Controller.

@Test
@DisplayName("Controller classes should end with 'Controller'")
void controllersShouldEndWithController() {
    classes()
            .that().areAnnotatedWith(RestController.class)
            .should().haveNameMatching(".*Controller")
            .check(ALL_SERVICE_CLASSES);
}

Similarly, you can test the names of Repository, Entity classes, or the package names in which they are placed. This ensures consistency and makes maintaining the code easier.

9. Each Module Should Have a Single Configuration Class

In my projects, I adhere to the rule that each module should have a single entry point - one class that can produce a configured module. This can be described as a factory for a configured module. For me, this is a Config class that creates a bean serving as the module’s facade. In other words, each module should have one and only one configuration class. This configuration class is also used in unit tests to produce the module to test. This makes verifying the domain part of the entire module easier.

A test ensuring the existence of a single configuration class is somewhat more complex than the tests presented earlier:

@Test
void eachInfrastructurePackageShouldContainSingleConfigClass() {
    // Import classes from the package
    JavaClasses importedClasses = new ClassFileImporter().importPackages(PROJECT_PACKAGE);
    // Identify infrastructure packages
    Set<String> infrastructurePackages = importedClasses.stream()
            .map(JavaClass::getPackageName)
            .filter(packageName -> packageName.endsWith(".infrastructure") || packageName.contains(".infrastructure."))
            .map(packageName -> packageName.substring(0, packageName.indexOf(".infrastructure") + ".infrastructure".length()))
            .collect(Collectors.toSet());
    // Find *Config classes in each infrastructure package
    Map<String, List<String>> configClassesByPackage = infrastructurePackages.stream()
            .collect(Collectors.toMap(
                    packageName -> packageName,
                    packageName -> findConfigClassesInGivenPackage(importedClasses, packageName)));
    // Verify if each infrastructure package has exactly one *Config class
    configClassesByPackage.forEach((packageName, configClasses) -> {
        Assertions.assertEquals(1, configClasses.size(),
                "Package `%s` should contain exactly one *Config class but contains %s".formatted(
                        packageName,
                        String.join(", ", configClasses)));
    });
}

private static List<String> findConfigClassesInGivenPackage(JavaClasses importedClasses, String packageName) {
    return importedClasses.stream()
            .filter(javaClass -> javaClass.getPackageName().startsWith(packageName))
            .map(JavaClass::getSimpleName)
            .filter(className -> className.endsWith("Config"))
            .toList();
}

This test ensures that each module in the project has exactly one configuration class named Config. Such an organization of the code makes managing module configurations and testing them easier. It makes it easy to find and understand where the configuration for each module is located.

10. Beans Created in Configuration Class

In my code, I do not use annotations like @Service or @Component. Such beans should be created in a configuration class using @Bean. This is consistent with the previously described rule that the config class is a factory providing a configured module. This can be verified with a test:

@Test
@DisplayName("Classes should not be annotated with @Service or @Component (create beans in a config class)")
void classesShouldNotBeAnnotatedWithService() {
    classes()
            .should().notBeAnnotatedWith(Service.class)
            .andShould().notBeAnnotatedWith(Component.class)
            .check(ALL_SERVICE_CLASSES);
}

This test verifies that all beans are created in configuration classes rather than using the @Service or @Component annotations on the classes. This allows centralized management of bean configurations in the project, making it easier to monitor, modify, and test them.

ArchUnit Limitations

ArchUnit works based on compiled code. This entails certain limitations that should be acknowledged. For instance, constant literals can be inlined, and a dependency that exists in the source code might disappear in the bytecode. For example, if a public constant of type String is defined in the infrastructure. In the domain, this constant is referenced. A test verifying that the domain should not depend on the infrastructure will not catch such a dependency.

It’s important to remember that ArchUnit operates on bytecode to avoid unpleasant surprises like the one described above.

Message for Today

Add a test if you discover a violation of any design or architectural rule. If a rule has been broken once, it proves that it can be broken again.

Benoit B. Mandelbrot referred to himself as a “fractalist” and is recognized for his contribution to the field of fractal geometry, which included coining the word “fractal”, as well as developing a theory of “roughness and self-similarity” in nature.

– en.wikipedia.org

In the world of software, modularization is crucial for maintaining flexibility, scalability, and code readability. I have participated in many discussions about the ideal size of a module. These discussions often feature extreme opinions, ranging from “it’s better to have a few large modules” to “the smaller the modules, the better”. The truth, as always, lies somewhere in between, and in this post, I will point out how to pinpoint it.

What is a module?

In the world of software engineering, a module does not have a clear-cut definition. For some, modules may be microservices, for others, JAR files or packages, and for yet others, Maven modules or Gradle subprojects. This diversity in definitions complicates discussions about modularization.

For the purposes of this article, I will adopt a broad definition of a module as a logical unit of code within a program or library, having both an interface and an implementation. The simple concept is illustrated in the image below.

Thus, a module could be, for example, a microservice, a package, a class, or a method. Even a private method is a module living within a class-module. The module’s interface encompasses both formal aspects, such as an API schema (e.g. JSON schema) or method signature, and informal aspects, such as requirements regarding the order of method calls or issues related to thread safe. In other words, an informal interface is one that must be expressed in the form of documentation or comments.

This definition of a module allows us to express its complexity as the sum of the complexity of its interface and implementation. And this complexity is crucial in module design.

Deep and Shallow Modules

The concept of deep and shallow modules is a significant element in software design. This division refers to how modules are designed and how they present their interfaces to clients. Deep modules feature a small, concise interface that hides a complex implementation behind the scenes. On the other hand, shallow modules have a broad interface behind which lies a very simple implementation.

Deep modules are often preferred. Users can access advanced features through a simple interface without needing to understand all the internal details. In contrast, with shallow modules, the interface may be very extensive, but the provided functionality is relatively simple. In extreme cases, the interface may be more complex than the implementation itself. A simple example could be a method:

public createUser() {
    return new User();
}

In this case, calling createUser() is even longer than new User().

The described advantages of deep modules over shallow ones may lead to the conclusion that we should optimize the code for designing maximally deep modules. However, let’s consider how this affects the extract method or extract class operation. Extract method means creating a new method. It is a new module that has its implementation and interface. As shown in the image below, the total implementation before and after splitting remains constant: A1 ~= A2 + B. However, the total interface is larger IA < IA + IB. This means that method extraction almost always leads to an increase in the total complexity of the project. An exception may be when method extraction serves to reduce code duplication, resulting in a decrease in the total implementation.

The increase in total complexity associated with breaking down code into smaller fragments leads to the absurd conclusion that the deepest and simplest design can be achieved when all the code is placed in a single class or method. Undoubtedly, another practice is needed to balance this direction.

The Magical Number Seven

In 1956, George A. Miller, in his article titled “The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing Information”, described how the human mind can consciously process about seven pieces of information at a time.

In the context of deep modules, the magical number seven becomes a key criterion for balancing their complexity, both in depth and width. The complexity of ultra-deep modules can be so great that the human mind cannot grasp them. According to George A. Miller, the human mind can consciously process about seven pieces of information at a time. In other words, interfaces and implementations should not be too extensive or too complicated for a programmer to easily process information, use the module, and modify it as needed.

To clarify, Miller’s research concerns short-term memory and the processing of unrelated concepts. This means that the more we work with a certain code, the better we learn it, and we can start using long-term memory, making room in the highly limited short-term memory. Another issue is the limit on unrelated concepts. For example, if we have seven variables in a method with names that tell us nothing, for many people, this will be the limit of effective use of these variables. Good naming can push this limit up because the name will refer to long-term memory and the relationships between variables. Similarly, adhering to standards, conventions, and patterns can relieve short-term memory. However, regardless of how much we try to stretch psychological studies, human minds have limitations, and it is better not to exceed the threshold of seven concepts within one module.

The principle of seven concepts can also lead to an absurd extreme. By focusing on simplifying individual modules, we can create millions of micro-modules that are trivial and very shallow on their own, but their multitude introduces excessive complexity.

Synergy

From all this, a simple conclusion arises: we cannot optimize only the total complexity of the project because the human mind is not capable of processing such complex issues. A balance is needed between total complexity and local complexity, which naturally leads to the fractal nature of modules.

These two practices balance each other, allowing for the design of optimal modules. Not too large - in accordance with the principle of seven concepts, yet deep enough to be valuable and easy to use. This principle is a good starting point for module design, around which other software design practices can be applied, such as consistency in abstraction levels within the module or consistency in terms of changes.

Fractals in Software Design

Fractals are geometric structures that exhibit self-similarity across different scales. Let’s briefly consider an analogy with a tree drawn by a child. A young child often draws a tree as a green oval on a brown rectangle. However, in reality, the structure of a tree is much more complex; a large branch is composed of smaller ones, each smaller branch resembling the larger one, and so on. Even in the veins of leaves, one can discern a repeating structure similar to the branching of a tree. This analogy demonstrates that the initial view of modules in software may be too simplistic, akin to a child’s drawing of a tree.

Similarly to a fractal tree, modularization in software unfolds fractally. We start with an Organization, which we divide into subdomains, such as “Product Management”, “Order Management”, or “Customer Support”. Within these areas, there are further services, such as “Payment Processing” or “Shopping Cart Management”. In the case of “Payment Processing”, we may have multiple components handling different payment methods, transaction tracking, or analytics and reports. Depending on the architecture and complexity, each of these components may be a separate microservice, a JAR file, or simply a package. We can continue to delve deeper, reaching methods calling other methods, and so on.

In this approach, we cannot speak of an absolute size for the ideal module. Instead, modularization is multi-level; at each level, we should maintain a balance of depth and complexity limited by the cognitive capabilities of the human brain.

Message for Today

1. Deep modules and fractal modularization are important, but they are just a starting point for good design.
2. Code should be understandable even for a tired programmer.

The art of programming is the art of organizing complexity; mastering multitude & avoiding its chaos as effectively as possible.

– Edsger W. Dijkstra

Modularization in projects is one of the key techniques that allows for maintaining code readability, scalability, and ease of maintenance. As projects evolve, especially those with a larger scope, it becomes an important element ensuring order and transparency in the code structure. However, as the project progresses and new changes are introduced, and developers come and go, it’s easy to forget the initial architecture assumptions. Automated tests come to the rescue. But what should we test and how should we do it? Without solid tests, we cannot ensure that our modular structure meets the goals we set for ourselves.

What to Test

Certain aspects of modules, such as inter-module dependencies and cycles in the Java language, can be tested using ArchUnit. However, this library does not solve all problems. Let’s take a closer look at two other particularly important cases:

1. Uniform Distribution of Code

When we have many modules but one of them contains a significant majority of the code, modularization loses its meaning. For example, if we have 15 modules and one of them contains 80% of the code, we cannot speak of real modularization because almost all the code is contained in one module. This is a situation that needs to be eliminated through automated testing of module size.

2. Some Modules Should Be Especially Small

It is also important to ensure that individual modules are small and stable in terms of the changes introduced (how often we make the module changes). For example, a “commons” module should be small and contain general functionality that is often used in various parts of the project. If this module becomes too large, it can lead to problems with managing and modifying the code. Of course, this is an approximation, as it is more important to minimize the module interface and maintain its stability in terms of changes, which does not necessarily mean minimizing the module size.

How to Test

Because the issues described above are very important to me, I decided to verify them in tests. The implementation can be very simple and involve counting lines of code in packages. To my surprise, I did not find a ready-made tool that would allow me to quickly check the size of modules.

So I prepared a Java library that allows testing the size of modules - module-size-calculator. This library enables analyzing the size of modules in a project based on the number of lines of code (LOC).

Just define the dependency

<dependency>
    <groupId>pl.tfij</groupId>
    <artifactId>module-size-calculator</artifactId>
    <version>1.0.0</version>
</dependency>

From now on, we can write tests like

ProjectSummary projectSummary = ModuleSizeCalculator.project("src/main/java")
    .withModule("com.example.module1")
    .withModule("com.example.module2")
    .analyze()
    .verifyEachModuleRelativeSizeIsSmallerThan(0.3)
    .verifyModuleRelativeSizeIsSmallerThan("com.example.commons", 0.1);

The library allows for various assertions of module size, and if something has not been foreseen, a classic JUnit assertion can be written based on the generated report. The library also allows you to generate a report in the form of a Mermaid pie chart, which can then be included, for example, in documentation.

For more details and examples, visit GitHub.

Message for Today

Modularization is a key aspect of the project. Test it to ensure it does not fade over time.

Simplicity is the goal.

– Sean Parent, Menlo Innovations

The Open-Closed Principle, described in SOLID, ensures project flexibility, but does it always lead to optimal, future-ready code? It sounds promising - open for extension, closed for modification. Let’s take a closer look.

Overengineering in Light of Open-Closed

The Open-Closed Principle seems like a reasonable approach. By designing our code to easily add new features without modifying existing code, we become prepared for unexpected changes and project expansions. However, is this always necessary? This is where the problem of overengineering arises.

Overengineering is when our code is more complicated than necessary to prepare for changes and scenarios that may never occur. It’s like building a bridge in the desert, hoping it might someday be useful as a trade corridor.

Anticipating potential, but unknown, changes can lead to excessive code abstraction. Additional layers, interfaces, and structures intended to provide flexibility introduce unnecessary complexity. Additional complexity is introduced to avoid touching individual pieces of code in the future. It is the fear of future change that drives overengineering. Fear stemming from poor-quality code.

Proper Engineering

Instead of focusing on creating code that is ready for every eventuality, it is worth concentrating on proper engineering. Rather than avoiding changes, let’s focus on creating code that is easy to change. High-quality code, clean code, automated testing, modularization, high cohesion, etc. - these are the foundations that make our code flexible without unnecessary abstractions.

Engineering should focus on creating solutions that are simple and efficient. For example, when you have one discount calculation algorithm, you don’t need to implement the strategy pattern thinking, “maybe someday we’ll have a second algorithm, and it will be easy to replace”. This is overengineering entirely consistent with the open-closed principle. If the code is of good quality, introducing abstractions when needed shouldn’t be a problem.

Message for Today

Handle the Open-Closed Principle with care. Code should be easy to modify, not necessarily prepared for specific, uncertain changes.

The most important transformation for most organizations is to enable people and teams to do creative high-quality work. Large scale, incremental change is the key to achieving this.

– David Farey

In recent years, service architectures, especially microservices, have gained enormous popularity, yet the approach to end-to-end (E2E) testing often remains unchanged. We hear that tests verifying the operation of the entire system are crucial in the software development process, especially with distributed architectures. Statements like “We need to prove that the system works as a whole. We used to have a monolith and E2E tests; now we have independent microservices, so E2E tests are even more necessary” arise.

In this post, I use the term E2E tests to refer to tests of the entire system. These are cases where the test requires running multiple services. Therefore, for example, front-end tests using a browser don’t meet this definition if the backend is a service mock, stub, etc.

Mental Monolith

Overestimating the importance of whole-system tests is a symptom of monolithic thinking. When we need to test the system as a whole, it means that key attributes of distributed architecture, such as independence of changes and deployments, haven’t been achieved. Furthermore, deployment independence is ingrained in the definition of microservices. This statement could end the discussion. However, let’s take a closer look at the negative aspects of E2E tests in microservices. In the case of a service-oriented architecture, E2E tests not only involve issues of cost, speed, stability, and complexity, as described in the testing pyramid, but they also significantly affect workflow. Since their purpose is cross-team testing, a team of testers is often created to develop and maintain them. This solution isn’t scalable and introduces delays as work passes through multiple teams—from developers, through testers, to deployment/release. In another approach, responsibility for E2E tests can be shared by all teams. In this model, it’s common for changes in one service to cause errors in tests and block deployments of another team’s service. In both configurations, having multiple releases per day will be challenging, and their schedule will be susceptible to unpredictable delays. Development teams will lose independence and spend more time on communication. Introducing the first E2E test entails a range of problems, such as deciding who will maintain the E2E tests, how they will be run, how to ensure independence of development teams, and how to maintain deployment independence, etc.

The need for E2E tests may arise from two main reasons. The first is when we have a solid system with independent services, but the manager is stuck in mental monolith thinking. They don’t understand the concept of independent services with clear boundaries in the form of contracts. Fear of system stability and reluctance to take responsibility for errors in the event of a failure may also play a role. In such cases, the solution may be education or even changing the manager. In extreme cases, however, this may mean a cultural revolution in the company. The second reason is the state of our architecture, where elements form a distributed monolith and are strongly interconnected. In this case, it’s worth analyzing contracts between services, checking if E2E tests are not the result of abandoning strict contracts in favor of loose ones, if service APIs are consumed according to the X-as-a-service (XasS) pattern, or if consumer-driven contracts have been applied. Lack of contracts doesn’t just mean a lack of endpoint description. It can be reflected in formulations such as “the system must be run on a pre-production or UAT environment with production data for n days because we can’t predict all data cases and event combinations.”

If you decide to use E2E tests, make sure they are fast and stable, which is a challenge in itself. Additionally, introducing the first E2E test will have a significant impact on the entire system. It will be challenging to determine who will maintain the E2E tests and how they will affect the workflow of all teams. Therefore, limit their scope only to critical areas of the system and control their number.

Living Without Whole-System Tests

Similarly to what I wrote in another post, Documentation is not a Requirement, and above, E2E tests are not a requirement either. Consider what risks we want to minimize and what problems we want to solve with them. How else can we approach these issues? Much depends on the context; nevertheless, ultimately, in many cases, we can do without any E2E tests.

The topic of safely deploying independent services is extensive, so I don’t intend to discuss it in full here. Below, I raise a few key issues.

Firstly, define service boundaries through API contracts. These contracts should be thoroughly tested. When designing services, it’s also worth considering which processes require testing in full and why. The choice between orchestration and choreography has an impact on testing. In other words, it’s usually easier to test a process managed by a single service because tests can be limited to that one service.

To minimize deployment-related risks, consider using practices such as blue-green deployment, canary release, or feature flags.

Ultimately, if the system needs to be tested as a whole, perhaps microservices aren’t the best choice; maybe a monolith and monorepo will work better.

Message for Today

Don’t get stuck in mental monolith thinking. A monolith isn’t just an architecture; it’s also a way of thinking about a problem.

There’s no sense in being precise when you don’t even know what you’re talking about.

– John van Neumann

In my professional life, I’ve encountered guidelines stating that “every system must have documentation” many times. Typically, based on such formulated requirements, someone from the team would prepare a document called documentation. Often, it was a forced document that didn’t change anything in terms of the system’s usability and didn’t make anything easier.

In this post, I’d like to present my three-point approach to tasks and problems related to documentation.

Firstly, determine what problem the documentation is supposed to solve

The IT community often perceives documentation creation as a necessary requirement that few people want to fulfill. The most important task of documentation, i.e., achieving a goal or solving a problem, is not recognized. Without considering the goal, we prepare a document that is supposed to address all issues of all stakeholders, if it addresses any at all.

Let’s consider some example goals and problems that documentation is supposed to address:

1. The system architecture is complex and difficult to explain.
2. Onboarding time for project employees is long, and we want to shorten it.
3. The Ops team is struggling with deploying software prepared by developers.
4. Other teams complain about integration with our library.

Documentation can potentially be a solution to all these problems. However, let’s take a closer look at them, leading us to the second point.

Secondly, consider whether the problem can be solved differently than through documentation

Creating documentation often seems like a remedy for a variety of problems, but it might be worth finding and eliminating their source instead of applying a plaster in the form of an additional document.

If the architecture is complex (problem 1), instead of writing extensive documentation explaining all intricacies, it’s better to spend time simplifying the architecture to make it more understandable.

If onboarding time for employees is long (problem 2), it’s worth considering why. Is it due to poor code quality, non-compliance with standards, lack of code modularity? All these cases can be addressed differently than with documentation, while simplifying the lives of all code users.

If deploying the system by the Ops team is a challenge (problem 3), instead of preparing deployment specifications, DevOps practices can be applied. Instead of introducing exotic deployment methods, the company may have a standard that can be applied. You can consider to apply ‘you build it, you run it’ approach.

If library usage is the problem (problem 4), it’s worth working on the API. First and foremost, check if the library has a clearly defined API, if it’s easy to use, and if methods and types are unambiguous.

Thirdly, choose the appropriate form of documentation

I wouldn’t want to be misunderstood; I’m not against the written word. Often, creating documentation is the best way to address many problems. However, it’s worth considering its form. For describing a framework that other teams will integrate with, a tutorial might be best, while a tutorial won’t work for describing that framework for developers who are developing it. Architectural Decision Records (ADRs) can be used to describe architectural decisions. Different cases require different forms of documentation. Sometimes we’ll need many different forms in a single system.

The same goes for diagrams. If a diagram isn’t understandable without someone describing it, it probably presents too many concepts at once and should be split into several simpler ones.

Message for Today

If someone asks you to prepare documentation, before you do anything, ask what problem we are solving and solve it in the right way.

I consider tools for static code analysis extremely useful. It’s worth using them, even if they sometimes make life a bit harder. Ultimately, with their help, the code of the application is better. I’ve also noticed that many people are more receptive to feedback on code formatting from a machine than from another person, and any potential annoyance is directed towards the computer.

Custom Rules

It turns out that it’s quite easy to add custom rules to Checkstyle. By this, I mean writing your own check and using it in your own project. Adding a check to the main library is a completely different story. It can take years from submitting the idea and presenting the Proof of concept (PoC) to the merge!

Checkstyle in My Project

In the project I’m working on, it often happened (several times a month) that the rule for formatting method parameters was violated – whether parameters were in one line or each in a separate line. The code looked something like this:

public int fun(int a, int b,
    int c) {
...    
}

After a few times, when I mentioned this during code reviews, I decided to set the appropriate rule in Checkstyle. Unfortunately, it turned out that there was no such rule. From searching the internet, through GitHub issues, I came to my own library.

Custom Library with Rules

The library currently contains four checks related to method and constructor parameters both in their declaration and when called. Using it is simple, just add the library as a dependency to the plugin. Below is an example for Gradle Kotlin DSL:

plugins {
    java
    checkstyle
}

dependencies {
    checkstyle("pl.tfij:check-tfij-style:1.2.1")
}

Then add the checks to the Checkstyle configuration:

<module name="MethodParameterAlignment"/>
<module name="MethodParameterLines"/>
<module name="MethodCallParameterAlignment"/>
<module name="MethodCallParameterLines">
    <property name="ignoreMethods" value="Map.of"/>
</module>

Formatting errors, such as those mentioned above, are caught during the project build stage, and I no longer have to mention them during code reviews.

More details on GitHub: https://github.com/tfij/check-tfij-style

Message for Today

Use static code analysis. I also hope that the checks from my library will be useful to you.

Most papers in computer science describe how their author learned what someone else already knew.

– Peter Landin

This post is a brief story of how good intentions can lead to disaster when forgetting about JVM’s internal mechanisms and how, once again, Kent Beck’s approach - “Make it work, Make it right, Make it fast” - came into play.

Ugly Code to Refactor

Recently, I stumbled upon a rather unreadable piece of code. Below, I present its essence:

private Map<String, Map<String, Set<String>>> map = new HashMap<>();

void put(String a, String b, String c) {
    map.putIfAbsent(a, new HashMap<>());
    map.get(a).putIfAbsent(b, new HashSet<>());
    map.get(a).get(b).add(c);
}
    
boolean contains(String a, String b, String c) {
    return map.getOrDefault(a, new HashMap<>())
        .getOrDefault(b, new HashSet<>())
        .contains(c);
}

Of course, in the original code, methods weren’t as separated, the class had a few hundred lines, and everything was much more tangled. After several refactoring steps, I replaced Map<String, Map<String, Set<String>>> with Set<Key>, resulting in something like:

private Set<Key> set = new HashSet();

void put(String a, String b, String c) {
    set.add(new Key(a, b, c));
}

boolean contains(String a, String b, String c) {
    return set.contains(new Key(a, b, c));
}

record Key(String a, String b, String c) { }

I name variables in the example as a, b, c, etc., to avoid introducing domain intricacies.

Satisfied with the results, I deployed the change. After a few minutes, I checked the service metrics, and there was a huge spike in memory usage. Luckily, the deployment wasn’t on the production environment.

What Went Wrong?

It turned out that the new data structure consumed several times more memory. But that’s not all - it’s not a small collection; it stores millions of elements. The collection in the original version weighed around 400MB, while in the “improved” one, it was about 1100MB.

The increase in memory usage in this case stems from the mechanism of creating and storing Strings in the JVM. Java has several optimizations on strings. In particular, string literals go into the string pool in memory and can be reused multiple times, e.g.,

String x = "Lorem ipsum";
String y = "Lorem " + "ipsum";
System.out.println(x.equals(y)); // prints true
System.out.println(x == y);      // prints true

This isn’t true for strings that aren’t literals, e.g.,

int i = 0;
String x = "Lorem ipsum" + i;
String y = "Lorem ipsum" + i/2;
System.out.println(x.equals(y));  // prints true
System.out.println(x == y);       // prints false

One can force adding a string to the string pool using the intern() method, but this solution has its nuances and, in my opinion, can lead to errors. This solution may also result in other memory issues.

The described behavior of strings makes the implementation with Map significantly more memory efficient in my case. The map holds a reference, which provides noticeable gains when there are many entries with the same key. Additionally, in the described case, the strings were quite long - consisting of several dozen characters.

Deeper Problem Analysis

To better understand what’s happening in the JVM, consider the following example:

map.computeIfAbsent(new String("a"), x -> new HashSet<>()).put(new String("b1"));
map.computeIfAbsent(new String("a"), x -> new HashSet<>()).put(new String("b2"));

After executing the first line of code, the following strings will be created:

• “a” – a literal that can be cleaned up by GC
• “b1”– a literal that can be cleaned up by GC
• new String("a") – as a key, the map holds a reference to this object
• new String("b1") – value in the set – the set holds a reference to this object, and the map holds a reference to the set.

After executing the second line of code, the following strings will be created:

• “a” – a literal that can be cleaned up by GC
• “b2” – a literal that can be cleaned up by GC
• new String("a") – may be cleaned up by GC because equals will be called on the string when adding to the map, and such a key already exists
• new String("b2") – value in the set – the set holds a reference to this object, and the map holds a reference to the set.

As a result, we keep only three strings in memory - no duplicates.

For a change, let’s consider a version with a set and an aggregating object:

set.add(new Key(new String("a"), new String("b1")));
set.add(new Key(new String("a"), new String("b2")));

After executing the first line, the following strings will be created:

• “a” – a literal that can be cleaned up by GC
• “b1” – a literal that can be cleaned up by GC
• new String("a") – value in the Key object – Key holds a reference to this object, and the set holds references to Key
• new String("b1") – value in the Key object – Key holds a reference to this object, and the set holds references to Key

After executing the second line, the following strings will be created:

• “a” – a literal that can be cleaned up by GC
• “b2” – a literal that can be cleaned up by GC
• new String("a") – value in the Key object – Key holds a reference to this object, and the set holds references to Key
• new String("b2") – value in the Key object – Key holds a reference to this object, and the set holds references to Key

As a result, we keep four strings in memory that cannot be deleted by GC – the new String("a") instance is stored twice.

How I Solved the Problem

For performance reasons, I decided to stick with the map of map. However, I encapsulated the whole ugliness of a set in a map within a map into a separate class:

static class MultiDeepMap<K1, K2, V> {

    private Map<K1, Map<K2, Set<V>>> map = new HashMap<>();

    void put(K1 key1, K2 key2, V value) {
        map.computeIfAbsent(key1, it -> new HashMap<>())
                .computeIfAbsent(key2, it -> new HashSet<>())
                .add(value);
    }

   boolean contains(String key1, String key2, String value) {
        return map.getOrDefault(key1, new HashMap<>())
                .getOrDefault(key2, new HashSet<>())
                .contains(value);
    }
}

With such an API, we have a clear way of adding and checking if something has been added to the map:

map.put("a", "b", "c");
map.contains("a", "b", "c");

To increase code readability, you can get rid of the habit of typing everything as a string, the jargon known as String Typing, by wrapping strings in classes/records and replacing:

MultiDeepMap<String, String, String>

with:

MultiDeepMap<A, B, C>

In my case, this resulted in a roughly 10% increase in memory usage for this collection. All measurements were performed on Open JDK 17.0.1.

Message for Today

It’s not enough to know the internal mechanisms of the JVM. You also need to remember them at the right time, especially during the daily maintenance of the code.

Global state is evil until proven otherwise.

– Martin Fowler

On this blog, I sometimes touch upon taboo subjects like in post Optional as a Field and what are you going to do to me about it?. This time, it’s about static public variables. Much has already been said about the harm their usage has inflicted on the world. In this post, I’d like to analyze a specific case of their usage, namely metrics.

Metrics, Metrics Everywhere

In the Mierz logi na zamiary (bite off more than you can measure) post by Bartek Gałek, he described how important metrics are. Collecting metrics is also very straightforward. In the Spring framework, all you need to do is inject MeterRegistry…

Well, yes, just inject MeterRegistry. But does everything in my code have to be a Bean just to collect metrics? If I want to collect metrics in a POJO, do I have to create a factory that will be a Bean and set the MeterRegistry in the POJO instance?

Of course NOT! After all, if you want to log something, you don’t inject a logger (at least I haven’t encountered that). Instead, you use a static instance and log whatever and wherever you want. I assume that logs and metrics are not that distant from each other. So let’s try to apply a similar approach to metrics.

Global Variables Come to the Rescue

In the simplest approach, we could just create a class with a public static field holding an instance of MeterRegistry. We would initialize this field at the start of the application and then use it freely. Below is a slightly more elaborate implementation, where the mutator has package visibility and the accessor is public.

public class MeterRegistryHolder {
    private static MeterRegistry aMeterRegistry;
    
        static void init(MeterRegistry meterRegistry) {
            aMeterRegistry = meterRegistry;
        }
    
        public static MeterRegistry meterRegistry() {
            return aMeterRegistry;
        }
    }

@Configuration
public class MeterRegistryHolderInitializer {
    MeterRegistryHolderInitializer(MeterRegistry meterRegistry) {
        MeterRegistryHolder.init(meterRegistry);
    }
}

This implementation is very simple yet provides immense flexibility for adding metrics in the code.

If you need several instances of MeterRegistry because, for example, you send metrics to different places, you can extend the MeterRegistryHolder class to hold multiple instances.

For convenience, you can add a static import for MeterRegistryHolder.meterRegistry. The code will remain largely unchanged. Instead of meterRegistry.counter(), it will be meterRegistry().counter().

You can also use the Metrics class from Micrometer. It has a much more extensive API through which, although we don’t have access to the MetricRegistry object, we have a range of methods for generating metric instances associated with the global MetricRegistry.

Limitations

Global variables are not without reason infamous. Below are two limitations of the discussed approach to keep in mind.

If you need to test metrics, you can achieve this by setting Spy/Mock in MeterRegistryHolder or initialize it by SimpleMeterRegistry. However, note that in this case, metric tests should not be run concurrently.

Also, note that in this implementation, we do not control the order in which beans are initialized and when MeterRegistryHolder will be initialized. Therefore, if you try to collect metrics during application context initialization, the meterRegistry reference may be empty. In such a situation, you can either expand the MeterRegistryHolder (I have prepared a sample implementation on GitHub) or resort to the old proven injection. A simple implementation of MeterRegistryHolder can be used for everything that happens after the context is initialized.

I’m not assuming that this approach will work in all cases. In my recent projects, it worked great, providing a lot of freedom for adding metrics.

Message for Today

Give global variables a chance (especially when you limit their variability to the package scope).

It ain’t what you don’t know that gets you into trouble. It’s what you know for sure that just ain’t so.

– Will Rogers

The Basics Senior Developers Might Not Know

We all know how crucial good naming conventions for variables, functions, classes, and everything we work with are. One of the popular techniques of refactoring is renaming. Programmers spend a considerable amount of time brainstorming names. Therefore, one would expect every name to make sense and be correct, and when it’s not, we should be able to change it.

Unfortunately, life is cruel! Even in the Java standard library, there’s a stench. Let’s take a look at the LocalDateTime class. What is this class? The name suggests that it holds a local date. That’s the kind of response I hear in job interviews (if someone remembers what the java.time API is).

Local Only in Name

Let’s conduct a little experiment then. I have my computer set to the Polish time zone, which means the following assertion is correct.

assert ZoneId.systemDefault().equals(ZoneId.of("Europe/Warsaw"));

If LocalDateTime stores the date in the local time zone, to get the current date in another time zone, I should be able to execute the code:

ZonedDateTime now = LocalDateTime.now().atZone(ZoneId.of("UTC")));

and the following assertion should pass:

assert now.equals(ZonedDateTime.now(Clock.system(ZoneId.of("UTC"))));

However, the assertion fails. This is because LocalDateTime has little to do with locality Moreover, the same issue applies to LocalDate. If you see the expression

ZonedDateTime now = LocalDateTime.now().atZone(ZoneId.of("UTC")));

chances are high that it’s a bug. I’ve fixed such bugs several times already. They are not easy to detect, especially if creating instances of LocalDateTime and converting to ZonedDateTime are far apart, for example, in different files.

In fact, the atZone method of the LocalDateTime class only makes sense when we know the context of creating the instances – we know in which time zone the LocalDateTime instance was created.

So, what’s happening in LocalDateTime.now().atZone(ZoneId.of("UTC")))? The LocalDateTime.now() method returns the current system date and then a given time zone is added to it. In our case, it’s UTC. As it turns out, this has nothing to do with “now”. The result is “now” shifted by the time zone differences between the system time zone and UTC.

This behavior shouldn’t surprise those who read the documentation.

A date-time without a time-zone in the ISO-8601 calendar system, such as 2007-12-03T10:15:30.

But why bother reading the documentation when the name explains everything? The clue lies in the motto above. As Will Rogers said, It ain’t what you don’t know that gets you into trouble. It’s what you know for sure that just ain’t so.

Dear reader, I still owe you a correct code example. Understanding how LocalDateTime works, the expression

ZonedDateTime now = LocalDateTime.now().atZone(ZoneId.of("UTC"));

should be replaced with

ZonedDateTime now = ZonedDateTime.now(ZoneId.of("UTC"));

How to Proceed?

We now know that LocalDateTime is a misleading, weak name. So, how to proceed?

Perhaps a better name would be ZonelessDateTime, analogous to ZonedDateTime? Alternatively, something like NoZoneDateTime or NotZonedDateTime. This name has one drawback. Generally, a class name should indicate what the object is responsible for, not what it is not. So maybe just DateTime?

If you can come up with a better name (or one of my suggestions fits you), and you’re using Kotlin, you can use type aliases:

typealias ZonelessDateTime = LocalDateTime

I almost forgot, if you can think of a better name, be sure to write to me.

Message for Today

Finally, my favorite solution: don’t use LocalDateTime if possible.