Introduction

Integration tests with TestRestTemplate often need request headers for tenant context, auth, locale, or tracing. The test can pass locally without these headers and still fail in production because controller filters or interceptors are bypassed. Good integration tests should mirror real request metadata, not only endpoint paths.

Core Sections

1. Build request entities with explicit headers

Use HttpHeaders and HttpEntity to keep header setup visible in test code. This makes tests easier to review and simplifies debugging when a security filter rejects requests.

1HttpHeaders headers = new HttpHeaders();
2headers.set("X-Tenant", "acme");
3headers.setBearerAuth("integration-test-token");
4headers.setContentType(MediaType.APPLICATION_JSON);
5
6HttpEntity<Void> request = new HttpEntity<>(headers);
7ResponseEntity<String> response = testRestTemplate.exchange(
8    "/api/orders",
9    HttpMethod.GET,
10    request,
11    String.class
12);

2. Test both positive and negative header behavior

A complete integration test should verify:

• Request succeeds with required headers.
• Request fails with missing or invalid headers.

This catches accidental regressions in filter chains and controller advice logic.

1assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
2
3HttpEntity<Void> badRequest = new HttpEntity<>(new HttpHeaders());
4ResponseEntity<String> denied = testRestTemplate.exchange(
5    "/api/orders",
6    HttpMethod.GET,
7    badRequest,
8    String.class
9);
10assertThat(denied.getStatusCode()).isEqualTo(HttpStatus.UNAUTHORIZED);

3. Reusable setup for large test suites

If many tests require the same headers, create a small helper to reduce duplication while preserving explicit semantics. Keep helper behavior simple and avoid hidden defaults that change test meaning.

For authentication-heavy test suites, generating short-lived test tokens in setup can keep coverage realistic and prevent stale hard-coded tokens.

4. Operational realism

Include correlation headers or tenant IDs when your production stack depends on them for routing, logging, or authorization. A test that omits these can produce false confidence because it never exercises the real request path.

The goal is not just endpoint correctness but request-path correctness across security, multi-tenant, and observability layers.

5. Encapsulate header creation without hiding intent

A helper factory can reduce duplication while keeping each test explicit about which headers are required. Prefer small helper methods that return HttpEntity instances instead of global interceptors that silently inject values.

1private HttpEntity<Void> authRequest(String tenant, String token) {
2    HttpHeaders h = new HttpHeaders();
3    h.set("X-Tenant", tenant);
4    h.setBearerAuth(token);
5    h.setAccept(List.of(MediaType.APPLICATION_JSON));
6    return new HttpEntity<>(h);
7}
8
9@Test
10void listOrders_requiresTenantHeader() {
11    ResponseEntity<String> ok = testRestTemplate.exchange(
12        "/api/orders",
13        HttpMethod.GET,
14        authRequest("acme", "good-token"),
15        String.class
16    );
17    assertThat(ok.getStatusCode()).isEqualTo(HttpStatus.OK);
18}

This pattern keeps repeated code small while still showing which request metadata drives endpoint behavior.

6. Verify header propagation to downstream services

For applications that forward headers to internal services, integration tests should verify propagation, not only acceptance at controller level. A mock downstream endpoint can assert expected header values and reveal broken interceptor chains early.

When downstream forwarding is part of security or audit requirements, this check prevents subtle regressions where requests pass locally but lose context in distributed environments.

7. Keep test data deterministic

Header-dependent tests become flaky when token generation, clock skew, or dynamic tenant fixtures vary between runs. Keep deterministic fixtures for tenant IDs and use stable test credentials created in setup. When you need expiring tokens, issue them inside the test lifecycle and assert expected expiration windows explicitly.

Common Pitfalls

• Testing only success headers and never validating missing-header failure behavior.
• Hiding required headers in global test config so test intent becomes unclear.
• Using hard-coded tokens that silently expire and cause flaky builds.
• Forgetting content type or accept headers when endpoint parsing depends on them.
• Assuming unit tests cover filter-chain behavior that only integration tests execute.

Summary

• Header handling is part of endpoint behavior and should be covered in integration tests.
• HttpHeaders plus HttpEntity keeps request metadata explicit and reviewable.
• Always test both valid and invalid header scenarios.
• Reuse helper methods carefully to avoid hiding test assumptions.
• Realistic request metadata improves confidence in production filter-chain behavior.