actix_web/test/
test_request.rs

1use std::{borrow::Cow, net::SocketAddr, rc::Rc};
2
3use actix_http::{test::TestRequest as HttpTestRequest, Request};
4use serde::Serialize;
5
6#[cfg(feature = "cookies")]
7use crate::cookie::{Cookie, CookieJar};
8use crate::{
9    app_service::AppInitServiceState,
10    config::AppConfig,
11    data::Data,
12    dev::{Extensions, Path, Payload, ResourceDef, Service, Url},
13    http::{
14        header::{ContentType, TryIntoHeaderPair},
15        Method, Uri, Version,
16    },
17    rmap::ResourceMap,
18    service::{ServiceRequest, ServiceResponse},
19    test,
20    web::Bytes,
21    HttpRequest, HttpResponse,
22};
23
24/// Test `Request` builder.
25///
26/// For unit testing, actix provides a request builder type and a simple handler runner. TestRequest implements a builder-like pattern.
27/// You can generate various types of request via TestRequest's methods:
28/// - [`TestRequest::to_request`] creates an [`actix_http::Request`](Request).
29/// - [`TestRequest::to_srv_request`] creates a [`ServiceRequest`], which is used for testing middlewares and chain adapters.
30/// - [`TestRequest::to_srv_response`] creates a [`ServiceResponse`].
31/// - [`TestRequest::to_http_request`] creates an [`HttpRequest`], which is used for testing handlers.
32///
33/// ```
34/// use actix_web::{test, HttpRequest, HttpResponse, HttpMessage};
35/// use actix_web::http::{header, StatusCode};
36///
37/// async fn handler(req: HttpRequest) -> HttpResponse {
38///     if let Some(hdr) = req.headers().get(header::CONTENT_TYPE) {
39///         HttpResponse::Ok().into()
40///     } else {
41///         HttpResponse::BadRequest().into()
42///     }
43/// }
44///
45/// #[actix_web::test]
46/// # // force rustdoc to display the correct thing and also compile check the test
47/// # async fn _test() {}
48/// async fn test_index() {
49///     let req = test::TestRequest::default()
50///         .insert_header(header::ContentType::plaintext())
51///         .to_http_request();
52///
53///     let resp = handler(req).await;
54///     assert_eq!(resp.status(), StatusCode::OK);
55///
56///     let req = test::TestRequest::default().to_http_request();
57///     let resp = handler(req).await;
58///     assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
59/// }
60/// ```
61pub struct TestRequest {
62    req: HttpTestRequest,
63    rmap: ResourceMap,
64    config: AppConfig,
65    path: Path<Url>,
66    peer_addr: Option<SocketAddr>,
67    app_data: Extensions,
68    #[cfg(feature = "cookies")]
69    cookies: CookieJar,
70}
71
72impl Default for TestRequest {
73    fn default() -> TestRequest {
74        TestRequest {
75            req: HttpTestRequest::default(),
76            rmap: ResourceMap::new(ResourceDef::new("")),
77            config: AppConfig::default(),
78            path: Path::new(Url::new(Uri::default())),
79            peer_addr: None,
80            app_data: Extensions::new(),
81            #[cfg(feature = "cookies")]
82            cookies: CookieJar::new(),
83        }
84    }
85}
86
87#[allow(clippy::wrong_self_convention)]
88impl TestRequest {
89    /// Constructs test request and sets request URI.
90    pub fn with_uri(uri: &str) -> TestRequest {
91        TestRequest::default().uri(uri)
92    }
93
94    /// Constructs test request with GET method.
95    pub fn get() -> TestRequest {
96        TestRequest::default().method(Method::GET)
97    }
98
99    /// Constructs test request with POST method.
100    pub fn post() -> TestRequest {
101        TestRequest::default().method(Method::POST)
102    }
103
104    /// Constructs test request with PUT method.
105    pub fn put() -> TestRequest {
106        TestRequest::default().method(Method::PUT)
107    }
108
109    /// Constructs test request with PATCH method.
110    pub fn patch() -> TestRequest {
111        TestRequest::default().method(Method::PATCH)
112    }
113
114    /// Constructs test request with QUERY method.
115    // TODO: use `Method::QUERY` once the `http` dependency is bumped (see #3384).
116    pub fn query() -> TestRequest {
117        TestRequest::default().method(Method::from_bytes(b"QUERY").unwrap())
118    }
119
120    /// Constructs test request with DELETE method.
121    pub fn delete() -> TestRequest {
122        TestRequest::default().method(Method::DELETE)
123    }
124
125    /// Sets HTTP version of this request.
126    pub fn version(mut self, ver: Version) -> Self {
127        self.req.version(ver);
128        self
129    }
130
131    /// Sets method of this request.
132    pub fn method(mut self, meth: Method) -> Self {
133        self.req.method(meth);
134        self
135    }
136
137    /// Sets URI of this request.
138    pub fn uri(mut self, path: &str) -> Self {
139        self.req.uri(path);
140        self
141    }
142
143    /// Inserts a header, replacing any that were set with an equivalent field name.
144    pub fn insert_header(mut self, header: impl TryIntoHeaderPair) -> Self {
145        self.req.insert_header(header);
146        self
147    }
148
149    /// Appends a header, keeping any that were set with an equivalent field name.
150    pub fn append_header(mut self, header: impl TryIntoHeaderPair) -> Self {
151        self.req.append_header(header);
152        self
153    }
154
155    /// Sets cookie for this request.
156    #[cfg(feature = "cookies")]
157    pub fn cookie(mut self, cookie: Cookie<'_>) -> Self {
158        self.cookies.add(cookie.into_owned());
159        self
160    }
161
162    /// Sets request path pattern parameter.
163    ///
164    /// # Examples
165    ///
166    /// ```
167    /// use actix_web::test::TestRequest;
168    ///
169    /// let req = TestRequest::default().param("foo", "bar");
170    /// let req = TestRequest::default().param("foo".to_owned(), "bar".to_owned());
171    /// ```
172    pub fn param(
173        mut self,
174        name: impl Into<Cow<'static, str>>,
175        value: impl Into<Cow<'static, str>>,
176    ) -> Self {
177        self.path.add_static(name, value);
178        self
179    }
180
181    /// Sets peer address.
182    pub fn peer_addr(mut self, addr: SocketAddr) -> Self {
183        self.peer_addr = Some(addr);
184        self
185    }
186
187    /// Sets request payload.
188    pub fn set_payload(mut self, data: impl Into<Bytes>) -> Self {
189        self.req.set_payload(data);
190        self
191    }
192
193    /// Serializes `data` to a URL encoded form and set it as the request payload.
194    ///
195    /// The `Content-Type` header is set to `application/x-www-form-urlencoded`.
196    pub fn set_form(mut self, data: impl Serialize) -> Self {
197        let bytes = serde_urlencoded::to_string(&data)
198            .expect("Failed to serialize test data as a urlencoded form");
199        self.req.set_payload(bytes);
200        self.req.insert_header(ContentType::form_url_encoded());
201        self
202    }
203
204    /// Serializes `data` to JSON and set it as the request payload.
205    ///
206    /// The `Content-Type` header is set to `application/json`.
207    pub fn set_json(mut self, data: impl Serialize) -> Self {
208        let bytes = serde_json::to_string(&data).expect("Failed to serialize test data to json");
209        self.req.set_payload(bytes);
210        self.req.insert_header(ContentType::json());
211        self
212    }
213
214    /// Inserts application data.
215    ///
216    /// This is equivalent of `App::app_data()` method for testing purpose.
217    pub fn app_data<T: 'static>(mut self, data: T) -> Self {
218        self.app_data.insert(data);
219        self
220    }
221
222    /// Inserts application data.
223    ///
224    /// This is equivalent of `App::data()` method for testing purpose.
225    #[doc(hidden)]
226    pub fn data<T: 'static>(mut self, data: T) -> Self {
227        self.app_data.insert(Data::new(data));
228        self
229    }
230
231    /// Sets resource map.
232    #[cfg(test)]
233    pub(crate) fn rmap(mut self, rmap: ResourceMap) -> Self {
234        self.rmap = rmap;
235        self
236    }
237
238    /// Finalizes test request.
239    ///
240    /// This request builder will be useless after calling `finish()`.
241    fn finish(&mut self) -> Request {
242        // mut used when cookie feature is enabled
243        #[allow(unused_mut)]
244        let mut req = self.req.finish();
245
246        #[cfg(feature = "cookies")]
247        {
248            use actix_http::header::{HeaderValue, COOKIE};
249
250            let cookie: String = self
251                .cookies
252                .delta()
253                // ensure only name=value is written to cookie header
254                .map(|c| c.stripped().encoded().to_string())
255                .collect::<Vec<_>>()
256                .join("; ");
257
258            if !cookie.is_empty() {
259                req.headers_mut()
260                    .insert(COOKIE, HeaderValue::from_str(&cookie).unwrap());
261            }
262        }
263
264        req
265    }
266
267    /// Finalizes request creation and returns `Request` instance.
268    pub fn to_request(mut self) -> Request {
269        let mut req = self.finish();
270        req.head_mut().peer_addr = self.peer_addr;
271        req
272    }
273
274    /// Finalizes request creation and returns `ServiceRequest` instance.
275    pub fn to_srv_request(mut self) -> ServiceRequest {
276        let (mut head, payload) = self.finish().into_parts();
277        head.peer_addr = self.peer_addr;
278        self.path.get_mut().update(&head.uri);
279
280        let app_state =
281            AppInitServiceState::new_without_pool(Rc::new(self.rmap), self.config.clone());
282
283        ServiceRequest::new(
284            HttpRequest::new(
285                self.path,
286                head,
287                app_state,
288                Rc::new(self.app_data),
289                None,
290                Default::default(),
291            ),
292            payload,
293        )
294    }
295
296    /// Finalizes request creation and returns `ServiceResponse` instance.
297    pub fn to_srv_response<B>(self, res: HttpResponse<B>) -> ServiceResponse<B> {
298        self.to_srv_request().into_response(res)
299    }
300
301    /// Finalizes request creation and returns `HttpRequest` instance.
302    pub fn to_http_request(mut self) -> HttpRequest {
303        let (mut head, _) = self.finish().into_parts();
304        head.peer_addr = self.peer_addr;
305        self.path.get_mut().update(&head.uri);
306
307        let app_state =
308            AppInitServiceState::new_without_pool(Rc::new(self.rmap), self.config.clone());
309
310        HttpRequest::new(
311            self.path,
312            head,
313            app_state,
314            Rc::new(self.app_data),
315            None,
316            Default::default(),
317        )
318    }
319
320    /// Finalizes request creation and returns `HttpRequest` and `Payload` pair.
321    pub fn to_http_parts(mut self) -> (HttpRequest, Payload) {
322        let (mut head, payload) = self.finish().into_parts();
323        head.peer_addr = self.peer_addr;
324        self.path.get_mut().update(&head.uri);
325
326        let app_state =
327            AppInitServiceState::new_without_pool(Rc::new(self.rmap), self.config.clone());
328
329        let req = HttpRequest::new(
330            self.path,
331            head,
332            app_state,
333            Rc::new(self.app_data),
334            None,
335            Default::default(),
336        );
337
338        (req, payload)
339    }
340
341    /// Finalizes request creation, calls service, and waits for response future completion.
342    pub async fn send_request<S, B, E>(self, app: &S) -> S::Response
343    where
344        S: Service<Request, Response = ServiceResponse<B>, Error = E>,
345        E: std::fmt::Debug,
346    {
347        let req = self.to_request();
348        test::call_service(app, req).await
349    }
350
351    #[cfg(test)]
352    pub fn set_server_hostname(&mut self, host: &str) {
353        self.config.set_host(host)
354    }
355}
356
357#[cfg(test)]
358mod tests {
359    use std::{sync::Arc, time::SystemTime};
360
361    use super::*;
362    use crate::{http::header, test::init_service, web, App, Error, Responder};
363
364    #[actix_rt::test]
365    async fn test_request_app_data_is_dropped() {
366        fn assert_dropped(make_request: impl FnOnce(TestRequest)) {
367            let data = Arc::new(());
368            let weak = Arc::downgrade(&data);
369            make_request(TestRequest::default().app_data(Data::new(data)));
370            assert!(weak.upgrade().is_none());
371        }
372
373        assert_dropped(|req| drop(req.to_srv_request()));
374        assert_dropped(|req| drop(req.to_http_request()));
375        assert_dropped(|req| drop(req.to_http_parts()));
376    }
377
378    #[actix_rt::test]
379    async fn test_basics() {
380        let req = TestRequest::default()
381            .version(Version::HTTP_2)
382            .insert_header(header::ContentType::json())
383            .insert_header(header::Date(SystemTime::now().into()))
384            .param("test", "123")
385            .data(10u32)
386            .app_data(20u64)
387            .peer_addr("127.0.0.1:8081".parse().unwrap())
388            .to_http_request();
389        assert!(req.headers().contains_key(header::CONTENT_TYPE));
390        assert!(req.headers().contains_key(header::DATE));
391        assert_eq!(
392            req.head().peer_addr,
393            Some("127.0.0.1:8081".parse().unwrap())
394        );
395        assert_eq!(&req.match_info()["test"], "123");
396        assert_eq!(req.version(), Version::HTTP_2);
397        let data = req.app_data::<Data<u32>>().unwrap();
398        assert!(req.app_data::<Data<u64>>().is_none());
399        assert_eq!(*data.get_ref(), 10);
400
401        assert!(req.app_data::<u32>().is_none());
402        let data = req.app_data::<u64>().unwrap();
403        assert_eq!(*data, 20);
404    }
405
406    #[actix_rt::test]
407    async fn test_send_request() {
408        let app = init_service(
409            App::new().service(
410                web::resource("/index.html")
411                    .route(web::get().to(|| HttpResponse::Ok().body("welcome!"))),
412            ),
413        )
414        .await;
415
416        let resp = TestRequest::get()
417            .uri("/index.html")
418            .send_request(&app)
419            .await;
420
421        let result = test::read_body(resp).await;
422        assert_eq!(result, Bytes::from_static(b"welcome!"));
423    }
424
425    #[actix_rt::test]
426    async fn test_async_with_block() {
427        async fn async_with_block() -> Result<HttpResponse, Error> {
428            let res = web::block(move || Some(4usize).ok_or("wrong")).await;
429
430            match res {
431                Ok(value) => Ok(HttpResponse::Ok()
432                    .content_type("text/plain")
433                    .body(format!("Async with block value: {:?}", value))),
434                Err(_) => panic!("Unexpected"),
435            }
436        }
437
438        let app =
439            init_service(App::new().service(web::resource("/index.html").to(async_with_block)))
440                .await;
441
442        let req = TestRequest::post().uri("/index.html").to_request();
443        let res = app.call(req).await.unwrap();
444        assert!(res.status().is_success());
445    }
446
447    // allow deprecated App::data
448    #[allow(deprecated)]
449    #[actix_rt::test]
450    async fn test_server_data() {
451        async fn handler(data: web::Data<usize>) -> impl Responder {
452            assert_eq!(**data, 10);
453            HttpResponse::Ok()
454        }
455
456        let app = init_service(
457            App::new()
458                .data(10usize)
459                .service(web::resource("/index.html").to(handler)),
460        )
461        .await;
462
463        let req = TestRequest::post().uri("/index.html").to_request();
464        let res = app.call(req).await.unwrap();
465        assert!(res.status().is_success());
466    }
467}
actix_web/test/test_request.rs

actix_web/test/
test_request.rs
