0
# Spring Security Test
1

2
Spring Security Test provides comprehensive testing utilities for Spring Security applications, enabling developers to easily test authentication, authorization, and security configurations. It offers mock authentication support through annotations, declarative security context management, and utilities for testing both servlet-based and reactive Spring applications.
3

4
## Package Information
5

6
- **Package Name**: spring-security-test
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.springframework.security
10
- **Artifact ID**: spring-security-test
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
    <groupId>org.springframework.security</groupId>
15
    <artifactId>spring-security-test</artifactId>
16
    <version>6.5.1</version>
17
    <scope>test</scope>
18
  </dependency>
19
  ```
20

21
For Gradle:
22
```gradle
23
testImplementation 'org.springframework.security:spring-security-test:6.5.1'
24
```
25

26
## Core Imports
27

28
```java
29
import org.springframework.security.test.context.support.WithMockUser;
30
import org.springframework.security.test.context.support.WithAnonymousUser;
31
import org.springframework.security.test.context.support.WithUserDetails;
32
import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.*;
33
import static org.springframework.security.test.web.servlet.setup.SecurityMockMvcConfigurers.springSecurity;
34
```
35

36
## Basic Usage
37

38
```java
39
import org.springframework.security.test.context.support.WithMockUser;
40
import org.springframework.test.web.servlet.MockMvc;
41
import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.user;
42
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
43
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
44

45
@SpringBootTest
46
@AutoConfigureTestDatabase
47
public class SecurityTestExample {
48

49
    @Autowired
50
    private MockMvc mockMvc;
51

52
    // Using annotation-based authentication
53
    @Test
54
    @WithMockUser(roles = "ADMIN")
55
    public void testAdminEndpoint() throws Exception {
56
        mockMvc.perform(get("/admin"))
57
               .andExpect(status().isOk());
58
    }
59

60
    // Using request post-processors
61
    @Test
62
    public void testWithRequestPostProcessor() throws Exception {
63
        mockMvc.perform(get("/secure")
64
                .with(user("testuser").roles("USER")))
65
               .andExpect(status().isOk());
66
    }
67
}
68
```
69

70
## Architecture
71

72
Spring Security Test is built around several key components:
73

74
- **Security Context Annotations**: Method and class-level annotations like `@WithMockUser` that establish security contexts declaratively
75
- **Test Execution Listeners**: Integration with Spring Test framework to manage security context lifecycle during test execution
76
- **MockMvc Integration**: Request post-processors and configurers that integrate with Spring MVC Test framework
77
- **WebTestClient Integration**: Reactive testing support with mutators for WebFlux applications
78
- **Context Management**: Thread-local security context management optimized for test environments
79

80
## Capabilities
81

82
### Security Context Annotations
83

84
Core testing annotations for declarative security context management, providing method and class-level authentication setup without complex configuration.
85

86
```java { .api }
87
@WithMockUser(username = "user", roles = {"USER"}, authorities = {})
88
@WithAnonymousUser
89
@WithUserDetails(value = "user", userDetailsServiceBeanName = "")
90
@WithSecurityContext(factory = WithSecurityContextFactory.class)
91
```
92

93
[Security Context Annotations](./security-context-annotations.md)
94

95
### MockMvc Integration
96

97
Comprehensive MockMvc integration providing request post-processors, configurers, and result matchers for testing web security in servlet-based applications.
98

99
```java { .api }
100
// Setup
101
MockMvcConfigurer springSecurity();
102

103
// Request post-processors
104
RequestPostProcessor user(String username);
105
RequestPostProcessor httpBasic(String username, String password);
106
RequestPostProcessor jwt();
107
RequestPostProcessor csrf();
108

109
// Result matchers
110
ResultMatcher authenticated();
111
ResultMatcher unauthenticated();
112
```
113

114
[MockMvc Integration](./mockmvc-integration.md)
115

116
### Reactive Testing (WebTestClient)
117

118
WebTestClient integration for testing security in reactive Spring WebFlux applications, providing mutators for various authentication scenarios.
119

120
```java { .api }
121
// Server configurers
122
MockServerConfigurer springSecurity();
123

124
// Authentication mutators
125
UserExchangeMutator mockUser();
126
JwtMutator mockJwt();
127
OAuth2LoginMutator mockOAuth2Login();
128
CsrfMutator csrf();
129
```
130

131
[Reactive Testing](./reactive-testing.md)
132

133
### Test Context Management
134

135
Low-level utilities for programmatic security context management and integration with Spring Test framework execution listeners.
136

137
```java { .api }
138
class TestSecurityContextHolder {
139
    static void setContext(SecurityContext context);
140
    static SecurityContext getContext();
141
    static void clearContext();
142
    static void setAuthentication(Authentication authentication);
143
}
144
```
145

146
[Test Context Management](./test-context-management.md)
147

148
## Types
149

150
```java { .api }
151
enum TestExecutionEvent {
152
    TEST_METHOD,
153
    TEST_EXECUTION
154
}
155

156
interface WithSecurityContextFactory<A extends Annotation> {
157
    SecurityContext createSecurityContext(A annotation);
158
}
159

160
interface AuthenticatedMatcher extends ResultMatcher {
161
    AuthenticatedMatcher withUsername(String expected);
162
    AuthenticatedMatcher withRoles(String... roles);
163
    AuthenticatedMatcher withAuthorities(Collection<? extends GrantedAuthority> expected);
164
}
165
```