test_detective

Writing reliable tests for Spring Boot Actuator endpoints

Spring Boot Actuator exposes the operational surface of an application: health checks, metrics, environment details, application information and custom management endpoints. These URLs are often treated as infrastructure concerns, yet they affect deployment decisions, incident response and security. A small testing gap can therefore make a service appear healthy when it cannot serve real traffic.

A useful test strategy checks more than HTTP status codes. It verifies response structure, security rules, health transitions, metric registration and behaviour under the application profiles used in production. This matters for Australian teams operating across Sydney, Melbourne, Brisbane and Perth, where regional deployments, customer support hours and cloud monitoring integrations all depend on trustworthy signals.

Testing approach Best for Main strength Typical limitation
Unit tests Health indicators and contributors Fast feedback and precise edge cases Does not verify HTTP exposure
@WebMvcTest Routing, JSON and access rules Focused web-layer coverage May need mocked Actuator configuration
@SpringBootTest with MockMvc Integrated endpoint behaviour Real application configuration Slower and more setup-sensitive
Testcontainers or live HTTP tests Database, broker and platform checks Exercises realistic dependencies Higher runtime and maintenance cost
Contract or smoke tests Deployment verification Confirms monitoring-facing behaviour Less detailed failure diagnosis

Define the operational contract first

Before writing a test, decide what each endpoint promises. For /actuator/health, that may mean returning 200 OK when the application is ready and 503 Service Unavailable when a critical dependency fails. For /actuator/info, it may mean exposing only approved build metadata. For metrics, the contract might cover the presence of a name and tags rather than a fixed numeric value.

Spring Boot’s configuration determines which endpoints are exposed. management.endpoints.web.exposure.include controls exposure, while management.endpoint.health.show-details influences the amount of health information returned. Tests should load the same relevant properties as the deployed application; otherwise, they can pass against an endpoint that is disabled or configured differently in production.

A concise contract also helps distinguish liveness from readiness. A process can be alive while a database connection is unavailable, and a readiness probe should communicate that difference. Australian Kubernetes platforms hosted in Sydney or Melbourne regions often route these probes through load balancers and deployment controllers, so a wrong status code can cause unnecessary restarts or remove healthy instances from service.

Select the right Spring test slice

Unit testing a custom HealthIndicator is usually the cheapest starting point. Mock the dependency, configure success and failure responses, and assert the resulting Health status and details. This is especially useful for indicators that call an external payment provider, message broker or internal REST service.

The next level is a web-layer test that verifies endpoint serialisation and routing. Depending on the Spring Boot version and configuration, Actuator infrastructure may not be included automatically in a narrow @WebMvcTest. If the endpoint is absent, add the necessary Actuator configuration or use a broader test context rather than weakening the assertion.

For practical examples of Java testing patterns and supporting techniques, a testing notes archive can provide useful background alongside the Spring documentation. The important choice is to match test scope to risk: a unit test explains business logic failures, while an integrated test exposes configuration and filter-chain mistakes.

Verify HTTP responses with MockMvc

MockMvc is well suited to checking status codes, content types, JSON fields and request authentication without opening a real server port. A health test can call /actuator/health, assert application/vnd.spring-boot.actuator.v3+json or the configured JSON media type, and inspect the status field. Avoid asserting the entire response body when framework versions may add harmless fields.

A useful test might look conceptually like this:

mockMvc.perform(get("/actuator/health"))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$.status").value("UP"));

The failure path deserves equal attention. Configure a mocked repository or broker client to fail, then assert the status expected by the deployment platform. If details are intentionally hidden, verify that sensitive fields such as connection strings, hostnames or exception messages are absent.

For /actuator/metrics, test the response shape and a known metric such as jvm.memory.used or an application counter. A metric can exist but still be unusable if a tag is missing, a name changes unexpectedly or a high-cardinality value such as userId is introduced. These checks protect monitoring dashboards as well as the endpoint itself.

