This episode of Testing in the Trenches describes, with appropriate modifications to protect the parties involved, a situation I encountered on a client's project that challenged our efforts to create a suite of automated unit tests and what we did about it. It is adapted from one of the internal Tips that I regularly sent to the team.
One of the key goals in unit testing is that we can run the suites of tests quickly. When the tests run in just a handful of seconds, we get fast feedback when issues arise. It is easier and safer to resolve those issues when the developer's mind is still on the problem they were working on.
And tests that run quickly are less of a perceived interruption to the work of a test-averse developer. This increases the odds that the developer will adopt the practice of running the test suite before committing their code.
But a run of tests comes to a complete halt when user interaction is required. For example, a path through the code that creates a pop-up message box brings the test run to a halt. None of the tests can proceed until they receive user input.
How can we write our unit tests to be independent of user interaction? It is tough when we want to test code that looks like this:
if ( myFile.getPath().length() > uiFields.getField(downLoadFileFN).getMaxWidth() )
{
JOptionPane.showMessageDialog(getFrameInFocus(),
"The selected path exceeds the width of the entry field.\n"
+ "Please select a different path."
"Error",
JOptionPane.ERROR_MESSAGE);
doSomethingHere();
}
It may be an important condition in our logic, one that really needs to be covered by one or more unit tests. But as soon as a test fulfills the if-condition, a warning box pops up and everything pauses until it is dismissed. That is, of course, the behavior we want in production, but it is not helpful in automated testing.
There are at least a couple things we can do when faced with code that halts for a pop-up warning message or error. Both involve making a small change to the production code, to make it possible to get the tests in place. But in both cases, the small change improves our design in a small way, and both are also reasonably safe.
Option 1 – Extract Method Locally and Override in Test
If the behavior of alerting the user with a pop-up is a truly exceptional situation, one that happens very rarely in the code, it might be enough to handle it locally. In this case, extract the JOptionPane call out to a new method on the class, such as:
protected void showErrorMessage(String message, String title)
{
JOptionPane.showMessageDialog(getFrameInFocus(),
message, title,
JOptionPane.ERROR_MESSAGE);
}
And then change the original code to call this method (Tip: use the refactoring tools built into your IDE to do this extraction faster and more safely).
if ( myFile.getPath().length() > uiFields.getField(downLoadFileFN).getMaxWidth() )
{
showErrorMessage("The selected path exceeds the width of the entry field.\n"
+ "Please select a different path.", "Error");
doSomethingHere();
}
Then the test class uses a private inner class that overrides the protected message and skips the user-interaction.
@Override
protected void showErrorMessage(String message, String title)
{
// skip UI in Unit Tests
}
This approach is not to everyone's taste. It has some design flaws, which we can dig into another day. But it does let us move ahead with writing unit tests that are not interrupted by user interactions, and I think it makes a tiny improvement in our design.
Option 2 – Wrap the Call in Another Class
In the original production code, our class knows and uses the gory details of how to make a pop-up message appear, in this case using JOptionPane. But if we pull that code out into another class, our validation check will no longer need to know if we are using a GUI, a web interface, a shell interface, or some futuristic 3D tactile gizmo.
Then, if we switch from Java Swing to JavaFX or any other UI system for our error messages, this piece of code will not be affected, only the new class we are about to create.
Let's start it something like this:
public class UIMessagesManager
{
public void showErrorMessage(String message, String title)
{
JOptionPane.showMessageDialog(getFrameInFocus(),
message, title,
JOptionPane.ERROR_MESSAGE);
}
}
UIMessagesManager now has the showErrorMessage() method, for starters. It can grow over time to have utility methods that handle most different types of messates we would want to communicate to the user: an error, message or information.
Even better, the UIMessagesManager can be expanded to know whether to show a GUI, display a console string, craft a web-page response, etc. It is a much more appropriate place than our original code to handle the different UI modalities.
We can also expand it to build in some special processing for when unit tests are running. "Unit-Test UI" is conceptually another UI variation like "GUI" or "Console" except that it would suppress the UI display so that no message box appears.
In fact, let's turn it into an interface, and implement the interface with our production GUI code on the one hand, and our unit-test non-UI code on the other hand. Something like this:
public interface UIMessagesManagerIF
{
public void showErrorMessage(String message, String title);
}
Then our production code becomes:
public class UIMessagesManager implements UIMessagesManagerIF
{
@Override
public void showErrorMessage(String message, String title)
{
JOptionPane.showMessageDialog(getFrameInFocus(),
message, title,
JOptionPane.ERROR_MESSAGE);
}
}
And we can make a Unit Test UI Manager something like this:
public class FakeUIMessagesManager implements UIMessagesManagerIF
{
private List<String> messages = new ArrayList<String>();
@Override
public void showErrorMessage(String message, String title)
{
messages.add(message);
}
public void clearMessages()
{
messages.clear();
{
public List<String> getMessages()
{
return messages;
}
}
Our Fake class handles calls to show the user a message, and keeps the messages it was asked to display, which our tests can access later. And it provides a way to clear the log. These are outside the interface, and will be used by our unit tests for verification. Production code will know nothing about them.
Now let's write a jUnit test case for our validation check above. In a new jUnit class, we can add the following:
public class MyClassTestUT
{
FakeUIMessagesManager myUIMgr = new FakeUIMessagesManager();
@Before
public void setup()
{
injectMessageManager(myUIMgr);
}
@After
public void teardown()
{
FakeUIMessagesManager.clearMessages();
}
@Test
public void validationCheck_FilePathTooLong_ExpectedMessage()
{
My Class objToTest = new MyClass(); // create an object of the class to test.
objToTest.isValidInput(); // call the validation check method
String expectedErr = "The selected path exceeds the width of the entry field.\n"
+ "Please select a different path."
assertEquals(expectedErr, myUIMgr.getMessages().get(0));
}
}
Even as I write this, I can think of improvements to the design of this new unit testing infrastructure, and the design of our production code.
But even this small change has real advantages. The code is now testable in an automated test suite; the production code has also become shorter, clearer, and at a higher level of abstraction, all of which make it easier to read, write and maintain; and it wraps a 3rd-party API so that, if ever we needed to switch from JOptionPane to something else, the change would happen in 1 class, not hundreds.
One of the key goals in unit testing is that we can run the suites of tests quickly. When the tests run in just a handful of seconds, we get fast feedback when issues arise. It is easier and safer to resolve those issues when the developer's mind is still on the problem they were working on.
And tests that run quickly are less of a perceived interruption to the work of a test-averse developer. This increases the odds that the developer will adopt the practice of running the test suite before committing their code.
But a run of tests comes to a complete halt when user interaction is required. For example, a path through the code that creates a pop-up message box brings the test run to a halt. None of the tests can proceed until they receive user input.
How can we write our unit tests to be independent of user interaction? It is tough when we want to test code that looks like this:
if ( myFile.getPath().length() > uiFields.getField(downLoadFileFN).getMaxWidth() )
{
JOptionPane.showMessageDialog(getFrameInFocus(),
"The selected path exceeds the width of the entry field.\n"
+ "Please select a different path."
"Error",
JOptionPane.ERROR_MESSAGE);
doSomethingHere();
}
It may be an important condition in our logic, one that really needs to be covered by one or more unit tests. But as soon as a test fulfills the if-condition, a warning box pops up and everything pauses until it is dismissed. That is, of course, the behavior we want in production, but it is not helpful in automated testing.
There are at least a couple things we can do when faced with code that halts for a pop-up warning message or error. Both involve making a small change to the production code, to make it possible to get the tests in place. But in both cases, the small change improves our design in a small way, and both are also reasonably safe.
Option 1 – Extract Method Locally and Override in Test
If the behavior of alerting the user with a pop-up is a truly exceptional situation, one that happens very rarely in the code, it might be enough to handle it locally. In this case, extract the JOptionPane call out to a new method on the class, such as:
protected void showErrorMessage(String message, String title)
{
JOptionPane.showMessageDialog(getFrameInFocus(),
message, title,
JOptionPane.ERROR_MESSAGE);
}
And then change the original code to call this method (Tip: use the refactoring tools built into your IDE to do this extraction faster and more safely).
if ( myFile.getPath().length() > uiFields.getField(downLoadFileFN).getMaxWidth() )
{
showErrorMessage("The selected path exceeds the width of the entry field.\n"
+ "Please select a different path.", "Error");
doSomethingHere();
}
Then the test class uses a private inner class that overrides the protected message and skips the user-interaction.
@Override
protected void showErrorMessage(String message, String title)
{
// skip UI in Unit Tests
}
This approach is not to everyone's taste. It has some design flaws, which we can dig into another day. But it does let us move ahead with writing unit tests that are not interrupted by user interactions, and I think it makes a tiny improvement in our design.
Option 2 – Wrap the Call in Another Class
In the original production code, our class knows and uses the gory details of how to make a pop-up message appear, in this case using JOptionPane. But if we pull that code out into another class, our validation check will no longer need to know if we are using a GUI, a web interface, a shell interface, or some futuristic 3D tactile gizmo.
Then, if we switch from Java Swing to JavaFX or any other UI system for our error messages, this piece of code will not be affected, only the new class we are about to create.
Let's start it something like this:
public class UIMessagesManager
{
public void showErrorMessage(String message, String title)
{
JOptionPane.showMessageDialog(getFrameInFocus(),
message, title,
JOptionPane.ERROR_MESSAGE);
}
}
UIMessagesManager now has the showErrorMessage() method, for starters. It can grow over time to have utility methods that handle most different types of messates we would want to communicate to the user: an error, message or information.
Even better, the UIMessagesManager can be expanded to know whether to show a GUI, display a console string, craft a web-page response, etc. It is a much more appropriate place than our original code to handle the different UI modalities.
We can also expand it to build in some special processing for when unit tests are running. "Unit-Test UI" is conceptually another UI variation like "GUI" or "Console" except that it would suppress the UI display so that no message box appears.
In fact, let's turn it into an interface, and implement the interface with our production GUI code on the one hand, and our unit-test non-UI code on the other hand. Something like this:
public interface UIMessagesManagerIF
{
public void showErrorMessage(String message, String title);
}
Then our production code becomes:
public class UIMessagesManager implements UIMessagesManagerIF
{
@Override
public void showErrorMessage(String message, String title)
{
JOptionPane.showMessageDialog(getFrameInFocus(),
message, title,
JOptionPane.ERROR_MESSAGE);
}
}
And we can make a Unit Test UI Manager something like this:
public class FakeUIMessagesManager implements UIMessagesManagerIF
{
private List<String> messages = new ArrayList<String>();
@Override
public void showErrorMessage(String message, String title)
{
messages.add(message);
}
public void clearMessages()
{
messages.clear();
{
public List<String> getMessages()
{
return messages;
}
}
Our Fake class handles calls to show the user a message, and keeps the messages it was asked to display, which our tests can access later. And it provides a way to clear the log. These are outside the interface, and will be used by our unit tests for verification. Production code will know nothing about them.
Now let's write a jUnit test case for our validation check above. In a new jUnit class, we can add the following:
public class MyClassTestUT
{
FakeUIMessagesManager myUIMgr = new FakeUIMessagesManager();
@Before
public void setup()
{
injectMessageManager(myUIMgr);
}
@After
public void teardown()
{
FakeUIMessagesManager.clearMessages();
}
@Test
public void validationCheck_FilePathTooLong_ExpectedMessage()
{
My Class objToTest = new MyClass(); // create an object of the class to test.
objToTest.isValidInput(); // call the validation check method
String expectedErr = "The selected path exceeds the width of the entry field.\n"
+ "Please select a different path."
assertEquals(expectedErr, myUIMgr.getMessages().get(0));
}
}
Even as I write this, I can think of improvements to the design of this new unit testing infrastructure, and the design of our production code.
But even this small change has real advantages. The code is now testable in an automated test suite; the production code has also become shorter, clearer, and at a higher level of abstraction, all of which make it easier to read, write and maintain; and it wraps a 3rd-party API so that, if ever we needed to switch from JOptionPane to something else, the change would happen in 1 class, not hundreds.