Update servlet test method docs to use include-code

References gh-16226

Signed-off-by: Joe Kuhel <4983938+jkuhel@users.noreply.github.com>

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethod/HelloMessageService.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethod;
+
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.config.core.MessageService;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.context.SecurityContextHolder;
+
+/**
+ * A message service for demonstrating test support for method-based security.
+ */
+// tag::authenticated[]
+public class HelloMessageService implements MessageService {
+
+	@Override
+	@PreAuthorize("isAuthenticated()")
+	public String getMessage() {
+		Authentication authentication = SecurityContextHolder.getContext()
+				.getAuthentication();
+		return "Hello " + authentication;
+	}
+
+	@Override
+	@PreAuthorize("isAuthenticated()")
+	public String getJsrMessage() {
+		Authentication authentication = SecurityContextHolder.getContext()
+				.getAuthentication();
+		return "Hello JSR " + authentication;
+	}
+}
+// end::authenticated[]

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethod/HelloServiceTests.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethod;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
+import org.springframework.security.config.core.MessageService;
+import org.springframework.security.core.authority.AuthorityUtils;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration
+class HelloServiceTests {
+
+	@Autowired
+	MessageService messageService;
+
+	@BeforeEach
+	void setup() {
+		UsernamePasswordAuthenticationToken user = UsernamePasswordAuthenticationToken.authenticated("user", "password", AuthorityUtils.createAuthorityList("ROLE_USER"));
+		SecurityContextHolder.getContext().setAuthentication(user);
+	}
+
+	@Test
+	void helloServiceTest() {
+		assertThat(messageService.getMessage())
+				.contains("user")
+				.contains("ROLE_USER");
+	}
+
+	@EnableMethodSecurity(prePostEnabled = true, jsr250Enabled = true)
+	@Configuration
+	static class Config {
+
+		@Bean
+		MessageService messageService() {
+			return new HelloMessageService();
+		}
+	}
+}

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodmetaannotations/WithMockAdmin.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodmetaannotations;
+
+import org.springframework.security.test.context.support.WithMockUser;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+// tag::snippet[]
+@Retention(RetentionPolicy.RUNTIME)
+@WithMockUser(value="rob",roles={"USER","ADMIN"})
+public @interface WithMockAdmin { }
+// end::snippet[]

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodmetaannotations/WithMockAdminTests.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodmetaannotations;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
+import org.springframework.security.config.core.MessageService;
+import org.springframework.security.docs.servlet.test.testmethod.HelloMessageService;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration
+public class WithMockAdminTests {
+
+	@Autowired
+	MessageService messageService;
+
+	@Test
+	@WithMockAdmin
+	void getMessageWithMockUserAdminRoles() {
+		String message = messageService.getMessage();
+		assertThat(message)
+				.contains("rob")
+				.contains("ROLE_ADMIN")
+				.contains("ROLE_USER");
+	}
+
+	@EnableMethodSecurity
+	@Configuration
+	static class Config {
+
+		@Bean
+		MessageService messageService() {
+			return new HelloMessageService();
+		}
+	}
+}

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodmetaannotations/WithMockUserTests.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodmetaannotations;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
+import org.springframework.security.config.core.MessageService;
+import org.springframework.security.docs.servlet.test.testmethod.HelloMessageService;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration
+public class WithMockUserTests {
+
+	@Autowired
+	MessageService messageService;
+
+	@Test
+	// tag::snippet[]
+	@WithMockUser(username = "admin", roles = {"USER", "ADMIN"})
+	// end::snippet[]
+	void getMessageWithMockUserAdminRoles() {
+		String message = messageService.getMessage();
+		assertThat(message)
+				.contains("admin")
+				.contains("ROLE_ADMIN")
+				.contains("ROLE_USER");
+	}
+
+	@EnableMethodSecurity
+	@Configuration
+	static class Config {
+
+		@Bean
+		MessageService messageService() {
+			return new HelloMessageService();
+		}
+	}
+}

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodsetup/WithMockUserSampleTests.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodsetup;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.authentication.AuthenticationCredentialsNotFoundException;
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
+import org.springframework.security.docs.servlet.test.testmethod.HelloMessageService;
+import org.springframework.security.config.core.MessageService;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration
+class WithMockUserSampleTests {
+
+	@Autowired
+	MessageService messageService;
+
+	// tag::snippet[]
+	@Test
+	void getMessageUnauthenticated() {
+		assertThatExceptionOfType(AuthenticationCredentialsNotFoundException.class)
+				.isThrownBy(() -> messageService.getMessage());
+	}
+	// end::snippet[]
+
+	@EnableMethodSecurity(prePostEnabled = true, jsr250Enabled = true)
+	@Configuration
+	static class Config {
+
+		@Bean
+		MessageService messageService() {
+			return new HelloMessageService();
+		}
+	}
+}

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodsetup/WithMockUserTests.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodsetup;
+
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+// tag::setup[]
+@ExtendWith(SpringExtension.class) // <1>
+@ContextConfiguration // <2>
+class WithMockUserTests {
+	// ...
+}
+// end::setup[]

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodwithanonymoususer/WithUserClassLevelAuthenticationTests.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodwithanonymoususer;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.springframework.security.test.context.support.WithAnonymousUser;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+// tag::snippet[]
+@ExtendWith(SpringExtension.class)
+@WithMockUser
+class WithUserClassLevelAuthenticationTests {
+
+	@Test
+	void withMockUser1() {
+	}
+
+	@Test
+	void withMockUser2() {
+	}
+
+	@Test
+	@WithAnonymousUser
+	void anonymous() throws Exception {
+		// override default to run as anonymous user
+	}
+}
+// end::snippet[]

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodwithmockuser/WithMockUserClassTests.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodwithmockuser;
+
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+// tag::snippet[]
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration
+@WithMockUser(username = "admin", roles = {"USER", "ADMIN"})
+class WithMockUserClassTests {
+	// ...
+}
+// end::snippet[]

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodwithmockuser/WithMockUserNestedTests.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodwithmockuser;
+
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+// tag::snippet[]
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration
+@WithMockUser(username = "admin", roles = {"USER", "ADMIN"})
+class WithMockUserNestedTests {
+
+	@Nested
+	class TestSuite1 {
+		// ... all test methods use admin user
+	}
+
+	@Nested
+	class TestSuite2 {
+		// ... all test methods use admin user
+	}
+}
+// end::snippet[]

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodwithmockuser/WithMockUserTests.java