Test exposure and security boundaries

Actuator endpoints frequently sit behind a separate management port or a dedicated security matcher. Tests should prove which endpoints are public, which require an authenticated principal and which are unavailable altogether. A successful response for /actuator/health should not imply that /actuator/env, /actuator/beans or /actuator/configprops is equally accessible.

With Spring Security, include tests for anonymous access, ordinary authenticated users and an operations role where appropriate. Assert both the HTTP status and the absence of confidential values. Depending on the security design, unauthorised requests may receive 401, while authenticated users without permission receive 403; the distinction should be deliberate rather than an accidental result of filter ordering.

Check CSRF and management-port behaviour when these controls are relevant. A separate port can change the effective network boundary, while a reverse proxy may rewrite paths or headers. In an Australian retail or financial environment, security reviewers may expect evidence that operational endpoints cannot disclose customer or infrastructure data, particularly around end-of-financial-year reporting when release activity increases.

Exercise health indicators and custom checks

A custom HealthIndicator should have tests for normal operation, dependency failure, timeout and malformed responses. A timeout is often more realistic than an immediate exception: a remote system may be slow enough to consume request threads while still technically responding. Use deterministic mocks or a controllable test server so that these scenarios remain fast and repeatable.

If the application uses ReactiveHealthIndicator, test non-blocking completion and error propagation. For asynchronous dependencies, verify that a delayed or failed Mono produces the intended status rather than hanging the health request. A health endpoint should not wait indefinitely for a dependency that is already known to be unavailable.

Keep sensitive detail under control. The detail map can be valuable to internal operators, but it should not contain credentials, raw exception text or complete third-party responses. Tests that assert allowed keys and redact forbidden values make the policy visible. This is particularly useful when services are shared between Australian and overseas support teams with different access requirements.

Cover metrics and asynchronous behaviour

Metrics testing has two layers. First, confirm that meters are registered with stable names, units and tags. Second, exercise the operation that changes the measurement and check that the value moves in the expected direction. Exact values can be fragile when other tests share a registry, so isolate the MeterRegistry or reset it between scenarios.

For counters, assert an increment after a successful event and decide what should happen after a rejected or failed event. For timers, verify that a completed operation records a sample without trying to match an exact duration. For gauges, test the source value and lifecycle carefully because gauges commonly reference mutable objects that may be replaced or garbage-collected.

Asynchronous processing needs an explicit waiting strategy. Awaitility, Reactor’s StepVerifier or a test-specific event listener can coordinate assertions without arbitrary sleeps. A test that waits for a queue consumer to update a metric should have a bounded timeout and a useful failure message. This prevents a Brisbane or Perth build agent with different scheduling characteristics from producing intermittent results.

Build a practical actuator test suite

A balanced suite separates quick checks from environment-dependent verification. Run unit and web tests on every commit, then reserve container-backed checks for pull requests or deployment pipelines. This keeps feedback fast while still testing the database, broker and monitoring integrations that cannot be represented accurately by mocks.

Useful assertions to keep close to the code include:

A small number of smoke tests can then validate the packaged application. Start it with the same profile and management settings used in the target environment, call the important endpoints over HTTP and record failures with response bodies that are safe to retain. Test the management port separately when it is configured, since a main application port check does not prove that Actuator is reachable or protected correctly.

For delivery pipelines, group checks by purpose rather than by framework annotation. A practical split is:

Use stable test data, explicit profiles and isolated registries. Avoid coupling assertions to timestamps, random IDs or the exact ordering of JSON properties. When the application is deployed across Australian time zones and daylight-saving boundaries, test scheduling and timestamp formatting with fixed clocks rather than relying on the machine’s local zone.

A dependable Actuator suite proves that operational endpoints tell the truth, reveal only what they should and continue to work as configuration evolves. The practical takeaway is simple: test each management endpoint at the narrowest useful level, then add a small set of live checks that reflects how your production platform decides whether the service is healthy.