What is an Integration Test ?
Sometimes there is not a clear distinction on what is an integration test and what is a unit test.
My basic rule of thumb is that if
- a test uses the database
- a test uses the network
- a test uses an external system (e.g. a queue or a mail server)
- a test reads/writes files or performs other I/O
…then it is an integration test and not a unit test. I have seen several developers who talk about “tests” and either they mean both or just integration tests. Here is also a brief comparison between the two.
| Unit test | Integration test |
|---|
| Results depends only on Java code | Results also depends on external systems |
| Easy to write and verify | Setup of integration test might be complicated |
| A single class/unit is tested in isolation | One or more components are tested |
| All dependencies are mocked if needed | No mocking is used (or only unrelated components are mocked) |
| Test verifies only implementation of code | Test verifies implementation of individual components and their interconnection behaviour when they are used together |
| A unit test uses only JUnit/TestNG and a mocking framework | An integration test can use real containers and real DBs as well as special integration testings frameworks (e.g. Arquillian or DbUnit) |
| Mostly used by developers | Integration tests are also useful to QA, DevOps, Help Desk |
| A failed unit test is always a regression (if the business has not changed) | A failed integration test can also mean that the code is still correct but the environment has changed |
| Unit tests in an Enterprise application should last about 5 minutes | Integration tests in an Enterprise application can last for hours |
You should now know the difference between the two....well, I hope so =)
How to write an integration test
Writing an integration test is heavily dependent on your environment. The first thing that you should decide is the scope of your integration test. So, let's say we are building a huge RESERVATION SYSTEM, we could write integration tests for:
- Verifying correct integration of the RESERVATION SYSTEM with the printer (in a staging environment of course)
- Verifying correct integration of this RESERVATION SYSTEM with the mail server
- Verifying correct reading/writing of invoices from/to the DB
- Verifying the whole data flow of receiving an order, creating an invoice, saving it to the DB and mailing it to the client. This is an End-To-End integration test
Since some of the integration tests in the case of this RESERVATION SYSTEM, use a staging environment (e.g. the mail server) it is also important to document these dependencies so that his fellow developers know about them. I always hate it when I run the test suite on a new application and half the tests fail because my workstation has no network access to the testing database!
A second point with integration tests that must be accounted is the use of detailed logging. When a unit test fails it is very easy to understand why since the scope is very narrow. When an integration test fails, things are not so simple. Because by definition an integration tests is based on many components and a specific data flow, identifying the failure cause is not always straightforward.
My recommended way to alleviate this problem, is the use of detailed logging statements (that are always needed in an Enterprise application regardless of unit tests). This way, when an integration test fails you can examine the logs and understand if the issue is in the code or in an external resource used by the test.
Why integration tests should NEVER run together with unit tests
Now we reach the most important point regarding unit tests. In a big enterprise application integration and unit tests MUST be handled differently. Here is an all too common scenario that I have personally seen multiple times.
Some developer has created a lot of unit and integration tests. All of them are executed by Maven when the test goal is run. However during a server migration some of the integration tests stop working. However everyone on the team is busy and nobody fixes the IPs in the configuration files.
Soon after some integration tests that depend on an external system run really slowly. But nobody has time to investigate the cause. Developers no longer run tests before committing code because the test suite is very slow. More unit tests break as a result, since developers do not maintain them.
New developers come into the team. They start working on the RESERVATION SYSTEM and soon find out that half the test suite is broken. Most of them do not even bother with unit tests anymore.
A valiant developer comes into the team and says that this madness must stop. He spends a day and finds out that the effort required to fix all tests is not realistic for the current time-frame. He also finds out that in several cases the unit tests are broken because of changes in the business requirements. So fixings the tests is not a straightforward process since somebody has to adapt them to new code.
By this point it is clear that tests are not actually used in this project. New developers simply declare that “writing unit tests is a waste of time” and they are right from their point of view, since nobody wants to work with a broken test suit.
This is a scenario that we need to avoid!
Delegating integration tests to Maven Failsafe plugin
There are many ways to split unit and integration tests. My suggestion is to use the
Maven failsafe plugin.
Unit tests should follow the naming convention introduced in the
first part of this series. Unit test classes are named with “name of class + Test”. Then they are placed in the test directory of the
Maven project structure.
The unit tests are executed automatically when the test goal is run.
Next you should add the failsafe plugin in your pom.xml file.
<project>
…
<build>
<plugins>
…
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>2.13</version>
<executions>
<execution>
<id>integration-test</id>
<goals>
<goal>integration-test</goal>
</goals>
</execution>
<execution>
<id>verify</id>
<goals>
<goal>verify</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
Your integration tests however have a different naming convention. They are named as “name of class + IT”. IT stands for Integration Test.
Now the test goal will ignore them. Instead these tests will be executed by the integration-test goal which is a built-in goal into Maven. Here is a table that summarizes this split
| Unit tests | Integration Tests |
|---|
| Located in | Maven test directory | Maven test directory |
| Naming convention | name of class + Test | name of class + IT |
| Example class name | BasketWeightTest.java | InvoicingProcessorIT.java |
| Managed by | Maven surefire plugin | Maven failsafe plugin |
| Executed in test goal | Yes | No |
| Executed in integration-test goal | No | Yes |
How to run integration tests in your build process
Now that all these changes are done you have great flexibility on how you run unit tests. Most importantly your build server (e.g. Jenkins) should contain a mixture of jobs that deal with both kinds of tests. Here is a overview of suggested jobs.
| Job type | Schedule | Description | Tests |
|---|
| Main build | Every 15 minutes or half hour. | Only compiles and runs unit tests. Should finish in 15-20 minutes max | Only unit tests |
| Integration build | Every 24 hours (usually at night) | Runs integrations tests. Can run for 2-3 hours | All tests |
| QA build | Manually | Deploys to a QA environment | All tests |
The suggested workflow is the following
- Developers run the test goal during development
- Developers run the test goal before any commit
- Developers run the integration-test goal before a major commit with many side effects
- Build server compiles code and runs the test goal every 15-30 minutes (main build)
- Build server compiles code and runs the integration-test goal every day (integration build)
- Build server compiles code and runs the integration-test goal before a release to QA
With this workflow it is clear that developers get fast feedback from the unit tests so anything that breaks can be fixed immediately. The boring process of running integration tests is left to the build server which runs them automatically in a well defined schedule.
Conclusion
In this post we have finally tackled integration tests. We showed you the differences with unit tests regarding test focus, external systems and running time.
We also hope we convinced you that they must be handled differently. Our suggested method for splitting tests is the maven failsafe plugin.
Finally we proposed some combinations of build jobs and how they run different types of tests.
Feel free to post your suggestions below regarding unit and integration tests.
Programming thought of the day:
- Me: Siri, why am I alone?
- Siri: *opens front facing camera*
