Integration Unit Testing

Integration unit testing is an API testing strategy that combines the core benefits from traditional unit testing and integration testing. It is for API and integration test automation, and for replacing traditional unit testing in the API ecosystem.

A little background

Software backend systems in modern enterprises are often seen to be distributed, like applications, databases, SCADA services, etc. Each backend system, small or huge, specializes in some business functionalities.

To make all the backend systems, plus frontend user interfaces, work well together to support integral enterprise business, distributed architectures or techniques like Microservices, SOA, ESB, Messaging, etc. are often used, resulting in the proliferation of APIs.

Each API represents a small piece of business or integration functionality in a backend system. APIs are exposed through various protocols like HTTP, JMS, FTP, etc. to enable integration with each other.

Here is a sample API:

Sample API

This sample API exposes an HTTP endpoint, and, when invoked, interacts with three dependencies: another HTTP API, a database and a queue. In the real world, a normal API probably won’t have too many dependencies, but here we just make the sample API look more illustrative.

To test enterprise software systems, there was traditional test pyramid

Traditional Test Pyramid

Traditional unit testing was invented when most backend systems were siloed and monolithic applications. It feels not so fitting into the API ecosystem.

Some characteristics of traditional unit testing when applied on APIs are

  • Single-process testing. Everything runs in the same process, including test case, the API implementation under test and its dependencies. To achieve test isolation, the API implementation’s dependencies are mocked. When the API’s input protocol relies on a middleware that can’t be embedded in the same process, like JMS (Solace), normally the input protocol is also bypassed during the testing. So the API implementation’s interactions with other processes are not tested.

These characteristics are so as to make the unit tests easy and fast to run. In fact, people have been so enthusiastic on the ‘run’ aspect, that the critical issues coming along have been largely ignored.

Some critical issues with traditional unit testing in the API ecosystem are:

  1. Duplicate testing. When developer finishes traditional unit testing, he or she faces one question: is my code now good enough to be handed over to tester for testing? Normally the answer is no, because the API implementation code has not been tested with real dependencies such as a real database. By mocking out a dependency database, the developer is unsure whether the SQL statements in the API implementation will work when a real database is used. The developer risks receiving defects soon from tester. With API definition/specification being a well communicated deck for all people in the team, testing against API definition/specification seems unavoidable. If the developer chooses to also integration testing the API, it will be largely duplicate with the traditional unit testing he or she has already done, especially for testing with various API input data.

To address the issues, this article promotes integration unit testing as a replacement of traditional unit testing in the API ecosystem.

What is integration unit testing?

‘Unit testing’ here means API level test isolation. To test an API, use stubs as its dependencies like HTTP stubs, stub database, stub queues, etc. Stubs here are dedicated systems, like a dedicated database, for integration unit testing purpose. They are replacements of real systems that the API will interact with in production environment. They can be fully controlled by integration unit test cases. Use test case and stubs to control the behavior of the API under test. Treat the entire API under test (instead of one inner piece of it) as a unit.

‘Integration’ here means multi-process. Test case, the API under test and its dependencies (stubs) run in different processes. The API implementation still interacts with its dependencies (stubs) via real cross-process protocols like HTTP, ODBC, JMS, etc.

Sample API Test Isolation

When doing integration unit testing on an API, stub its dependencies, call its input endpoint (like an HTTP endpoint), and then check the stubs status and data to verify the API’s behavior is as expected.

As can be seen, the behavior tested here is much closer to the behavior of the API in production environment, comparing to traditional unit testing.

Characteristics of API integration unit testing

  • Multi-process testing. As described above.

Let’s recap how the issues with traditional unit testing are addressed by integration unit testing, in the API ecosystem.

  1. No duplicate testing. Traditional unit testing is replaced with integration unit testing, hence no more question from developer as to un-tested API definition/specification or cross-process interactions between the API and its dependencies.

In fact, it is very intuitive to do integration unit testing. Many teams have API or integration design documents. These documents describe how the API is invoked, how it interacts with its external dependencies (HTTP APIs, queues, databases, etc.), and the data/message transformations inside the APIs. Developers are naturally inclined to test against the design documents, so as to talk the same language as the entire team (team is straightforwardly aligned around design documents).

So this article promotes a new test pyramid for the API ecosystem.

New Test Pyramid for API Ecosystem

The good tool

API Test Base (ATB) is a tool designed for Integration Unit Testing (automated) and System Integration Testing (manual, semi-automated or automated) in the API ecosystem.

Integration unit testing examples using ATB:



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store