From 4eebbcf5fbe910630d5297f1be1a3c98a8b4e7df Mon Sep 17 00:00:00 2001
From: Rob Ede <robjtede@icloud.com>
Date: Tue, 14 Dec 2021 23:37:17 +0000
Subject: [PATCH] renam test util calls and deprecate old names

---
 src/test/test_utils.rs | 35 ++++++++++++++++++++++++++++++++---
 src/types/either.rs    |  2 --
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/src/test/test_utils.rs b/src/test/test_utils.rs
index 111a4dc61..e7f488edd 100644
--- a/src/test/test_utils.rs
+++ b/src/test/test_utils.rs
@@ -15,6 +15,7 @@ use crate::{
 
 /// Initialize service from application builder instance.
 ///
+/// # Examples
 /// ```
 /// use actix_service::Service;
 /// use actix_web::{test, web, App, HttpResponse, http::StatusCode};
@@ -65,6 +66,7 @@ where
 
 /// Calls service and waits for response future completion.
 ///
+/// # Examples
 /// ```
 /// use actix_web::{test, web, App, HttpResponse, http::StatusCode};
 ///
@@ -100,6 +102,7 @@ where
 
 /// Helper function that returns a response body of a TestRequest
 ///
+/// # Examples
 /// ```
 /// use actix_web::{test, web, App, HttpResponse, http::header};
 /// use bytes::Bytes;
@@ -119,7 +122,7 @@ where
 ///         .header(header::CONTENT_TYPE, "application/json")
 ///         .to_request();
 ///
-///     let result = test::read_response(&app, req).await;
+///     let result = test::call_and_read_body(&app, req).await;
 ///     assert_eq!(result, Bytes::from_static(b"welcome!"));
 /// }
 /// ```
@@ -128,6 +131,18 @@ where
 /// Panics if:
 /// - service call returns error;
 /// - body yields an error while it is being read.
+pub async fn call_and_read_body<S, B>(app: &S, req: Request) -> Bytes
+where
+    S: Service<Request, Response = ServiceResponse<B>, Error = Error>,
+    B: MessageBody,
+    B::Error: fmt::Debug,
+{
+    let res = call_service(app, req).await;
+    read_body(res).await
+}
+
+#[doc(hidden)]
+#[deprecated(since = "4.0.0", note = "Renamed to `call_and_read_body`.")]
 pub async fn read_response<S, B>(app: &S, req: Request) -> Bytes
 where
     S: Service<Request, Response = ServiceResponse<B>, Error = Error>,
@@ -181,6 +196,7 @@ where
 
 /// Helper function that returns a deserialized response body of a ServiceResponse.
 ///
+/// # Examples
 /// ```
 /// use actix_web::{App, test, web, HttpResponse, http::header};
 /// use serde::{Serialize, Deserialize};
@@ -241,6 +257,7 @@ where
 
 /// Helper function that returns a deserialized response body of a TestRequest
 ///
+/// # Examples
 /// ```
 /// use actix_web::{App, test, web, HttpResponse, http::header};
 /// use serde::{Serialize, Deserialize};
@@ -270,7 +287,7 @@ where
 ///         .set_payload(payload)
 ///         .to_request();
 ///
-///     let result: Person = test::read_response_json(&mut app, req).await;
+///     let result: Person = test::call_and_read_body_json(&mut app, req).await;
 /// }
 /// ```
 ///
@@ -279,7 +296,7 @@ where
 /// - service call returns an error body yields an error while it is being read;
 /// - body yields an error while it is being read;
 /// - received body is not a valid JSON representation of `T`.
-pub async fn read_response_json<S, B, T>(app: &S, req: Request) -> T
+pub async fn call_and_read_body_json<S, B, T>(app: &S, req: Request) -> T
 where
     S: Service<Request, Response = ServiceResponse<B>, Error = Error>,
     B: MessageBody,
@@ -290,6 +307,18 @@ where
     read_body_json(res).await
 }
 
+#[doc(hidden)]
+#[deprecated(since = "4.0.0", note = "Renamed to `call_and_read_body_json`.")]
+pub async fn read_response_json<S, B, T>(app: &S, req: Request) -> T
+where
+    S: Service<Request, Response = ServiceResponse<B>, Error = Error>,
+    B: MessageBody,
+    B::Error: fmt::Debug,
+    T: DeserializeOwned,
+{
+    call_and_read_body_json(app, req).await
+}
+
 #[cfg(test)]
 mod tests {
 
diff --git a/src/types/either.rs b/src/types/either.rs
index 5b8e02525..0eafb9e43 100644
--- a/src/types/either.rs
+++ b/src/types/either.rs
@@ -20,8 +20,6 @@ use crate::{
 
 /// Combines two extractor or responder types into a single type.
 ///
-/// Can be converted to and from an [`either::Either`].
-///
 /// # Extractor
 /// Provides a mechanism for trying two extractors, a primary and a fallback. Useful for
 /// "polymorphic payloads" where, for example, a form might be JSON or URL encoded.