circle-exclamation
These docs are still under construction and may contain outdated references to Earthly and/or broken links.
search

Integration Testing

Running unit tests in a build pipeline is relatively simple. By definition, unit tests have no external dependencies. Things get more interesting when we want to test how our service integrates with other services and external systems. A service may have dependencies on external file systems, on databases, on external message queues, or other services. An ergonomic and effective development environment should have simple ways to construct and run integration tests. It should be easy to run these tests locally on the developer machine and in the build pipeline.

** This guide will take an existing application with integration tests and show how they can be easily run inside earthly, both in the local development environment as well as in the build pipeline. **

hashtag
Prerequisites

This integration approach can work with most applications and development stacks. See examplesarrow-up-right for guidance on using earthly in other languages.

hashtag
Our Application

The application we start with is simple. It returns the first 5 countries alphabetically via standard out. It has unit tests and integration tests. The integration tests require a datastore with the correct data in place.

hashtag
The Basic Earthfile

We start with a simple Earthfile that can build and create a docker image for our app. See the Basics guide for more details, as well as examples in many programming languages.

See the Basics Guide for more details on these steps, including how they might differ in Go, JavaScript, Java, and Python.

hashtag
In-App Integration Testing

Since our service has a docker-compose file of dependencies, running integration tests is easy.

Our integration target needs to copy in our source code and our Dockerfile and then inside a WITH DOCKER start the tests:

integration-test:
    FROM +project-files
    COPY src src
    COPY docker-compose.yml ./
    WITH DOCKER --compose docker-compose.yml
        RUN while ! pg_isready --host=localhost --port=5432 --dbname=iso3166 --username=postgres; do sleep 1; done ;\
            sbt it:test
    END

The WITH DOCKER has a --compose flag that we use to start up our docker-compose and run our integration tests in that context.

We can now run our tests both locally and in the CI pipeline, in a reproducible way:

This means that if an integration test fails in the build pipeline, you can easily reproduce it locally.

hashtag
End to End Integration Tests

Our first integration test used was part of the service we were testing. This is one way to exercise integration code paths. Another useful form of integration testing is end-to-end testing. In this form of integration testing, we start up the application and test it from the outside.

In our simplified case example, with a single code path, a test that verifies the application starts and produces the desired output is sufficient.

Output: We can then run this and check that our application with its dependencies, produces the correct output.

hashtag
Bringing It All Together

Adding these testing targets to an all target, we now can unit test, integration test, and dockerize and push our software in a single command. Using this approach, integration tests that fail sporadically for environmental reasons and can't be reproduced consistently should be a thing of the past.

There we have it, a reproducible integration process. If you have questions about the example, askarrow-up-right.

hashtag
See also

PreviousAuthenticating Git and image registriesNextDebugging techniques

Last updated