@SpringBootTest webEnvironment Options

Direct Answer

MOCK is the default: it creates a web ApplicationContext when the classpath supports one, without starting an embedded server, and servlet applications can add MockMvc. RANDOM_PORT starts a server on an available port; DEFINED_PORT starts it on the configured port; NONE creates a non-web context. The client can be TestRestTemplate, WebTestClient, or another suitable client.

Code Example

// MOCK (default): no real server, drive it with MockMvc
@SpringBootTest // webEnvironment = MOCK by default
@AutoConfigureMockMvc
class MockEnvTest {
    @Autowired MockMvc mockMvc;

    @Test
    void hitsEndpoint() throws Exception {
        mockMvc.perform(get("/api/orders"))
               .andExpect(status().isOk());
    }
}

// RANDOM_PORT: a real server starts, call it with TestRestTemplate
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class RandomPortTest {
    @LocalServerPort int port;            // the random port, injected
    @Autowired TestRestTemplate rest;

    @Test
    void callsRealHttp() {
        var body = rest.getForObject(
            "http://localhost:" + port + "/api/orders", String.class);
        assertThat(body).isNotNull();
    }
}

Swap MOCK for RANDOM_PORT the moment you need a real socket — TestRestTemplate has nothing to talk to under MOCK.

Common Mistakes & Pitfalls

• Using a network client with MOCK: MOCK does not open a listening server. Use MockMvc/WebTestClient against the mock context, or choose a port mode for real HTTP.
• Hard-coding the random port: An injected TestRestTemplate can use relative paths with its configured root URL. If another client builds an absolute URL, read the actual port with @LocalServerPort.
• Choosing DEFINED_PORT without isolation: A fixed port can collide when test processes run in parallel. Use it only when that exact port is part of the requirement and the environment reserves it.
• Omitting DEFINED_PORT from the model: It is a fourth option beside MOCK, RANDOM_PORT, and NONE.