如何用MockMvc和Spring Security过滤器编写Spring Boot控制器集成测试

一、最简配置：仅测试控制器逻辑+模拟认证 #

如果你只需要验证控制器的业务逻辑，不需要真实的Spring Security过滤器链，用以下配置即可解决WebSecurityConfig依赖报错问题：

@RunWith(SpringJUnit4ClassRunner.class)
@WebMvcTest(目标控制器类.class) // 仅加载指定控制器的上下文，避免加载全量应用Bean
@AutoConfigureMockMvc(addFilters = false) // 关闭默认安全过滤器，跳过真实认证流程
@WithMockUser(username = "testUser", roles = {"USER"}) // 全局模拟已认证用户
public class CsrfShowcaseTests {

    @Autowired
    private MockMvc mockMvc;

    // Mock控制器依赖的所有外部服务/DAO
    @MockBean
    private 控制器依赖类 依赖实例;

    // 测试示例：访问受保护的GET端点
    @Test
    public void testSecuredGetEndpoint() throws Exception {
        // 模拟依赖方法的返回值（如果需要）
        when(依赖实例.方法名(参数)).thenReturn(预期结果);

        mockMvc.perform(get("/secured-path"))
                .andExpect(status().isOk())
                .andExpect(content().string(预期响应内容));
    }
}

关键注解说明 #

• @WebMvcTest：仅初始化Spring MVC相关组件（控制器、视图解析器、消息转换器等），不会加载Service、Repository或自定义安全配置的全量Bean，从根源避免依赖缺失问题。
• @AutoConfigureMockMvc(addFilters = false)：关闭默认的安全过滤器链，无需处理WebSecurityConfig的复杂依赖。
• @WithMockUser：直接模拟已通过认证的用户，无需走真实的登录、过滤器校验流程，支持指定用户名、角色。
• @MockBean：自动生成控制器依赖Bean的Mock实例，避免因依赖未加载导致的上下文初始化失败。

二、进阶配置：测试真实安全规则 #

如果需要验证Spring Security的权限控制、CSRF校验等规则，需导入自定义安全配置并Mock其依赖：

@RunWith(SpringJUnit4ClassRunner.class)
@WebMvcTest(目标控制器类.class)
@Import(WebSecurityConfig.class) // 导入自定义安全配置类
@AutoConfigureMockMvc
public class CsrfShowcaseTests {

    @Autowired
    private MockMvc mockMvc;

    // Mock WebSecurityConfig依赖的所有Bean（比如用户认证服务、权限管理器）
    @MockBean
    private 安全配置依赖类 安全依赖实例;

    // 测试管理员权限端点
    @Test
    @WithMockUser(roles = {"ADMIN"}) // 模拟管理员角色用户
    public void testAdminOnlyEndpoint() throws Exception {
        mockMvc.perform(get("/admin-path"))
                .andExpect(status().isOk());
    }

    // 测试POST请求的CSRF校验（如需关闭测试用CSRF，添加.csrf().disable()）
    @Test
    @WithMockUser
    public void testPostEndpointWithCsrf() throws Exception {
        mockMvc.perform(post("/submit-form")
                        .param("data", "test")
                        .csrf()) // 自动添加CSRF Token
                .andExpect(status().isOk());
    }
}

注意事项 #

• 必须用@MockBean模拟WebSecurityConfig的所有依赖Bean，否则会因依赖缺失导致上下文加载失败。
• @WithMockUser的roles属性默认会自动添加ROLE_前缀，若你的安全配置中使用了无前缀的权限，需改用authorities属性（比如@WithMockUser(authorities = {"ADMIN"})）。

三、常见问题排查 #

1. WebSecurityConfig依赖Bean找不到：用@MockBean模拟该依赖，或切换到最简配置（不导入WebSecurityConfig）。
2. 403 Forbidden但已加@WithMockUser：检查用户角色/权限是否与端点的安全配置匹配，确认roles/authorities属性是否正确。
3. CSRF校验失败：测试POST请求时，要么添加.csrf()自动生成Token，要么用.csrf().disable()临时关闭（仅用于测试）。

内容的提问来源于stack exchange，提问作者Nathan