Spring WebTestClient target: distinguish mock binding from a running port

Binding defines the test

WebTestClient can bind directly to a controller or ApplicationContext, or to a running server. The first choices use mock request and response handling; bindToServer uses HTTP and a base URL. A receipt endpoint may pass a mock-bound test while a reverse proxy, connector setting or real cookie attribute fails in deployment. MockMvc has the same servlet mock boundary. Name the test by its binding mode so a passing result is not mistaken for a socket test.

Use the running port for transport evidence

With a random-port Boot test, build WebTestClient against the injected local port. Assert status, headers and JSON, then inspect durable state through a separate database connection. The HTTP server runs the request in another thread and transaction, so a test-thread @Transactional rollback does not undo server writes. That transaction split changes fixture setup and teardown. Keep request deadlines and response size bounded to avoid hanging the test suite.

Keep mock checks fast

Use context-bound tests for serialization, status mapping and controller validation. Reserve live-server tests for representative connector, security and transaction behavior, and verify any proxy-specific behavior in a deployment environment. The failure-layer matrix prevents one large HTTP test from becoming the only evidence for every layer. Do not switch binding modes mid-test and expect the same database visibility rules.

Implementation contract

WebTestClient client = WebTestClient.bindToServer()
    .baseUrl(localServerBaseAddress)
    .build();
client.get().uri("/api/receipts/r-47").exchange()
    .expectStatus().isOk()
    .expectBody().jsonPath("$.status").isEqualTo("issued");

Cost and verification

A live server adds startup, socket and serialization work to each scenario. Mock-bound tests are faster but cannot establish connector or cross-thread transaction behavior.

Common Mistakes

• Do not label a context-bound client test end-to-end HTTP.
• Do not expect test-thread rollback to undo live-server writes.
• Do not use a fixed port that collides with another parallel test process.

Read next

Spring MockMvc tests: HTTP behavior without claiming a real network test, Spring Boot HTTP test: client rollback does not own server writes, Test Spring RestClient on a socket without claiming a remote service, Spring test failures: prove the layer that can reject the request, Spring Testcontainers parallel tests: one database can leak another test's rows.