Propagate TestSecurityContextHolder to SecurityContextHolder

Create SecurityMockMvcResultHandlers to define security related MockMvc ResultHandlers
Create a method to allow copying the SecurityContext from the TestSecurityContextHolder to SecurityContextHolder

Closes gh-9565

docs/manual/src/docs/asciidoc/_includes/servlet/test/mockmvc.adoc

@@ -1889,3 +1889,65 @@ mvc
     }
 ----
 ====
+
+=== SecurityMockMvcResultHandlers
+
+Spring Security provides a few ``ResultHandler``s implementations.
+In order to use Spring Security's ``ResultHandler``s implementations ensure the following static import is used:
+
+[source,java]
+----
+import static org.springframework.security.test.web.servlet.response.SecurityMockMvcResultHandlers.*;
+----
+
+==== Exporting the SecurityContext
+
+Often times we want to query a repository to see if some `MockMvc` request actually persisted in the database.
+In some cases our repository query uses the <<data,Spring Data Integration>> to filter the results based on current user's username or any other property.
+Let's see an example:
+
+A repository interface:
+[source,java]
+----
+private interface MessageRepository extends JpaRepository<Message, Long> {
+	@Query("SELECT m.content FROM Message m WHERE m.sentBy = ?#{ principal?.name }")
+	List<String> findAllUserMessages();
+}
+----
+
+Our test scenario:
+
+[source,java]
+----
+mvc
+	.perform(post("/message")
+		.content("New Message")
+		.contentType(MediaType.TEXT_PLAIN)
+	)
+	.andExpect(status().isOk());
+
+List<String> userMessages = messageRepository.findAllUserMessages();
+assertThat(userMessages).hasSize(1);
+----
+
+This test won't pass because after our request finishes, the `SecurityContextHolder` will be cleared out by the filter chain.
+We can then export the `TestSecurityContextHolder` to our `SecurityContextHolder` and use it as we want:
+
+[source,java]
+----
+mvc
+	.perform(post("/message")
+		.content("New Message")
+		.contentType(MediaType.TEXT_PLAIN)
+	)
+	.andDo(exportTestSecurityContext())
+	.andExpect(status().isOk());
+
+List<String> userMessages = messageRepository.findAllUserMessages();
+assertThat(userMessages).hasSize(1);
+----
+
+[NOTE]
+====
+Remember to clear the `SecurityContextHolder` between your tests, or it may leak amongst them
+====