@@ -0,0 +1,94 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodwithmockuser;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
+import org.springframework.security.config.core.MessageService;
+import org.springframework.security.docs.servlet.test.testmethod.HelloMessageService;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration
+class WithMockUserTests {
+
+	@Autowired
+	MessageService messageService;
+
+	// tag::mock-user[]
+	@Test
+	@WithMockUser
+	void getMessageWithMockUser() {
+		String message = messageService.getMessage();
+		assertThat(message).contains("user");
+	}
+	// end::mock-user[]
+
+	// tag::custom-user[]
+	@Test
+	@WithMockUser("customUser")
+	void getMessageWithMockUserCustomUsername() {
+		String message = messageService.getMessage();
+		assertThat(message).contains("customUser");
+	}
+	// end::custom-user[]
+
+	// tag::custom-roles[]
+	@Test
+	@WithMockUser(username = "admin", roles = {"USER", "ADMIN"})
+	void getMessageWithMockUserCustomRoles() {
+		String message = messageService.getMessage();
+		assertThat(message)
+				.contains("admin")
+				.contains("ROLE_ADMIN")
+				.contains("ROLE_USER");
+	}
+	// end::custom-roles[]
+
+	// tag::custom-authorities[]
+	@Test
+	@WithMockUser(username = "admin", authorities = {"ADMIN", "USER"})
+	public void getMessageWithMockUserCustomAuthorities() {
+		String message = messageService.getMessage();
+		assertThat(message)
+				.contains("admin")
+				.contains("ADMIN")
+				.contains("USER")
+				.doesNotContain("ROLE_");
+	}
+	// end::custom-authorities[]
+
+	@EnableMethodSecurity(prePostEnabled = true, jsr250Enabled = true)
+	@Configuration
+	static class Config {
+
+		@Bean
+		MessageService messageService() {
+			return new HelloMessageService();
+		}
+	}
+}

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodwithsecuritycontext/CustomUserDetails.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodwithsecuritycontext;
+
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.authority.AuthorityUtils;
+import org.springframework.security.core.userdetails.UserDetails;
+
+import java.util.Collection;
+
+public class CustomUserDetails implements UserDetails {
+
+	private final String name;
+
+	private final String username;
+
+	private final Collection<? extends GrantedAuthority> authorities;
+
+	public CustomUserDetails(String name, String username) {
+		this.name = name;
+		this.username = username;
+		this.authorities = AuthorityUtils.createAuthorityList("ROLE_USER");
+	}
+
+	@Override
+	public Collection<? extends GrantedAuthority> getAuthorities() {
+		return this.authorities;
+	}
+
+	@Override
+	public String getPassword() {
+		return null;
+	}
+
+	@Override
+	public String getUsername() {
+		return this.username;
+	}
+
+	@Override
+	public String toString() {
+		return "CustomUserDetails{" + "username='" + this.username + '\'' + '}';
+	}
+
+}

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodwithsecuritycontext/WithMockCustomUser.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodwithsecuritycontext;
+
+import org.springframework.security.test.context.support.WithSecurityContext;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+// tag::snippet[]
+@Retention(RetentionPolicy.RUNTIME)
+@WithSecurityContext(factory = WithMockCustomUserSecurityContextFactory.class)
+public @interface WithMockCustomUser {
+
+	String username() default "rob";
+
+	String name() default "Rob Winch";
+}
+// end::snippet[]

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodwithsecuritycontext/WithMockCustomUserSecurityContextFactory.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodwithsecuritycontext;
+
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.context.SecurityContext;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.test.context.support.WithSecurityContextFactory;
+
+// tag::snippet[]
+public class WithMockCustomUserSecurityContextFactory
+		implements WithSecurityContextFactory<WithMockCustomUser> {
+
+	@Override
+	public SecurityContext createSecurityContext(WithMockCustomUser customUser) {
+		SecurityContext context = SecurityContextHolder.createEmptyContext();
+		CustomUserDetails principal = new CustomUserDetails(customUser.name(), customUser.username());
+		Authentication auth = UsernamePasswordAuthenticationToken.authenticated(principal, "password",
+				principal.getAuthorities());
+		context.setAuthentication(auth);
+		return context;
+	}
+
+}
+// end::snippet[]

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodwithsecuritycontext/WithUserDetailsSecurityContextFactory.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodwithsecuritycontext;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.context.SecurityContext;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.test.context.support.WithSecurityContextFactory;
+import org.springframework.security.test.context.support.WithUserDetails;
+import org.springframework.util.Assert;
+
+// tag::snippet[]
+final class WithUserDetailsSecurityContextFactory
+		implements WithSecurityContextFactory<WithUserDetails> {
+
+	private final UserDetailsService userDetailsService;
+
+	@Autowired
+	public WithUserDetailsSecurityContextFactory(UserDetailsService userDetailsService) {
+		this.userDetailsService = userDetailsService;
+	}
+
+	public SecurityContext createSecurityContext(WithUserDetails withUser) {
+		String username = withUser.value();
+		Assert.hasLength(username, "value() must be non-empty String");
+		UserDetails principal = userDetailsService.loadUserByUsername(username);
+		Authentication authentication = UsernamePasswordAuthenticationToken.authenticated(principal, principal.getPassword(), principal.getAuthorities());
+		SecurityContext context = SecurityContextHolder.createEmptyContext();
+		context.setAuthentication(authentication);
+		return context;
+	}
+}
+// end::snippet[]

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodwithuserdetails/WithCustomUserDetailsTests.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodwithuserdetails;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.config.core.MessageService;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.core.userdetails.UsernameNotFoundException;
+import org.springframework.security.docs.servlet.test.testmethod.HelloMessageService;
+import org.springframework.security.docs.servlet.test.testmethodwithsecuritycontext.CustomUserDetails;
+import org.springframework.security.test.context.support.WithUserDetails;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration
+class WithCustomUserDetailsTests {
+
+	@Autowired
+	MessageService messageService;
+
+	// tag::custom-user-details-service[]
+	@Test
+	@WithUserDetails(value="customUsername", userDetailsServiceBeanName="myUserDetailsService")
+	void getMessageWithUserDetailsServiceBeanName() {
+		String message = messageService.getMessage();
+		assertThat(message).contains("customUsername");
+		Object principal = SecurityContextHolder.getContext().getAuthentication().getPrincipal();
+		assertThat(principal).isInstanceOf(CustomUserDetails.class);
+	}
+	// end::custom-user-details-service[]
+
+	@EnableWebSecurity
+	@Configuration
+	static class Config {
+
+		@Bean
+		UserDetailsService myUserDetailsService() {
+			return new CustomUserDetailsService();
+		}
+
+		@Bean
+		MessageService messageService() {
+			return new HelloMessageService();
+		}
+	}
+
+	static class CustomUserDetailsService implements UserDetailsService {
+
+		@Override
+		public UserDetails loadUserByUsername(final String username) throws UsernameNotFoundException {
+			return new CustomUserDetails("name", username);
+		}
+	}
+
+}

