Given When Then – short intro

Have You ever heard about Given-When-Then approach to create tests? It’s an approach to separate tests structure into three parts:

• Given – Test preparation. We should ask ourselves a few questions here (depending on approach):
  • What I need to execute before tested operation?
  • Do I need some specific beans?
  • Do I need to mock something?
  • Do I need some particular data?
• When – this is our operation under test.
• Then – this are our expectations. Basically – test assertions.

Of course not every code can have such structure, but as an ideal approach it can increase overall readability of our source code.

Example:

This test checks if newly created issue will invoke some sort of notification. We can read this test like this:

• With given title  and description
• When I create new issue
• Then one notification has been published.

Of course sometimes, some parts can not be that obvious. Take a look:

Now you can see that given part is hidden. But it’s still there!

There are a lot of good articles about this topic. Some of them:

• AgileAlliance: Given When Then
• Martin Fowler: Given When Then
• Alex Collins: Given When Then in JUnit

Validation – Operation – Notification approach

I would like to propose similar approach, but for production source code. Let’s call it VON (Validation – Operation – Notification).

• Validation – all prerequisites which need to be checked or done before you can do particular command. Such as validations, security check rules etc.
• Operation – our business command. The heart of the method. We start writing our method because of this. This is our main purpose.
• Notification – what happens after successful operation. Often it will be just some return statement, but it could be more. It’s a part of business method that did not exist to do primary operation, but invoke some other command (which very often can be done asynchronously. For example using CompletableFuture).

Let’s see a basic example:

Now, look at this method using 3 steps defined above:

• Validate – if title and description is not null,
• Create issue (our operation),
• Notify about newly created issue and return it.

Of course sometimes it will not be such straightforward. Above method in real world can look more like this (using lombok):

Still – you can see all 3 parts of VON approach.

Error handling

Depending on step, we should think about errors and problems differently. Lets try to check possible scenarios when we use VON code structure.

Imagine that something happen on validation step – the only thing you have to do is to throw an exception, return specific error message or maybe send error information to some notification queue… You didn’t start any operation- so you have no problem (within this method).

When something happen during operation part- then you have a problem. If your validation was well prepared then any error within this step will be related to technical or network issues (database downtime, no network connection, etc.).

Finally when something happen during notification phase then you should know two things- operation went well, so main purpose of this method was finished without problems. The only problem you have now is that some notification was not published. Question is what can you do about this? Maybe you should not do anything, maybe you should send information to technical error queue that some message was not sent. Maybe just log this situation? It depends.

As you can see separating your method to VON structure helps you identifying error type that can occurred. It’s one of the advantages of this approach.

To “Enter” or not to “Enter”

As you can see in above examples “enter key” change step in VON approach. In general “new line” in source code should inform us about context change. This principle goes well with whole VON approach as every step is different context. We can look at source code and with a single glance focus on most important part for us at the moment. If every team member use the same approach, then source code starts to look more clear and well structured. The faster you can focus on important things, the faster you can solve the problem you are currently working on.

Of course this doesn’t mean that we should create long methods 🙂 Ideally our methods will have 2-3 lines- each line for single step. Then we can omit all enters.

Lets start some cleaning!

Refactor to VON – example

Imagine a method that delete contract from some old system. Contract can be deleted when it’s not started and any of its conditions are not started yet as well (for example, there can be specific condition which will limit that resignation from contract can be made two or more months before contract is started). Delete operation is made using SoftDelete (BTW. I hate soft delete). Of course before we start making any changes we should have proper unit tests!

Our example:

First let’s try to find our steps:

• validation 
  • our contract and any of its conditions can not be started- this is in the code
  • we don’t have validation that contractId  is null …
  • we don’t have validation that particular contract exists in repository..
• operation
  • delete all contract conditions
  • set contract as non active (soft-delete)
  • save in repository
• notifications
  • cancel payment disposition for deleted payment

I would start with preparing above steps. Problematic part is that deleteAllContractConditionsByContract method is at the same time in validation and in operation phase. Let’s split it to two methods (for now).

As we don’t want to change too much outside this method let’s just extract both assertions to particular methods:

Much better 😉 Now lets fill the gap with our validations:

Ok. We should hide this whole optional stuff:

Now some small refactoring with operation part:

Now we need to take a look at the notification part. There are two things possible:

1. Add a new method to paymentsService  which will cancel payment disposition. Simple and safe operation, however we will still have direct relation between contracts and payments.
2. Add some queue in the middle between payments and contracts modules/components. We can use queue or just simple implementation of Producer/Consumer pattern. It’s a bit more complicated, but this gives us a more loose connection between the modules.

And basically we can stop now as this finish whole VON approach. Using this approach we did find 2 possible problems with particular method, however- now probably we have redundant checks – in our method we must assert that all contract conditions can be remover, and probably within contractConditionsService  the same check will be made.

Despite this, its look like a good start to further source code refactoring. Finally we can finish with something like this:

Summary

This technique nicely apply mostly to more complicated business methods and for legacy code refactor. Its biggest advantage is shown when every team member use this technique for all business operations. Then these methods starts to look consistent and much more straightforward. Also it helps to look at different parts of method differently (for example in case of potential errors that could happen).

Please note that this approach should not be used at every cost. It’s a convention that nicely applies to legacy code methods as in our example, but also to shiny newly created operations.

Have fun and comment below what you think about this approach!