From c5a95791932209db34ed0556e91ac0033877366c Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Sun, 10 Sep 2023 02:56:48 +0100 Subject: [PATCH] update testing docs to give less precedence to unit testing --- docs/errors.md | 4 ++-- docs/handlers.md | 2 +- docs/testing.md | 18 ++++++++++-------- docs/welcome.md | 2 +- examples/testing/src/integration_one.rs | 9 +++++---- examples/testing/src/integration_two.rs | 5 +++-- 6 files changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/errors.md b/docs/errors.md index 5357b98..be0d6ea 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -8,7 +8,7 @@ import CodeBlock from "@site/src/components/code_block.js"; Actix Web uses its own [`actix_web::error::Error`][actixerror] type and [`actix_web::error::ResponseError`][responseerror] trait for error handling from web handlers. -If a handler returns an `Error` (referring to the [general Rust trait `std::error::Error`][stderror]) in a `Result` that also implements the `ResponseError` trait, actix-web will render that error as an HTTP response with its corresponding [`actix_web::http::StatusCode`][status_code]. An internal server error is generated by default: +If a handler returns an `Error` (referring to the [general Rust trait `std::error::Error`][stderror]) in a `Result` that also implements the `ResponseError` trait, Actix Web will render that error as an HTTP response with its corresponding [`actix_web::http::StatusCode`][status_code]. An internal server error is generated by default: ```rust pub trait ResponseError { @@ -36,7 +36,7 @@ fn index(_req: HttpRequest) -> io::Result { } ``` -See [the actix-web API documentation][responseerrorimpls] for a full list of foreign implementations for `ResponseError`. +See [the Actix Web API documentation][responseerrorimpls] for a full list of foreign implementations for `ResponseError`. ## An example of a custom error response diff --git a/docs/handlers.md b/docs/handlers.md index ce39466..3bcab23 100644 --- a/docs/handlers.md +++ b/docs/handlers.md @@ -10,7 +10,7 @@ A request handler is an async function that accepts zero or more parameters that Request handling happens in two stages. First the handler object is called, returning any object that implements the [_Responder_][respondertrait] trait. Then, `respond_to()` is called on the returned object, converting itself to a `HttpResponse` or `Error`. -By default actix-web provides `Responder` implementations for some standard types, such as `&'static str`, `String`, etc. +By default Actix Web provides `Responder` implementations for some standard types, such as `&'static str`, `String`, etc. > For a complete list of implementations, check the [_Responder documentation_][responderimpls]. diff --git a/docs/testing.md b/docs/testing.md index 9dd5c80..fb7627f 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -6,15 +6,11 @@ import CodeBlock from "@site/src/components/code_block.js"; # Testing -Every application should be well tested. Actix Web provides tools to perform unit and integration tests. +Every application should be well tested. Actix Web provides tools to perform integration tests against your applications and unit test tools for custom extractors and middleware. -## Unit Tests +Actix Web provides a request builder type. [_TestRequest_][testrequest] implements a builder-like pattern. You can generate a `HttpRequest` instance with `to_http_request()` and call your handlers or extractors with it. Also see -For unit testing, actix-web provides a request builder type. [_TestRequest_][testrequest] implements a builder-like pattern. You can generate a `HttpRequest` instance with `to_http_request()` and call your handler with it. - - - -## Integration tests +## Integration Testing For Applications There are a few methods for testing your application. Actix Web can be used to run the application with specific handlers in a real HTTP server. @@ -30,12 +26,18 @@ If you need more complex application configuration, testing should be very simil -## Stream response tests +## Stream Response Testing If you need to test stream generation, it would be enough to call [`into_parts()`][resintoparts] and convert the resulting body into a future and execute it, for example when testing [_Server Sent Events_][serversentevents]. +## Unit Testing Extractors + +Unit testing has pretty limited value for applications, but can be useful when developing extractors, middleware, and responders. Given that, calling directly into handler functions **which are defined stand-alone, without using routing macros** (like `#[get("/")]`) is possible if you want to make assertions on custom `Responder`s. + + + [serversentevents]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events [resintoparts]: https://docs.rs/actix-web/4/actix_web/struct.HttpResponse.html#method.into_parts [actixdocs]: https://docs.rs/actix-web/4/actix_web/test/index.html diff --git a/docs/welcome.md b/docs/welcome.md index 582ee90..8d7c68c 100644 --- a/docs/welcome.md +++ b/docs/welcome.md @@ -8,7 +8,7 @@ slug: / Actix Web lets you quickly and confidently develop web services in Rust and this guide will get you going in no time. -The documentation on this website focuses primarily on the Actix Web framework. For information about the actor framework called Actix, check out the [Actix chapter][actix-chapter] (or the lower level [actix API docs][actix-docs]). Otherwise, head on to the [getting started guide][getting-started]. If you already know your way around and you need specific information you might want to read the [actix-web API docs][actix-web-docs]. +The documentation on this website focuses primarily on the Actix Web framework. For information about the actor framework called Actix, check out the [Actix chapter][actix-chapter] (or the lower level [actix API docs][actix-docs]). Otherwise, head on to the [getting started guide][getting-started]. If you already know your way around and you need specific information you might want to read the [Actix Web API docs][actix-web-docs]. [getting-started]: https://actix.rs/docs/getting-started [actix-web-docs]: https://docs.rs/actix-web diff --git a/examples/testing/src/integration_one.rs b/examples/testing/src/integration_one.rs index 96d6289..3c63b34 100644 --- a/examples/testing/src/integration_one.rs +++ b/examples/testing/src/integration_one.rs @@ -1,6 +1,7 @@ -use actix_web::{HttpRequest, Responder}; +use actix_web::{get, HttpRequest, Responder}; #[allow(dead_code)] +#[get("/")] async fn index(_req: HttpRequest) -> impl Responder { "Hello world!" } @@ -8,13 +9,13 @@ async fn index(_req: HttpRequest) -> impl Responder { // #[cfg(test)] mod tests { - use actix_web::{http::header::ContentType, test, web, App}; + use actix_web::{http::header::ContentType, test, App}; use super::*; #[actix_web::test] async fn test_index_get() { - let app = test::init_service(App::new().route("/", web::get().to(index))).await; + let app = test::init_service(App::new().service(index)).await; let req = test::TestRequest::default() .insert_header(ContentType::plaintext()) .to_request(); @@ -24,7 +25,7 @@ mod tests { #[actix_web::test] async fn test_index_post() { - let app = test::init_service(App::new().route("/", web::get().to(index))).await; + let app = test::init_service(App::new().service(index)).await; let req = test::TestRequest::post().uri("/").to_request(); let resp = test::call_service(&app, req).await; assert!(resp.status().is_client_error()); diff --git a/examples/testing/src/integration_two.rs b/examples/testing/src/integration_two.rs index 7929b26..fd648c8 100644 --- a/examples/testing/src/integration_two.rs +++ b/examples/testing/src/integration_two.rs @@ -1,4 +1,4 @@ -use actix_web::{web, HttpResponse, Responder}; +use actix_web::{get, web, HttpResponse, Responder}; use serde::{Deserialize, Serialize}; #[derive(Deserialize, Serialize, Debug)] @@ -7,6 +7,7 @@ struct AppState { } #[allow(dead_code)] +#[get("/")] async fn index(data: web::Data) -> impl Responder { HttpResponse::Ok().json(data.get_ref()) } @@ -22,7 +23,7 @@ mod tests { let app = test::init_service( App::new() .app_data(web::Data::new(AppState { count: 4 })) - .route("/", web::get().to(index)), + .service(index), ) .await; let req = test::TestRequest::get().uri("/").to_request();