Struct trillium_testing::TestConn
source · pub struct TestConn(/* private fields */);
Expand description
A wrapper around a trillium::Conn
for testing
Stability note: this may be replaced by an extension trait at some point.
Implementations§
source§impl TestConn
impl TestConn
sourcepub fn build<M>(
method: M,
path: impl Into<String>,
body: impl Into<Synthetic>,
) -> Self
pub fn build<M>( method: M, path: impl Into<String>, body: impl Into<Synthetic>, ) -> Self
constructs a new TestConn with the provided method, path, and body.
use trillium_testing::{prelude::*, TestConn};
let mut conn = TestConn::build("get", "/", "body");
assert_eq!(conn.method(), Method::Get);
assert_eq!(conn.path(), "/");
assert_eq!(conn.take_request_body_string(), "body");
sourcepub fn with_request_header(
self,
header_name: impl Into<HeaderName<'static>>,
header_value: impl Into<HeaderValues>,
) -> Self
pub fn with_request_header( self, header_name: impl Into<HeaderName<'static>>, header_value: impl Into<HeaderValues>, ) -> Self
chainable constructor to append a request header to the TestConn
use trillium_testing::TestConn;
let conn = TestConn::build("get", "/", "body")
.with_request_header("some-header", "value");
assert_eq!(conn.request_headers().get_str("some-header"), Some("value"));
sourcepub fn with_request_body(self, body: impl Into<Synthetic>) -> Self
pub fn with_request_body(self, body: impl Into<Synthetic>) -> Self
chainable constructor to replace the request body. this is useful
when chaining with a trillium_testing::methods
builder, as they do not provide a way to specify the body.
use trillium_testing::{methods::post, TestConn};
let mut conn = post("/").with_request_body("some body");
assert_eq!(conn.take_request_body_string(), "some body");
let mut conn = TestConn::build("post", "/", "some body")
.with_request_body("once told me");
assert_eq!(conn.take_request_body_string(), "once told me");
sourcepub fn with_peer_ip(self, ip: IpAddr) -> Self
pub fn with_peer_ip(self, ip: IpAddr) -> Self
sets the peer ip for this test conn
sourcepub fn with_state<S>(self, state: S) -> Self
pub fn with_state<S>(self, state: S) -> Self
set state on the test conn
sourcepub fn run(self, handler: &impl Handler) -> Self
pub fn run(self, handler: &impl Handler) -> Self
blocks on running this conn against a handler and finalizes
response headers. also aliased as TestConn::on
use trillium_testing::prelude::*;
async fn handler(conn: Conn) -> Conn {
conn.ok("hello trillium")
}
let conn = get("/").run(&handler);
assert_ok!(conn, "hello trillium", "content-length" => "14");
sourcepub async fn run_async(self, handler: &impl Handler) -> Self
pub async fn run_async(self, handler: &impl Handler) -> Self
runs this conn against a handler and finalizes response headers.
use trillium_testing::prelude::*;
async fn handler(conn: Conn) -> Conn {
conn.ok("hello trillium")
}
block_on(async move {
let conn = get("/").run_async(&handler).await;
assert_ok!(conn, "hello trillium", "content-length" => "14");
});
sourcepub fn on(self, handler: &impl Handler) -> Self
pub fn on(self, handler: &impl Handler) -> Self
blocks on running this conn against a handler and finalizes
response headers. also aliased as TestConn::run
.
use trillium_testing::prelude::*;
async fn handler(conn: Conn) -> Conn {
conn.ok("hello trillium")
}
let conn = get("/").on(&handler);
assert_ok!(conn, "hello trillium", "content-length" => "14");
sourcepub fn take_response_body_string(&mut self) -> Option<String>
pub fn take_response_body_string(&mut self) -> Option<String>
Reads the response body to string and returns it, if set. This is
used internally to [assert_body
] which is the preferred
interface
sourcepub fn take_request_body_string(&mut self) -> String
pub fn take_request_body_string(&mut self) -> String
Reads the request body to string and returns it
Methods from Deref<Target = Conn>§
sourcepub fn status(&self) -> Option<Status>
pub fn status(&self) -> Option<Status>
returns the response status for this Conn
, if it has been set.
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
assert!(conn.status().is_none());
conn.set_status(200);
assert_eq!(conn.status().unwrap(), Status::Ok);
sourcepub fn set_status(&mut self, status: impl TryInto<Status>)
pub fn set_status(&mut self, status: impl TryInto<Status>)
assigns a status to this response. see Conn::status
for example usage
sourcepub fn set_body(&mut self, body: impl Into<Body>)
pub fn set_body(&mut self, body: impl Into<Body>)
Sets the response body from any impl Into<Body>
. Note that this does not set the response
status or halted.
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
conn.set_body("hello");
assert_eq!(conn.response_len(), Some(5));
sourcepub fn take_response_body(&mut self) -> Option<Body>
pub fn take_response_body(&mut self) -> Option<Body>
Removes the response body from the Conn
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
conn.set_body("hello");
let mut body = conn.take_response_body().unwrap();
assert_eq!(body.len(), Some(5));
assert_eq!(conn.response_len(), None);
sourcepub fn response_body(&self) -> Option<&Body>
pub fn response_body(&self) -> Option<&Body>
Borrows the response body from the Conn
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
conn.set_body("hello");
let body = conn.response_body().unwrap();
assert_eq!(body.len(), Some(5));
assert!(body.is_static());
assert_eq!(body.static_bytes(), Some(&b"hello"[..]));
sourcepub fn state<T>(&self) -> Option<&T>where
T: 'static,
pub fn state<T>(&self) -> Option<&T>where
T: 'static,
Attempts to retrieve a &T from the state set
use trillium_testing::prelude::*;
struct Hello;
let mut conn = get("/").on(&());
assert!(conn.state::<Hello>().is_none());
conn.insert_state(Hello);
assert!(conn.state::<Hello>().is_some());
sourcepub fn state_mut<T>(&mut self) -> Option<&mut T>where
T: 'static,
pub fn state_mut<T>(&mut self) -> Option<&mut T>where
T: 'static,
Attempts to retrieve a &mut T from the state set
sourcepub fn set_state<T>(&mut self, state: T) -> Option<T>
👎Deprecated: use Conn::insert_state
pub fn set_state<T>(&mut self, state: T) -> Option<T>
see [insert_state
]
sourcepub fn insert_state<T>(&mut self, state: T) -> Option<T>
pub fn insert_state<T>(&mut self, state: T) -> Option<T>
Inserts a new type into the state set. See Conn::state
for an example.
Returns the previously-set instance of this type, if any
sourcepub fn take_state<T>(&mut self) -> Option<T>
pub fn take_state<T>(&mut self) -> Option<T>
Removes a type from the state set and returns it, if present
sourcepub fn mut_state_or_insert_with<T, F>(&mut self, default: F) -> &mut T
pub fn mut_state_or_insert_with<T, F>(&mut self, default: F) -> &mut T
Either returns the current &mut T from the state set, or inserts a new one with the provided default function and returns a mutable reference to it
sourcepub async fn request_body(&mut self) -> ReceivedBody<'_, BoxedTransport>
pub async fn request_body(&mut self) -> ReceivedBody<'_, BoxedTransport>
Returns a ReceivedBody
that references this Conn
. The Conn
retains all data and holds the singular transport, but the
ReceivedBody
provides an interface to read body content.
See also: Conn::request_body_string
for a convenience function
when the content is expected to be utf8.
§Examples
use trillium_testing::prelude::*;
let mut conn = get("/").with_request_body("request body").on(&());
let request_body = conn.request_body().await;
assert_eq!(request_body.content_length(), Some(12));
assert_eq!(request_body.read_string().await.unwrap(), "request body");
sourcepub async fn request_body_string(&mut self) -> Result<String, Error>
pub async fn request_body_string(&mut self) -> Result<String, Error>
Convenience function to read the content of a request body as a String
.
§Errors
This will return an error variant if either there is an IO failure on the underlying transport or if the body content is not a utf8 string.
§Examples
use trillium_testing::prelude::*;
let mut conn = get("/").with_request_body("request body").on(&());
assert_eq!(conn.request_body_string().await.unwrap(), "request body");
sourcepub fn response_len(&self) -> Option<u64>
pub fn response_len(&self) -> Option<u64>
if there is a response body for this conn and it has a known fixed length, it is returned from this function
use trillium_testing::prelude::*;
let mut conn = get("/").on(&|conn: trillium::Conn| async move {
conn.with_body("hello")
});
assert_eq!(conn.response_len(), Some(5));
sourcepub fn method(&self) -> Method
pub fn method(&self) -> Method
returns the request method for this conn.
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
assert_eq!(conn.method(), Method::Get);
sourcepub fn headers_mut(&mut self) -> &mut Headers
👎Deprecated: use Conn::response_headers_mut
pub fn headers_mut(&mut self) -> &mut Headers
sourcepub fn response_headers(&self) -> &Headers
pub fn response_headers(&self) -> &Headers
borrow the response headers
sourcepub fn response_headers_mut(&mut self) -> &mut Headers
pub fn response_headers_mut(&mut self) -> &mut Headers
mutably borrow the response headers
sourcepub fn request_headers(&self) -> &Headers
pub fn request_headers(&self) -> &Headers
borrow the request headers
sourcepub fn request_headers_mut(&mut self) -> &mut Headers
pub fn request_headers_mut(&mut self) -> &mut Headers
mutably borrow request headers
sourcepub fn path(&self) -> &str
pub fn path(&self) -> &str
returns the path for this request. note that this may not represent the entire http request path if running nested routers.
sourcepub fn querystring(&self) -> &str
pub fn querystring(&self) -> &str
returns query part of the request path
use trillium_testing::prelude::*;
let conn = get("/a/b?c&d=e").on(&());
assert_eq!(conn.querystring(), "c&d=e");
let conn = get("/a/b").on(&());
assert_eq!(conn.querystring(), "");
§Parsing
Trillium does not include a querystring parsing library, as there is no universal standard for querystring encodings of arrays, but several library options exist, inluding:
QueryStrong
(by the author of trillium)serde_qs
querystring
serde_querystring
sourcepub fn set_halted(&mut self, halted: bool)
pub fn set_halted(&mut self, halted: bool)
sets the halted
attribute of this conn. see Conn::halt
.
use trillium_testing::prelude::*;
let mut conn = get("/").on(&());
assert!(!conn.is_halted());
conn.set_halted(true);
assert!(conn.is_halted());
sourcepub fn is_halted(&self) -> bool
pub fn is_halted(&self) -> bool
retrieves the halted state of this conn. see Conn::halt
.
sourcepub fn is_secure(&self) -> bool
pub fn is_secure(&self) -> bool
predicate function to indicate whether the connection is
secure. note that this does not necessarily indicate that the
transport itself is secure, as it may indicate that
trillium_http
is behind a trusted reverse proxy that has
terminated tls and provided appropriate headers to indicate
this.
sourcepub fn start_time(&self) -> Instant
pub fn start_time(&self) -> Instant
The [Instant
] that the first header bytes for this conn were
received, before any processing or parsing has been performed.
sourcepub fn inner(&self) -> &Conn<BoxedTransport>
pub fn inner(&self) -> &Conn<BoxedTransport>
returns an immutable reference to the inner
trillium_http::Conn
. please open an issue if you need to do
this in application code.
stability note: hopefully this can go away at some point, but
for now is an escape hatch in case trillium_http::Conn
presents interfaces that cannot be reached otherwise.
sourcepub fn inner_mut(&mut self) -> &mut Conn<BoxedTransport>
pub fn inner_mut(&mut self) -> &mut Conn<BoxedTransport>
returns a mutable reference to the inner
trillium_http::Conn
. please open an issue if you need to
do this in application code.
stability note: hopefully this can go away at some point, but
for now is an escape hatch in case trillium_http::Conn
presents interfaces that cannot be reached otherwise.
sourcepub fn peer_ip(&self) -> Option<IpAddr>
pub fn peer_ip(&self) -> Option<IpAddr>
retrieves the remote ip address for this conn, if available.
sourcepub fn set_peer_ip(&mut self, peer_ip: Option<IpAddr>)
pub fn set_peer_ip(&mut self, peer_ip: Option<IpAddr>)
sets the remote ip address for this conn.
sourcepub fn push_path(&mut self, path: String)
pub fn push_path(&mut self, path: String)
for router implementations. pushes a route segment onto the path
sourcepub async fn cancel_on_disconnect<'a, Fut>(
&'a mut self,
fut: Fut,
) -> Option<<Fut as Future>::Output>
pub async fn cancel_on_disconnect<'a, Fut>( &'a mut self, fut: Fut, ) -> Option<<Fut as Future>::Output>
Cancels and drops the future if reading from the transport results in an error or empty read
If the client disconnects from the conn’s transport, this function will return None. If the future completes without disconnection, this future will return Some containing the output of the future.
The use of this method is not advised if your connected http client employs pipelining (rarely seen in the wild), as it will buffer an unbounded number of requests
Note that the inner future cannot borrow conn, so you will need to clone or take any information needed to execute the future prior to executing this method.
§Example
async fn something_slow_and_cancel_safe() -> String {
String::from("this was not actually slow")
}
async fn handler(mut conn: Conn) -> Conn {
match conn.cancel_on_disconnect(async {
something_slow_and_cancel_safe().await
}).await {
Some(returned_body) => conn.ok(returned_body),
None => conn
}
}
sourcepub async fn is_disconnected(&mut self) -> bool
pub async fn is_disconnected(&mut self) -> bool
Check if the transport is connected by testing attempting to read from the transport
§Example
This is best to use at appropriate points in a long-running handler, like:
async fn handler(mut conn: Conn) -> Conn {
for _ in 0..100 {
if conn.is_disconnected().await {
return conn;
}
something_slow_but_not_cancel_safe().await;
}
conn.ok("ok!")
}