Update servlet test method docs to use include-code

References gh-16226

Signed-off-by: Joe Kuhel <[email protected]>

Author: jkuhel

docs/modules/ROOT/pages/servlet/test/method.adoc

@@ -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/HelloMessageService.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/testmethod/HelloServiceTests.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/WithMockAdmin.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/WithMockAdminTests.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/testmethodmetaannotations/WithMockUserTests.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/WithMockUserSampleTests.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/testmethodsetup/WithMockUserTests.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[]