Test Architects Hub

Recently, I had an opportunity to visualize the continuous testing process and explain it in simple terms (possibly, without using too many words). It was challenging, first of all, because I was uncertain who would eventually see my drawing, and whether they would have enough context to comprehend it clearly. I somehow managed to accomplish it. However, this experience raised some thoughts:

• Did I capture the complete picture? Did I provide sufficient details for different stages of the process?
• If and when something changes, how can I keep this visualization up to date?
• What if I need to do this again? Can I make it simplify or expedite the process?

Research #1 – What do others do?

With these thoughts in mind, I researched how others document their test automation, test infrastructure and the overall continuous testing process. After examining more than 10 different schemes and drawings, the results were… very different.

People worldwide attempt to explain their testing with custom-made diagrams, using different blocks and arrows and often place everything they have on one page. That does not necessarily make it easier to understand. Such drawings often suffer from the presence of different abstraction levels on the same sheet, the absence of consistency and common notation, and so on.

For example:

Essentially, every mess that I’ve done with my custom-made diagrams so far seems to be common among others as well. It’s not necessarily a very bad thing; rather it highlights the absence of a standardized way of documenting test architecture and the continuous testing process. This makes understanding a depicted subject more complicated and needs to be addressed and hopefully resolved.

Research #2 – What should I do?

So, having this challenge in front of me, I started another research of possible tools that could solve it for me. The most evident starting option was to investigate UML drawing tools for software architecture diagrams.

However, that didn’t lead to any significant findings, as my vision of a potential solution differed (UML diagrams are unwieldy, aren’t they?). Ultimately, I became desperate and was even considering starting my own pet project for a drawing tool to fill the gap.

But then I recalled the Software Architecture for Developers workshop that I had the opportunity to attend last year. The coach, Simon Brown, among other cool things introduced his C4 model for documenting software architecture. And I thought “Why not attempt to apply it to test architecture? It could work”.

C4 model

In a nutshell, the C4 model entails a set of hierarchical diagrams: system context, containers, components and code. Each of these diagrams represents a different level of abstraction (or detail, if you prefer), going from an overview of the whole system to more and more information about each element.

I believe Simon made an excellent analogy for understanding the C4 model by comparing it to Google Maps:

First, you look at the big picture, such as a continent or a section of the world (system context). Then, if you require more details, you can zoom in to view a particular country (container). Further, if you need even more granularity, you can zoom in and focus on a specific city (component). And, eventually, if necessary, you can switch to Street View and can observe the tiniest details (code).

The good thing for me is that it’s not necessary to create diagrams for all four levels of the C4 model every time. For instance, some teams/companies may only need system context and container diagrams, and that level of detail would suffice for their needs. It’s cool because, unlike intricate software systems, the testing process and test architecture are typically less complex and do not demand that level of detail.

Merging the C4 model and my thoughts

The above-mentioned seemed very promising to me, to be honest. I wanted to attempt visualising test architectures in the following way:

• First, it would be good to have a high-level diagram that depicts the key participants in the continuous testing process. For example, the test automation framework, the CI system, the application-under-test, reporting dashboards, etc.
• Next, for someone interested in exploring the test automation framework architecture in more depth, they should be able to “zoom in” and see more details about it. Like what are the architecture layers of the framework, the utils and helpers used, the flow of test data, how a framework interacts with external systems, etc.
  • Or if someone wants to delve into the details of testing on the CI system, they should be able to “zoom in” as well. For example, to see what kind of tests are executed for the application-under-test on different environments or branches.
  • And so on, for every participant involved in the continuous testing process.
• Suppose there’s a need to delve even deeper into the implementation of each automation framework layer. In that case, it should be possible to “zoom in” and examine its code as well (a little spoiler, it’s doable with the C4 model too but with some limitations).

The following figure demonstrates how such zooming applies to the software architecture depicted using the C4 model:

The challenge and (hopefully) the future solution

Although it may have appeared optimistic in the previous chapter, the tricky part was that no one had previously applied the C4 model for describing test matters. At least, I could not find any examples or attempts in this regard. Therefore, I would have to improvise and employ trial-and-error methods.

But even if I draw everything, how can I make it an enduring and relevant document just as I wanted?

I’ve been contemplating the concept of documentation-as-code for some time now. I have even made attempts to write test docs in Markdown files, pushing them to a remote repository and following the review process. But the Markdown format is of no help when it comes to creating block schemes and diagrams. Drawing diagrams elsewhere and then copypasting them is not much better than just doing everything on Confluence or any other similar platform.

It would be extremely valuable to have test architecture diagrams as code, wouldn’t it?

Fortunately, in addition to the C4 model, Simon also invented Structurizr, an open-source set of tools designed to support the C4 model. Structurizr utilizes the textual Domain Specific Language (DSL) that allows describing software architecture as text, which can then be rendered into visually appealing and interactive diagrams. 

Why can’t Structurizr serve my goal of documenting test architecture as code? I think it should be capable of doing that, and that’s precisely what I’m going to try in the next article!

---

P.S. This post is part of a series where I’ll delve into polishing the documentation aspect of test architects’ lives. I already anticipate a couple more articles focusing on the C4 model and Stricturizr, and then we’ll move on to what is the next logical topic in this series.