docs/src/test/java/org/springframework/security/docs/servlet/test/testmethodwithuserdetails/WithUserDetailsTests.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.test.testmethodwithuserdetails;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.config.core.MessageService;
+import org.springframework.security.core.userdetails.User;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.docs.servlet.test.testmethod.HelloMessageService;
+import org.springframework.security.provisioning.InMemoryUserDetailsManager;
+import org.springframework.security.test.context.support.WithUserDetails;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@ExtendWith(SpringExtension.class)
+@ContextConfiguration
+class WithUserDetailsTests {
+
+	@Autowired
+	MessageService messageService;
+
+	// tag::user-details[]
+	@Test
+	@WithUserDetails
+	void getMessageWithUserDetails() {
+		String message = messageService.getMessage();
+		assertThat(message).contains("user");
+	}
+	// end::user-details[]
+
+	// tag::user-details-custom-username[]
+	@Test
+	@WithUserDetails("customUsername")
+	void getMessageWithUserDetailsCustomUsername() {
+		String message = messageService.getMessage();
+		assertThat(message).contains("customUsername");
+	}
+	// end::user-details-custom-username[]
+
+	@EnableWebSecurity
+	@Configuration
+	static class Config {
+
+		@Bean
+		UserDetailsService userDetailsService() {
+			UserDetails user1 = User.withDefaultPasswordEncoder()
+					.username("user")
+					.password("password")
+					.build();
+			UserDetails customUser = User.withDefaultPasswordEncoder()
+					.username("customUsername")
+					.password("password")
+					.build();
+			return new InMemoryUserDetailsManager(user1, customUser);
+		}
+
+		@Bean
+		MessageService messageService() {
+			return new HelloMessageService();
+		}
+	}
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethod/HelloMessageService.kt

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethod
+
+import org.springframework.security.access.prepost.PreAuthorize
+import org.springframework.security.config.core.MessageService
+import org.springframework.security.core.Authentication
+import org.springframework.security.core.context.SecurityContextHolder
+
+/**
+ * A message service for demonstrating test support for method-based security.
+ */
+// tag::authenticated[]
+class HelloMessageService : MessageService {
+
+	@PreAuthorize("isAuthenticated()")
+	override fun getMessage(): String {
+		val authentication: Authentication = SecurityContextHolder.getContext().authentication
+		return "Hello $authentication"
+	}
+
+	@PreAuthorize("isAuthenticated()")
+	override fun getJsrMessage(): String {
+		val authentication = SecurityContextHolder.getContext().authentication
+		return "Hello JSR $authentication"
+	}
+}
+// end::authenticated[]

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethod/HelloServiceTests.kt

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethod
+
+import org.assertj.core.api.Assertions
+import org.junit.jupiter.api.BeforeEach
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
+import org.springframework.security.config.core.MessageService
+import org.springframework.security.core.authority.AuthorityUtils
+import org.springframework.security.core.context.SecurityContextHolder
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+@ExtendWith(SpringExtension::class)
+@ContextConfiguration
+class HelloServiceTests {
+
+    @Autowired
+    lateinit var messageService: MessageService
+
+    @BeforeEach
+    fun setup() {
+        val user = UsernamePasswordAuthenticationToken.authenticated(
+            "user",
+            "password",
+            AuthorityUtils.createAuthorityList("ROLE_USER")
+        )
+        SecurityContextHolder.getContext().authentication = user
+    }
+
+    @Test
+    fun helloServiceTest() {
+        Assertions.assertThat(messageService.message)
+            .contains("user")
+            .contains("ROLE_USER")
+    }
+
+    @EnableMethodSecurity(prePostEnabled = true, jsr250Enabled = true)
+    @Configuration
+    open class Config {
+        @Bean
+        open fun messageService(): MessageService {
+            return HelloMessageService()
+        }
+    }
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodmetaannotations/WithMockAdmin.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodmetaannotations
+
+import org.springframework.security.test.context.support.WithMockUser
+
+// tag::snippet[]
+@Retention(AnnotationRetention.RUNTIME)
+@WithMockUser(value = "rob", roles = ["USER", "ADMIN"])
+annotation class WithMockAdmin
+// end::snippet[]

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodmetaannotations/WithMockAdminTests.kt

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodmetaannotations
+
+import org.assertj.core.api.Assertions
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
+import org.springframework.security.config.core.MessageService
+import org.springframework.security.kt.docs.servlet.test.testmethod.HelloMessageService
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+@ExtendWith(SpringExtension::class)
+@ContextConfiguration
+class WithMockAdminTests {
+
+    @Autowired
+    lateinit var messageService: MessageService
+
+    @Test
+    @WithMockAdmin
+    fun getMessageWithMockUserAdminRoles() {
+        val message = messageService.message
+        Assertions.assertThat(message)
+            .contains("rob")
+            .contains("ROLE_ADMIN")
+            .contains("ROLE_USER")
+    }
+
+    @EnableMethodSecurity(prePostEnabled = true, jsr250Enabled = true)
+    @Configuration
+    open class Config {
+        @Bean
+        open fun messageService(): MessageService {
+            return HelloMessageService()
+        }
+    }
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodmetaannotations/WithMockUserTests.kt

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodmetaannotations
+
+import org.assertj.core.api.Assertions
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
+import org.springframework.security.config.core.MessageService
+import org.springframework.security.kt.docs.servlet.test.testmethod.HelloMessageService
+import org.springframework.security.test.context.support.WithMockUser
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+@ExtendWith(SpringExtension::class)
+@ContextConfiguration
+class WithMockUserTests {
+
+    @Autowired
+    lateinit var messageService: MessageService
+
+    @Test
+    // tag::snippet[]
+    @WithMockUser(username = "admin", roles = ["USER", "ADMIN"])
+    // end::snippet[]
+    fun getMessageWithMockUserAdminRoles() {
+        val message = messageService.message
+        Assertions.assertThat(message)
+            .contains("admin")
+            .contains("ROLE_ADMIN")
+            .contains("ROLE_USER")
+    }
+
+    @EnableMethodSecurity
+    @Configuration
+    open class Config {
+        @Bean
+        open fun messageService(): MessageService {
+            return HelloMessageService()
+        }
+    }
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodsetup/WithMockUserSampleTests.kt

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodsetup
+
+import org.assertj.core.api.Assertions
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import org.springframework.security.authentication.AuthenticationCredentialsNotFoundException
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
+import org.springframework.security.config.core.MessageService
+import org.springframework.security.kt.docs.servlet.test.testmethod.HelloMessageService
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+@ExtendWith(SpringExtension::class)
+@ContextConfiguration
+class WithMockUserSampleTests {
+
+	@Autowired
+	lateinit var messageService: MessageService
+
+	// tag::snippet[]
+	@Test
+	fun getMessageUnauthenticated() {
+		Assertions.assertThatExceptionOfType(AuthenticationCredentialsNotFoundException::class.java)
+			.isThrownBy { messageService.getMessage() }
+	}
+	// end::snippet[]
+
+	@EnableMethodSecurity(prePostEnabled = true, jsr250Enabled = true)
+	@Configuration
+	open class Config {
+		@Bean
+		open fun messageService(): MessageService {
+			return HelloMessageService()
+		}
+	}
+
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodsetup/WithMockUserTests.kt

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodsetup
+
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+// tag::setup[]
+@ExtendWith(SpringExtension::class) // <1>
+@ContextConfiguration // <2>
+class WithMockUserTests {
+}
+// end::setup[]

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodwithanonymoususer/WithUserClassLevelAuthenticationTests.kt

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodwithanonymoususer
+
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.security.test.context.support.WithAnonymousUser
+import org.springframework.security.test.context.support.WithMockUser
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+
+// tag::snippet[]
+@ExtendWith(SpringExtension::class)
+@WithMockUser
+class WithUserClassLevelAuthenticationTests {
+
+	@Test
+	fun withMockUser1() {
+	}
+
+	@Test
+	fun withMockUser2() {
+	}
+
+	@Test
+	@WithAnonymousUser
+	@Throws(Exception::class)
+	fun anonymous() {
+		// override default to run as anonymous user
+	}
+
+}
+// end::snippet[]

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodwithmockuser/WithMockUserClassTests.kt

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodwithmockuser
+
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.security.test.context.support.WithMockUser
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+// tag::snippet[]
+@ExtendWith(SpringExtension::class)
+@ContextConfiguration
+@WithMockUser(username = "admin", roles = ["USER", "ADMIN"])
+class WithMockUserClassTests {
+	// ...
+}
+// end::snippet[]

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodwithmockuser/WithMockUserNestedTests.kt

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodwithmockuser
+
+import org.junit.jupiter.api.Nested
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.security.test.context.support.WithMockUser
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+// tag::snippet[]
+@ExtendWith(SpringExtension::class)
+@ContextConfiguration
+@WithMockUser(username = "admin", roles = ["USER", "ADMIN"])
+class WithMockUserNestedTests {
+
+	@Nested
+	inner class TestSuite1 {
+		// ... all test methods use admin user
+	}
+
+	@Nested
+	inner class TestSuite2 {
+		// ... all test methods use admin user
+	}
+
+}
+// end::snippet[]

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodwithmockuser/WithMockUserTests.kt

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodwithmockuser
+
+import org.assertj.core.api.Assertions
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
+import org.springframework.security.config.core.MessageService
+import org.springframework.security.kt.docs.servlet.test.testmethod.HelloMessageService
+import org.springframework.security.test.context.support.WithMockUser
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+@ExtendWith(SpringExtension::class)
+@ContextConfiguration
+class WithMockUserTests {
+
+    @Autowired
+    lateinit var messageService: MessageService
+
+    // tag::mock-user[]
+    @Test
+    @WithMockUser
+    fun getMessageWithMockUser() {
+        val message = messageService.message
+        Assertions.assertThat(message).contains("user")
+    }
+    // end::mock-user[]
+
+    // tag::custom-user[]
+    @Test
+    @WithMockUser("customUser")
+    fun getMessageWithMockUserCustomUsername() {
+        val message = messageService.message
+        Assertions.assertThat(message).contains("customUser")
+    }
+    // end::custom-user[]
+
+    // tag::custom-roles[]
+    @Test
+    @WithMockUser(username = "admin", roles = ["USER", "ADMIN"])
+    fun getMessageWithMockUserCustomRoles() {
+        val message = messageService.message
+        Assertions.assertThat(message)
+            .contains("admin")
+            .contains("ROLE_ADMIN")
+            .contains("ROLE_USER")
+    }
+    // end::custom-roles[]
+
+    // tag::custom-authorities[]
+    @Test
+    @WithMockUser(username = "admin", authorities = ["ADMIN", "USER"])
+    fun getMessageWithMockUserCustomAuthorities() {
+        val message = messageService.message
+        Assertions.assertThat(message)
+            .contains("admin")
+            .contains("ADMIN")
+            .contains("USER")
+            .doesNotContain("ROLE_")
+    }
+    // end::custom-authorities[]
+
+    @EnableMethodSecurity(prePostEnabled = true, jsr250Enabled = true)
+    @Configuration
+    open class Config {
+        @Bean
+        open fun messageService(): MessageService {
+            return HelloMessageService()
+        }
+    }
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodwithsecuritycontext/CustomUserDetails.kt

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodwithsecuritycontext
+
+import org.springframework.security.core.GrantedAuthority
+import org.springframework.security.core.authority.AuthorityUtils
+import org.springframework.security.core.userdetails.UserDetails
+
+class CustomUserDetails(
+    name: String,
+    username: String,
+    authorities: MutableCollection<GrantedAuthority> = AuthorityUtils.createAuthorityList("ROLE_USER")) : UserDetails {
+
+    override fun getAuthorities(): MutableCollection<out GrantedAuthority> {
+        return authorities
+    }
+
+    override fun getPassword(): String {
+        TODO("Not yet implemented")
+    }
+
+    override fun getUsername(): String {
+        return username
+    }
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodwithsecuritycontext/WithMockCustomUser.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodwithsecuritycontext
+
+import org.springframework.security.test.context.support.WithSecurityContext
+
+// tag::snippet[]
+@Retention(AnnotationRetention.RUNTIME)
+@WithSecurityContext(factory = WithMockCustomUserSecurityContextFactory::class)
+annotation class WithMockCustomUser(val username: String = "rob", val name: String = "Rob Winch")
+// end::snippet[]

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodwithsecuritycontext/WithMockCustomUserSecurityContextFactory.kt

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodwithsecuritycontext;
+
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
+import org.springframework.security.core.Authentication
+import org.springframework.security.core.context.SecurityContext
+import org.springframework.security.core.context.SecurityContextHolder
+import org.springframework.security.test.context.support.WithSecurityContextFactory
+
+// tag::snippet[]
+class WithMockCustomUserSecurityContextFactory : WithSecurityContextFactory<WithMockCustomUser> {
+	override fun createSecurityContext(customUser: WithMockCustomUser): SecurityContext {
+		val context = SecurityContextHolder.createEmptyContext()
+		val principal = CustomUserDetails(customUser.name, customUser.username)
+		val auth: Authentication =
+				UsernamePasswordAuthenticationToken(principal, "password", principal.authorities)
+		context.authentication = auth
+		return context
+	}
+}
+// end::snippet[]

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodwithsecuritycontext/WithUserDetailsSecurityContextFactory.kt

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodwithsecuritycontext
+
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
+import org.springframework.security.core.Authentication
+import org.springframework.security.core.context.SecurityContext
+import org.springframework.security.core.context.SecurityContextHolder
+import org.springframework.security.core.userdetails.UserDetailsService
+import org.springframework.security.test.context.support.WithSecurityContextFactory
+import org.springframework.security.test.context.support.WithUserDetails
+import org.springframework.util.Assert
+
+// tag::snippet[]
+class WithUserDetailsSecurityContextFactory @Autowired constructor(private val userDetailsService: UserDetailsService) :
+    WithSecurityContextFactory<WithUserDetails> {
+
+    override fun createSecurityContext(withUser: WithUserDetails): SecurityContext {
+        val username: String = withUser.value
+        Assert.hasLength(username, "value() must be non-empty String")
+        val principal = userDetailsService.loadUserByUsername(username)
+        val authentication: Authentication =
+            UsernamePasswordAuthenticationToken(principal, principal.password, principal.authorities)
+        val context = SecurityContextHolder.createEmptyContext()
+        context.authentication = authentication
+        return context
+    }
+
+}
+// end::snippet[]

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodwithuserdetails/WithCustomUserDetailsTests.kt

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodwithuserdetails
+
+import org.assertj.core.api.Assertions
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
+import org.springframework.security.config.core.MessageService
+import org.springframework.security.core.context.SecurityContextHolder
+import org.springframework.security.core.userdetails.UserDetails
+import org.springframework.security.core.userdetails.UserDetailsService
+import org.springframework.security.core.userdetails.UsernameNotFoundException
+import org.springframework.security.docs.servlet.test.testmethodwithsecuritycontext.CustomUserDetails
+import org.springframework.security.kt.docs.servlet.test.testmethod.HelloMessageService
+import org.springframework.security.test.context.support.WithUserDetails
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+@ExtendWith(SpringExtension::class)
+@ContextConfiguration
+class WithCustomUserDetailsTests {
+
+    @Autowired
+    lateinit var messageService: MessageService
+
+    // tag::custom-user-details-service[]
+    @Test
+    @WithUserDetails(value = "customUsername", userDetailsServiceBeanName = "myUserDetailsService")
+    fun getMessageWithUserDetailsServiceBeanName() {
+        val message: String = messageService.getMessage()
+        Assertions.assertThat(message).contains("customUsername");
+        val principal = SecurityContextHolder.getContext().authentication.principal
+        Assertions.assertThat(principal).isInstanceOf(CustomUserDetails::class.java)
+    }
+    // end::custom-user-details-service[]
+
+    @EnableMethodSecurity
+    @Configuration
+    open class Config {
+
+        @Bean
+        open fun myUserDetailsService(): UserDetailsService {
+            return CustomUserDetailsService()
+        }
+
+        @Bean
+        open fun messageService(): MessageService {
+            return HelloMessageService()
+        }
+    }
+
+    open class CustomUserDetailsService : UserDetailsService {
+
+        @Throws(UsernameNotFoundException::class)
+        override fun loadUserByUsername(username: String): UserDetails {
+            return CustomUserDetails("name", username)
+        }
+    }
+
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/test/testmethodwithuserdetails/WithUserDetailsTests.kt

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2002-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.kt.docs.servlet.test.testmethodwithuserdetails
+
+import org.assertj.core.api.Assertions
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity
+import org.springframework.security.config.core.MessageService
+import org.springframework.security.core.userdetails.User
+import org.springframework.security.core.userdetails.UserDetailsService
+import org.springframework.security.kt.docs.servlet.test.testmethod.HelloMessageService
+import org.springframework.security.provisioning.InMemoryUserDetailsManager
+import org.springframework.security.test.context.support.WithUserDetails
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.test.context.junit.jupiter.SpringExtension
+
+@ExtendWith(SpringExtension::class)
+@ContextConfiguration
+class WithUserDetailsTests {
+
+    @Autowired
+    lateinit var messageService: MessageService
+
+    // tag::user-details[]
+    @Test
+    @WithUserDetails
+    fun getMessageWithUserDetails() {
+        val message: String = messageService.message
+        Assertions.assertThat(message).contains("user")
+    }
+    // end::user-details[]
+
+    // tag::user-details-custom-username[]
+    @Test
+    @WithUserDetails("customUsername")
+    fun getMessageWithUserDetailsCustomUsername() {
+        val message: String = messageService.message
+        Assertions.assertThat(message).contains("customUsername")
+    }
+    // end::user-details-custom-username[]
+
+    @EnableMethodSecurity
+    @Configuration
+    open class Config {
+
+        @Bean
+        open fun userDetailsService(): UserDetailsService {
+            val user1 = User.withDefaultPasswordEncoder()
+                .username("user")
+                .password("password")
+                .build();
+            val customUser = User.withDefaultPasswordEncoder()
+                .username("customUsername")
+                .password("password")
+                .build();
+            return InMemoryUserDetailsManager(user1, customUser);
+        }
+
+        @Bean
+        open fun messageService(): MessageService {
+            return HelloMessageService()
+        }
+    }
+}