Integration Testing

What it is

An integration test verifies that two or more units work together — your code plus a real, or realistically faked, collaborator. Where a unit test replaces everything around the subject, an integration test lets the seams be real: a database, a message queue, an HTTP layer, another module.

Integration tests catch the bugs unit tests structurally cannot: mismatched contracts, wrong SQL, misconfigured serialization, wrong transaction boundaries.

When to use it / when to avoid it

Use it for

The boundary between your code and a datastore, queue, cache or external HTTP API
Wiring: dependency injection, configuration, migrations
Multi-step flows inside one deployable (e.g. controller → service → repository)

Avoid it when

The concern is pure logic → a fast unit test is better
The whole system across the network must be exercised → that is end-to-end
The dependency is another team’s service you cannot run → use contract testing

Frameworks & tools

Tool	Ecosystem	Notes
Testcontainers	Multi (Java, Go, Node, Python, .NET)	Real DB/queue/broker in Docker, disposed after the test
Supertest	Node.js	Drive an HTTP server in-process
Spring Boot Test	Java	`@SpringBootTest`, slices, embedded DB support
WireMock	Multi	Stub HTTP dependencies
MockServer	Multi	Expect/verify HTTP interactions
pytest + testcontainers	Python	Same containers, Python fixtures
`httptest`	Go	In-process HTTP servers for tests
Docker Compose	Any	Bring up a dependency graph for the suite

Quick setup

1
npm install -D vitest testcontainers supertest

1
import { PostgreSqlContainer } from '@testcontainers/postgresql';
2

3
const pg = await new PostgreSqlContainer().start();
4
const url = pg.getConnectionUri();   // real PostgreSQL, per run

1
pip install pytest testcontainers

1
go get github.com/testcontainers/testcontainers-go

1
<dependency>
2
  <groupId>org.testcontainers</groupId>
3
  <artifactId>postgresql</artifactId>
4
  <version>1.20.1</version>
5
  <scope>test</scope>
6
</dependency>

1
dotnet add package Testcontainers.PostgreSql
2
dotnet add package Microsoft.AspNetCore.Mvc.Testing

Example

1
import request from 'supertest';
2
import { app } from '../src/app';
3

4
it('creates and reads back a user', async () => {
5
  const created = await request(app)
6
    .post('/users')
7
    .send({ name: 'Ada' })
8
    .expect(201);
9

10
  const res = await request(app)
11
    .get(`/users/${created.body.id}`)
12
    .expect(200);
13

14
  expect(res.body.name).toBe('Ada');
15
});

1
import pytest
2
from testcontainers.postgres import PostgresContainer
3

4
@pytest.fixture(scope="session")
5
def db():
6
    with PostgresContainer("postgres:16") as pg:
7
        yield pg.get_connection_url()
8

9
def test_insert_and_read(db):
10
    repo = UserRepo(db)
11
    uid = repo.create(name="Ada")
12
    assert repo.get(uid)["name"] == "Ada"

1
func TestCreateAndReadUser(t *testing.T) {
2
  srv := httptest.NewServer(app.Router())
3
  defer srv.Close()
4

5
  res, err := http.Post(srv.URL+"/users", "application/json",
6
    strings.NewReader(`{"name":"Ada"}`))
7
  if err != nil || res.StatusCode != http.StatusCreated {
8
    t.Fatalf("create failed: %v %d", err, res.StatusCode)
9
  }
10
}

1
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
2
class UserApiTest {
3
  @Autowired TestRestTemplate rest;
4

5
  @Test
6
  void createsAndReadsBackUser() {
7
    var created = rest.postForEntity("/users", new User("Ada"), User.class);
8
    assertEquals(HttpStatus.CREATED, created.getStatusCode());
9
  }
10
}

1
public class UserApiTests : IClassFixture<WebApplicationFactory<Program>>
2
{
3
    private readonly HttpClient _client;
4
    public UserApiTests(WebApplicationFactory<Program> f) => _client = f.CreateClient();
5

6
    [Fact]
7
    public async Task CreatesAndReadsBackUser()
8
    {
9
        var created = await _client.PostAsJsonAsync("/users", new { Name = "Ada" });
10
        Assert.Equal(HttpStatusCode.Created, created.StatusCode);
11
    }
12
}

Anti-patterns & best practices

Fake the boundaries you cannot own. Use Testcontainers or a real dev DB; mock only genuinely external, uncontrollable services.
Isolate per test. Roll back transactions or recreate schema per test so runs are independent and parallelizable.
Seed with builders. Factory functions beat a shared fixtures.sql that drifts.
Do not assert on internals of a dependency. Assert on your behaviour as observed through the boundary.
Keep the suite fast enough to run often. Integration tests are slower than units; prune duplicates and run them in CI on every push.