Testing in the Trenches (TinT) is an occasional series based on my experiences promoting and coaching Unit Testing on real projects, ones where the team or management do not always embrace the philosophy or practices of Unit-Testing.
But imagine that you are working in a code base with pockets, sections, even whole packages of code that has no tests, possibly even code whose design is hostile to being put into a test harness.
Imagine that the enhancement or bug fix on your plate involves changing existing code that has no current test coverage, or not very much, or maybe some tests but they are poor quality. Maybe they have a lot of dependencies, or it takes a lot of work to set them up, or they do too many things on construction.
This imaginary scenario is very common on some projects.
Faced with such a scenario, as practitioners of the craft of unit-testing, we want to at the very least provide tests that cover our new code. We want to ensure that, when we add code for an enhancement or bug fix, our contribution is unit-tested.
One effective technique is to separate our new code into a new class. Like a TV show that spins-off from another one, we want to spin-off our new work into a new class, one that the original class will call for our new fix or feature. The idea is to put your changes into the new class and use it from the original class.
This testing technique has some immediate Advantages:
1. it lets us clearly separate our new code from the old code;
2. it lets us define a clean, clear interface between the old class and the new one;
3. our new code becomes much easier to test;
4. it is a smaller, less invasive change to the existing class than stuffing all our changes into it.
It is a technique that is not without controversy, of course. Some Disadvantages:
1. while it does less violence to the old class, it potentially does violence to the overall design - if there was a coherent story to the design before, it may now have become a little more muddled;
2. moving new functions into new classes and away from the existing abstractions can increase local and overall system complexity;
3. it leaves the issue of the existing untested code and its challenges for another day, punting that concern into the future.
Here is a real-world (redacted) example. On one project some years ago, a feature of our product allowed users to save the output of a process to a file. The existing business rule was that, for security reasons, the file would be created in a specific, hard-coded location. Then the requirement changed: they would be able to write the file to different locations, but any possible locations would be restricted to paths under a given root folder, which would be defined in another part of the application by a user with Administrator privileges.
(1) The first step in this Spin-off Class technique is to identify where in the original code the changes need to be made.
In the case of my enhancement, I found the place where the output-generator accessed the original, hard-coded output location. It would need to change, to get the location in a different way. I also found the bigger and more interesting change: the UI screen from which the action is triggered. It would need a way to identify the user's preferred output location. Something needed to change here as well - a button that opened a JFileChooser dialog, and some ability to process its results.
(2) The second step is to think through the detailed design of the new class and its fields and methods that will perform the new work.
In my case, I was adding a Browse button for the users to browse to their destination folder. The team culture was to build Action Handlers as private internal classes within the form or screen on which it appeared. But with an eye toward both testability and reusability, I wanted to pull this new function out into a separate public class.
It needed a good name, something like BrowseActionWithFixedRootFolder - a bit long and awkward, but seemed to communicate its purpose. It needed to live in an appropriate package, so I chose the com.appname.file package since it would deal with folder selections.
Since it would sub-class an Action class, some of its API, such as actionPerformed() was easy to design. But I needed to design how the selected file folder would be communicated back from the JFileChooser, through this new class, and back to the calling class.
Since I was designing this new class to be reusable, I needed to design a way to tell the action what to do with a file or folder once one was selected. Inspiration came, in my case, from existing design patterns.
Since I wanted this action class to be reusable in other contexts, I needed to design how it will know what was the fixed root, the starting point of the folder structure. These and a handful of other considerations shaped the fields and the method parameters of the new class.
(3) The third step is to implement the detailed design of the new class.
With a well-thought-out design, this step was straight-forward. I could create my Action class and write the unit-tests to cover this new functionality.
(4) The final step is to change the original class to call your new class.
The original class remained as hard as ever to test, and in this project I attempted no refactoring to get the original class into the test harness. In my case, I was adding a new button and this new Action class, so the impact on the original class was as minimal as possible. Some manual acceptance testing indicated that the UI worked as expected. My suite of new unit tests validated the rest of the behavior of the Action and the class to which I delegated the responsibility to handle the selected folder which, in my requirements, meant validating that it was a sub-folder of the fixed root folder, and then communicating the selected path to the process that would produce the output file.
Making BrowseActionWithFixedRootFolder into a new class pushed me to better design, as the code is reusable and the methods are more accessible for tests. This then let me complete my enhancement, if not with 100% coverage, at least with a high degree of coverage, including the most substantive parts.
Technique: Spinning-off a New Class
Imagine you believe in the principles of automated unit testing. You want to write tests to prove the correctness of your code.But imagine that you are working in a code base with pockets, sections, even whole packages of code that has no tests, possibly even code whose design is hostile to being put into a test harness.
Imagine that the enhancement or bug fix on your plate involves changing existing code that has no current test coverage, or not very much, or maybe some tests but they are poor quality. Maybe they have a lot of dependencies, or it takes a lot of work to set them up, or they do too many things on construction.
This imaginary scenario is very common on some projects.
Faced with such a scenario, as practitioners of the craft of unit-testing, we want to at the very least provide tests that cover our new code. We want to ensure that, when we add code for an enhancement or bug fix, our contribution is unit-tested.
One effective technique is to separate our new code into a new class. Like a TV show that spins-off from another one, we want to spin-off our new work into a new class, one that the original class will call for our new fix or feature. The idea is to put your changes into the new class and use it from the original class.
This testing technique has some immediate Advantages:
1. it lets us clearly separate our new code from the old code;
2. it lets us define a clean, clear interface between the old class and the new one;
3. our new code becomes much easier to test;
4. it is a smaller, less invasive change to the existing class than stuffing all our changes into it.
It is a technique that is not without controversy, of course. Some Disadvantages:
1. while it does less violence to the old class, it potentially does violence to the overall design - if there was a coherent story to the design before, it may now have become a little more muddled;
2. moving new functions into new classes and away from the existing abstractions can increase local and overall system complexity;
3. it leaves the issue of the existing untested code and its challenges for another day, punting that concern into the future.
Here is a real-world (redacted) example. On one project some years ago, a feature of our product allowed users to save the output of a process to a file. The existing business rule was that, for security reasons, the file would be created in a specific, hard-coded location. Then the requirement changed: they would be able to write the file to different locations, but any possible locations would be restricted to paths under a given root folder, which would be defined in another part of the application by a user with Administrator privileges.
(1) The first step in this Spin-off Class technique is to identify where in the original code the changes need to be made.
In the case of my enhancement, I found the place where the output-generator accessed the original, hard-coded output location. It would need to change, to get the location in a different way. I also found the bigger and more interesting change: the UI screen from which the action is triggered. It would need a way to identify the user's preferred output location. Something needed to change here as well - a button that opened a JFileChooser dialog, and some ability to process its results.
(2) The second step is to think through the detailed design of the new class and its fields and methods that will perform the new work.
In my case, I was adding a Browse button for the users to browse to their destination folder. The team culture was to build Action Handlers as private internal classes within the form or screen on which it appeared. But with an eye toward both testability and reusability, I wanted to pull this new function out into a separate public class.
It needed a good name, something like BrowseActionWithFixedRootFolder - a bit long and awkward, but seemed to communicate its purpose. It needed to live in an appropriate package, so I chose the com.appname.file package since it would deal with folder selections.
Since it would sub-class an Action class, some of its API, such as actionPerformed() was easy to design. But I needed to design how the selected file folder would be communicated back from the JFileChooser, through this new class, and back to the calling class.
Since I was designing this new class to be reusable, I needed to design a way to tell the action what to do with a file or folder once one was selected. Inspiration came, in my case, from existing design patterns.
Since I wanted this action class to be reusable in other contexts, I needed to design how it will know what was the fixed root, the starting point of the folder structure. These and a handful of other considerations shaped the fields and the method parameters of the new class.
(3) The third step is to implement the detailed design of the new class.
With a well-thought-out design, this step was straight-forward. I could create my Action class and write the unit-tests to cover this new functionality.
(4) The final step is to change the original class to call your new class.
The original class remained as hard as ever to test, and in this project I attempted no refactoring to get the original class into the test harness. In my case, I was adding a new button and this new Action class, so the impact on the original class was as minimal as possible. Some manual acceptance testing indicated that the UI worked as expected. My suite of new unit tests validated the rest of the behavior of the Action and the class to which I delegated the responsibility to handle the selected folder which, in my requirements, meant validating that it was a sub-folder of the fixed root folder, and then communicating the selected path to the process that would produce the output file.
Making BrowseActionWithFixedRootFolder into a new class pushed me to better design, as the code is reusable and the methods are more accessible for tests. This then let me complete my enhancement, if not with 100% coverage, at least with a high degree of coverage, including the most substantive parts.