Compare commits
2 commits
415c37a700
...
f354867088
| Author | SHA1 | Date | |
|---|---|---|---|
| f354867088 | |||
| aa26fd1867 |
7 changed files with 459 additions and 149 deletions
|
|
@ -15,7 +15,7 @@ file system and network operations.
|
|||
|
||||
The Filesystem module offers a clean abstraction over `std::fs`, the standard
|
||||
file system operations. For comprehensive documentation and usage examples,
|
||||
please refer to the <https://docs.rs/kxio/latest/kxio/fs/>.
|
||||
please refer to <https://docs.rs/kxio/latest/kxio/fs/>.
|
||||
|
||||
### Key Filesystem Features:
|
||||
|
||||
|
|
|
|||
|
|
@ -147,6 +147,6 @@ mod tests {
|
|||
// not needed for this test, but should it be needed, we can avoid checking for any
|
||||
// unconsumed request matches.
|
||||
let mock_net = kxio::net::MockNet::try_from(net).expect("recover mock");
|
||||
mock_net.reset().expect("reset mock");
|
||||
mock_net.reset();
|
||||
}
|
||||
}
|
||||
|
|
|
|||
66
src/lib.rs
66
src/lib.rs
|
|
@ -1,4 +1,68 @@
|
|||
//
|
||||
//! # kxio
|
||||
//!
|
||||
//! `kxio` is a Rust library that provides injectable `FileSystem` and `Network`
|
||||
//! resources to enhance the testability of your code. By abstracting system-level
|
||||
//! interactions, `kxio` enables easier mocking and testing of code that relies on
|
||||
//! file system and network operations.
|
||||
//!
|
||||
//! ## Features
|
||||
//!
|
||||
//! - Filesystem Abstraction
|
||||
//! - Network Abstraction
|
||||
//! - Enhanced Testability
|
||||
//!
|
||||
//! ## Filesystem
|
||||
//!
|
||||
//! The Filesystem module offers a clean abstraction over `std::fs`, the standard
|
||||
//! file system operations. For comprehensive documentation and usage examples,
|
||||
//! please refer to <https://docs.rs/kxio/latest/kxio/fs/>.
|
||||
//!
|
||||
//! ### Key Filesystem Features:
|
||||
//!
|
||||
//! - File reading and writing
|
||||
//! - Directory operations
|
||||
//! - File metadata access
|
||||
//! - Fluent API for operations like `.reader().bytes()`
|
||||
//!
|
||||
//! ## Network
|
||||
//!
|
||||
//! The Network module offers a testable interface over the `reqwest` crate. For
|
||||
//! comprehensive documentation and usage examples, please refer to
|
||||
//! <https://docs.rs/kxio/latest/kxio/net/>
|
||||
//!
|
||||
//! ## Getting Started
|
||||
//!
|
||||
//! Add `kxio` to your `Cargo.toml`:
|
||||
//!
|
||||
//! ```toml
|
||||
//! [dependencies]
|
||||
//! kxio = "x.y.z"
|
||||
//! ```
|
||||
//!
|
||||
//! ## Usage
|
||||
//!
|
||||
//! See the example [get.rs](https://git.kemitix.net/kemitix/kxio/src/branch/main/examples/get.rs) for an annotated example on how to use the `kxio` library.
|
||||
//! It covers both the `net` and `fs` modules.
|
||||
//!
|
||||
//! ## Development
|
||||
//!
|
||||
//! - The project uses [Cargo Mutants](https://crates.io/crates/cargo-mutants) for mutation testing.
|
||||
//! - [ForgeJo Actions](https://forgejo.org/docs/next/user/actions/) are used for continuous testing and linting.
|
||||
//!
|
||||
//! ## Contributing
|
||||
//!
|
||||
//! Contributions are welcome! Please check our [issue tracker](https://git.kemitix.net/kemitix/kxio/issues) for open tasks or
|
||||
//! submit your own ideas.
|
||||
//!
|
||||
//! ## License
|
||||
//!
|
||||
//! This project is licensed under the terms specified in the `LICENSE` file in the
|
||||
//! repository root.
|
||||
//!
|
||||
//! ---
|
||||
//!
|
||||
//! For more information, bug reports, or feature requests, please visit our [repository](https://git.kemitix.net/kemitix/kxio).
|
||||
|
||||
pub mod fs;
|
||||
pub mod net;
|
||||
mod result;
|
||||
|
|
|
|||
142
src/net/mod.rs
142
src/net/mod.rs
|
|
@ -149,6 +149,148 @@
|
|||
//!
|
||||
//! The module uses a custom [Result] type that wraps `core::result::Result` with the custom [Error] enum,
|
||||
//! allowing for specific error handling related to network operations.
|
||||
//! Provides a testable interface over the [reqwest] crate.
|
||||
//!
|
||||
//! ## Overview
|
||||
//!
|
||||
//! The `net` module provides a testable interface for network operations.
|
||||
//! It includes implementations for both real network interactions and mocked network operations for testing purposes.
|
||||
//!
|
||||
//! ## Key methods and types:
|
||||
//!
|
||||
//! - [kxio::net::new()][new()]: Creates a new `Net` instance
|
||||
//! - [kxio::net::mock()][mock()]: Creates a new `MockNet` instance for use in tests
|
||||
//! - [Error]: enum for network-related errors
|
||||
//! - [Result]: an alias for `core::result::Result<T, Error>`
|
||||
//! - [Net]: struct for real and mocked network operations
|
||||
//! - [MockNet]: struct for defining behaviours of mocked network operations
|
||||
//!
|
||||
//! ## Usage
|
||||
//!
|
||||
//! Write your program to take a reference to [Net].
|
||||
//!
|
||||
//! Use the [Net::client] functionto create a [reqwest::RequestBuilder] which you should then pass to the [Net::send] method.
|
||||
//! This is rather than building the request and calling its own `send` method, doing so would result in the network request being sent, even under-test.
|
||||
//!
|
||||
//! ```rust
|
||||
//! use kxio::net;
|
||||
//! async fn get_example(net: &net::Net) -> net::Result<()> {
|
||||
//! let response = net.send(net.client().get("https://example.com")).await?;
|
||||
//! ///...
|
||||
//! Ok(())
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ### Real Network Operations
|
||||
//!
|
||||
//! In your production code you will want to make real network requests.
|
||||
//!
|
||||
//! Construct a [Net] using [kxio::net::new()][new()]. Then pass as a reference to your program.
|
||||
//!
|
||||
//! ```rust
|
||||
//! use kxio::net;
|
||||
//! # #[tokio::main]
|
||||
//! # async fn main() -> net::Result<()> {
|
||||
//! let net = net::new();
|
||||
//!
|
||||
//! get_example(&net).await?;
|
||||
//! # Ok(())
|
||||
//! # }
|
||||
//! # async fn get_example(net: &net::Net) -> net::Result<()> {Ok(())}
|
||||
//! ```
|
||||
//!
|
||||
//! ### Mocked Network Operations
|
||||
//!
|
||||
//! In your tests you will want to mock your network requests and responses.
|
||||
//!
|
||||
//! Construct a [MockNet] using [kxio::net::mock()][mock()].
|
||||
//!
|
||||
//! ```rust
|
||||
//! use kxio::net;
|
||||
//! let mock_net = net::mock();
|
||||
//! ```
|
||||
//!
|
||||
//! Create a [reqwest::Client] using [MockNet::client()].
|
||||
//!
|
||||
//! ```rust
|
||||
//! # let mock_net = kxio::net::mock();
|
||||
//! let client = mock_net.client();
|
||||
//! // this is the same as:
|
||||
//! let client = reqwest::Client::new();
|
||||
//! ```
|
||||
//!
|
||||
//! Define the expected responses for each request, using the [MockNet::on],
|
||||
//! that you expect you program to make during the test. You can choose what each request should be
|
||||
//! matched against. The default is to the match when both the Method and Url are the same.
|
||||
//!
|
||||
//! ```rust
|
||||
//! use kxio::net;
|
||||
//! use kxio::net::MatchOn;
|
||||
//!
|
||||
//! # #[tokio::main]
|
||||
//! # async fn main() -> net::Result<()> {
|
||||
//! # let mock_net = net::mock();
|
||||
//! # let client = mock_net.client();
|
||||
//! mock_net.on(client.get("https://example.com"))
|
||||
//! .match_on(vec![
|
||||
//! MatchOn::Url,
|
||||
//! MatchOn::Method
|
||||
//! ])
|
||||
//! .respond_with_body(mock_net.response().status(200).body("Mocked response"))?;
|
||||
//! # mock_net.reset();
|
||||
//! # Ok(())
|
||||
//! # }
|
||||
//! ```
|
||||
//!
|
||||
//! All [MatchOn] options:
|
||||
//! - [MatchOn::Method] (default)
|
||||
//! - [MatchOn::Url] (default)
|
||||
//! - [MatchOn::Headers]
|
||||
//! - [MatchOn::Body].
|
||||
//!
|
||||
//! Once you have defined all your expected responses, convert the [MockNet] into a [Net].
|
||||
//!
|
||||
//! ```rust
|
||||
//! # use kxio::net;
|
||||
//! # let mock_net = net::mock();
|
||||
//! let net: net::Net = mock_net.into();
|
||||
//! // or
|
||||
//! # let mock_net = net::mock();
|
||||
//! let net = net::Net::from(mock_net);
|
||||
//! ```
|
||||
//!
|
||||
//! Now you can pass a reference to `net` to your program.
|
||||
//!
|
||||
//! ```rust
|
||||
//! # use kxio::net;
|
||||
//! # #[tokio::main]
|
||||
//! # async fn main() -> net::Result<()> {
|
||||
//! # let mock_net = net::mock();
|
||||
//! # let net = net::Net::from(mock_net);
|
||||
//! get_example(&net).await?;
|
||||
//! # Ok(())
|
||||
//! # }
|
||||
//! # async fn get_example(net: &net::Net) -> net::Result<()> {Ok(())}
|
||||
//! ```
|
||||
//!
|
||||
//! When your test is finished, the [MockNet] will check that all the expected requests were
|
||||
//! actually made. If there were any missed, then the test will [panic].
|
||||
//!
|
||||
//! If you don't want this to happen, then call [MockNet::reset] before your test finishes.
|
||||
//! You will need to recover the [MockNet] from the [Net].
|
||||
//!
|
||||
//! ```rust
|
||||
//! # use kxio::net;
|
||||
//! # let mock_net = net::mock();
|
||||
//! # let net = net::Net::from(mock_net);
|
||||
//! let mock_net = kxio::net::MockNet::try_from(net).expect("recover mock");
|
||||
//! mock_net.reset();
|
||||
//! ````
|
||||
//!
|
||||
//! ## Error Handling
|
||||
//!
|
||||
//! The module uses a custom [Result] type that wraps `core::result::Result` with the custom [Error] enum,
|
||||
//! allowing for specific error handling related to network operations.
|
||||
|
||||
mod result;
|
||||
mod system;
|
||||
|
|
|
|||
|
|
@ -1,15 +1,32 @@
|
|||
//
|
||||
use derive_more::derive::From;
|
||||
|
||||
/// Represents a error accessing the network.
|
||||
/// The Errors that may occur within [kxio::net][crate::net].
|
||||
#[derive(Debug, From, derive_more::Display)]
|
||||
pub enum Error {
|
||||
/// The Errors that may occur when processing a `Request`.
|
||||
///
|
||||
/// Note: Errors may include the full URL used to make the `Request`. If the URL
|
||||
/// contains sensitive information (e.g. an API key as a query parameter), be
|
||||
/// sure to remove it ([`without_url`](reqwest::Error::without_url))
|
||||
Reqwest(reqwest::Error),
|
||||
|
||||
/// The Errors that may occur when processing a `Request`.
|
||||
///
|
||||
/// The cause has been converted to a String.
|
||||
Request(String),
|
||||
|
||||
/// There was network request that doesn't match any that were expected
|
||||
#[display("Unexpected request: {0}", 0.to_string())]
|
||||
UnexpectedMockRequest(reqwest::Request),
|
||||
|
||||
/// There was an error accessing the list of expected requests.
|
||||
RwLockLocked,
|
||||
|
||||
/// There was an error making a network request.
|
||||
Http(http::Error),
|
||||
|
||||
/// Attempted to extract a [MockNet][super::MockNet] from a [Net][super::Net] that does not contain one.
|
||||
NetIsNotAMock,
|
||||
}
|
||||
impl std::error::Error for Error {}
|
||||
|
|
@ -22,7 +39,7 @@ impl Clone for Error {
|
|||
}
|
||||
}
|
||||
|
||||
/// Represents a success or a failure.
|
||||
/// Represents a success or a failure within [kxio::net][crate::net].
|
||||
///
|
||||
/// Any failure is related to `std::io`, a Path Traversal
|
||||
/// (i.e. trying to escape the base of the `FileSystem`),
|
||||
|
|
|
|||
|
|
@ -1,30 +1,32 @@
|
|||
//
|
||||
use std::{marker::PhantomData, sync::RwLock};
|
||||
use std::cell::RefCell;
|
||||
|
||||
use reqwest::Client;
|
||||
|
||||
use super::{Error, Result};
|
||||
|
||||
pub trait NetType {}
|
||||
|
||||
#[derive(Debug)]
|
||||
pub struct Mocked;
|
||||
impl NetType for Mocked {}
|
||||
|
||||
#[derive(Debug)]
|
||||
pub struct Unmocked;
|
||||
impl NetType for Unmocked {}
|
||||
|
||||
/// A list of planned requests and responses
|
||||
type Plans = Vec<Plan>;
|
||||
|
||||
/// The different ways to match a request.
|
||||
#[derive(Debug, PartialEq, Eq)]
|
||||
pub enum MatchOn {
|
||||
/// The request must have a specific HTTP Request Method.
|
||||
Method,
|
||||
|
||||
/// The request must have a specific URL.
|
||||
Url,
|
||||
|
||||
/// The request must have a specify HTTP Body.
|
||||
Body,
|
||||
|
||||
/// The request must have a specific set of HTTP Headers.
|
||||
Headers,
|
||||
}
|
||||
|
||||
/// A planned request and the response to return
|
||||
///
|
||||
/// Contains a list of the criteria that a request must meet before being considered a match.
|
||||
#[derive(Debug)]
|
||||
struct Plan {
|
||||
request: reqwest::Request,
|
||||
|
|
@ -33,133 +35,65 @@ struct Plan {
|
|||
}
|
||||
|
||||
/// An abstraction for the network
|
||||
#[derive(Debug)]
|
||||
pub struct Net {
|
||||
inner: InnerNet<Unmocked>,
|
||||
mock: Option<InnerNet<Mocked>>,
|
||||
plans: Option<RefCell<Plans>>,
|
||||
}
|
||||
impl Net {
|
||||
// constructors
|
||||
/// Creates a new unmocked [Net] for creating real network requests.
|
||||
pub(super) const fn new() -> Self {
|
||||
Self {
|
||||
inner: InnerNet::<Unmocked>::new(),
|
||||
mock: None,
|
||||
}
|
||||
Self { plans: None }
|
||||
}
|
||||
|
||||
/// Creats a new [MockNet] for use in tests.
|
||||
pub(super) const fn mock() -> MockNet {
|
||||
MockNet {
|
||||
inner: InnerNet::<Mocked>::new(),
|
||||
plans: RefCell::new(vec![]),
|
||||
}
|
||||
}
|
||||
}
|
||||
impl Net {
|
||||
// public interface
|
||||
/// Helper to create a default [reqwest::Client].
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # use kxio::net::Result;
|
||||
/// let net = kxio::net::new();
|
||||
/// let client = net.client();
|
||||
/// let request = client.get("https://hyper.rs");
|
||||
/// ```
|
||||
pub fn client(&self) -> reqwest::Client {
|
||||
Default::default()
|
||||
}
|
||||
|
||||
/// Constructs the Request and sends it to the target URL, returning a
|
||||
/// future Response.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// This method fails if there was an error while sending request,
|
||||
/// redirect loop was detected or redirect limit was exhausted.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```no_run
|
||||
/// # use kxio::net::Result;
|
||||
/// # async fn run() -> Result<()> {
|
||||
/// let net = kxio::net::new();
|
||||
/// let request = net.client().get("https://hyper.rs");
|
||||
/// let response = net.send(request).await?;
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
/// ```
|
||||
pub async fn send(
|
||||
&self,
|
||||
request: impl Into<reqwest::RequestBuilder>,
|
||||
) -> Result<reqwest::Response> {
|
||||
match &self.mock {
|
||||
Some(mock) => mock.send(request).await,
|
||||
None => self.inner.send(request).await,
|
||||
}
|
||||
}
|
||||
}
|
||||
impl Default for Net {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
inner: InnerNet::<Unmocked>::new(),
|
||||
mock: None,
|
||||
}
|
||||
}
|
||||
}
|
||||
impl TryFrom<Net> for MockNet {
|
||||
type Error = super::Error;
|
||||
|
||||
fn try_from(net: Net) -> std::result::Result<Self, Self::Error> {
|
||||
match net.mock {
|
||||
Some(inner_mock) => Ok(MockNet { inner: inner_mock }),
|
||||
None => Err(Self::Error::NetIsNotAMock),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug)]
|
||||
pub struct MockNet {
|
||||
inner: InnerNet<Mocked>,
|
||||
}
|
||||
impl MockNet {
|
||||
pub fn client(&self) -> Client {
|
||||
Default::default()
|
||||
}
|
||||
pub fn on(&self, request: impl Into<reqwest::RequestBuilder>) -> OnRequest {
|
||||
self.inner.on(request)
|
||||
}
|
||||
/// Creates a [http::response::Builder] to be extended and returned by a mocked network request.
|
||||
pub fn response(&self) -> http::response::Builder {
|
||||
Default::default()
|
||||
}
|
||||
pub async fn send(
|
||||
&self,
|
||||
request: impl Into<reqwest::RequestBuilder>,
|
||||
) -> Result<reqwest::Response> {
|
||||
self.inner.send(request).await
|
||||
}
|
||||
pub fn reset(&self) -> Result<()> {
|
||||
self.inner.reset()
|
||||
}
|
||||
}
|
||||
impl From<MockNet> for Net {
|
||||
fn from(mock_net: MockNet) -> Self {
|
||||
Self {
|
||||
inner: InnerNet::<Unmocked>::new(),
|
||||
// keep the original `inner` around to allow it's Drop impelmentation to run when we go
|
||||
// out of scope at the end of the test
|
||||
mock: Some(mock_net.inner),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug)]
|
||||
pub struct InnerNet<T: NetType> {
|
||||
_type: PhantomData<T>,
|
||||
plans: RwLock<Plans>,
|
||||
}
|
||||
impl InnerNet<Unmocked> {
|
||||
const fn new() -> Self {
|
||||
Self {
|
||||
_type: PhantomData,
|
||||
plans: RwLock::new(vec![]),
|
||||
}
|
||||
}
|
||||
|
||||
pub async fn send(
|
||||
&self,
|
||||
request: impl Into<reqwest::RequestBuilder>,
|
||||
) -> Result<reqwest::Response> {
|
||||
request.into().send().await.map_err(Error::from)
|
||||
}
|
||||
}
|
||||
|
||||
impl InnerNet<Mocked> {
|
||||
const fn new() -> Self {
|
||||
Self {
|
||||
_type: PhantomData,
|
||||
plans: RwLock::new(vec![]),
|
||||
}
|
||||
}
|
||||
|
||||
pub async fn send(
|
||||
&self,
|
||||
request: impl Into<reqwest::RequestBuilder>,
|
||||
) -> Result<reqwest::Response> {
|
||||
let Some(plans) = &self.plans else {
|
||||
return request.into().send().await.map_err(Error::from);
|
||||
};
|
||||
let request = request.into().build()?;
|
||||
let read_plans = self.plans.read().map_err(|_| Error::RwLockLocked)?;
|
||||
let index = read_plans.iter().position(|plan| {
|
||||
let index = plans.borrow().iter().position(|plan| {
|
||||
// METHOD
|
||||
(if plan.match_on.contains(&MatchOn::Method) {
|
||||
plan.request.method() == request.method()
|
||||
|
|
@ -189,16 +123,85 @@ impl InnerNet<Mocked> {
|
|||
true
|
||||
})
|
||||
});
|
||||
drop(read_plans);
|
||||
match index {
|
||||
Some(i) => {
|
||||
let mut write_plans = self.plans.write().map_err(|_| Error::RwLockLocked)?;
|
||||
Ok(write_plans.remove(i).response)
|
||||
let response = plans.borrow_mut().remove(i).response;
|
||||
Ok(response)
|
||||
}
|
||||
None => Err(Error::UnexpectedMockRequest(request)),
|
||||
}
|
||||
}
|
||||
}
|
||||
impl TryFrom<Net> for MockNet {
|
||||
type Error = super::Error;
|
||||
|
||||
fn try_from(net: Net) -> std::result::Result<Self, Self::Error> {
|
||||
match &net.plans {
|
||||
Some(plans) => Ok(MockNet {
|
||||
plans: RefCell::new(plans.take()),
|
||||
}),
|
||||
None => Err(Self::Error::NetIsNotAMock),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// A struct for defining the expected requests and their responses that should be made
|
||||
/// during a test.
|
||||
///
|
||||
/// When the [MockNet] goes out of scope it will verify that all expected requests were consumed,
|
||||
/// otherwise it will `panic`.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # use kxio::net::Result;
|
||||
/// # fn run() -> Result<()> {
|
||||
/// let mock_net = kxio::net::mock();
|
||||
/// let client = mock_net.client();
|
||||
/// // define an expected requet, and the response that should be returned
|
||||
/// mock_net.on(client.get("https://hyper.rs"))
|
||||
/// .respond_with_body(mock_net.response().status(200).body("Ok"))?;
|
||||
/// let net: kxio::net::Net = mock_net.into();
|
||||
/// // use 'net' in your program, by passing it as a reference
|
||||
///
|
||||
/// // In some rare cases you don't want to assert that all expected requests were made.
|
||||
/// // You should recover the `MockNet` from the `Net` and `MockNet::reset` it.
|
||||
/// let mock_net = kxio::net::MockNet::try_from(net)?;
|
||||
/// mock_net.reset(); // only if explicitly needed
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
/// ```
|
||||
pub struct MockNet {
|
||||
plans: RefCell<Plans>,
|
||||
}
|
||||
impl MockNet {
|
||||
/// Helper to create a default [reqwest::Client].
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// let mock_net = kxio::net::mock();
|
||||
/// let client = mock_net.client();
|
||||
/// let request = client.get("https://hyper.rs");
|
||||
/// ```
|
||||
pub fn client(&self) -> Client {
|
||||
Default::default()
|
||||
}
|
||||
|
||||
/// Specify an expected request.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # use kxio::net::Result;
|
||||
/// # fn run() -> Result<()> {
|
||||
/// let mock_net = kxio::net::mock();
|
||||
/// let client = mock_net.client();
|
||||
/// mock_net.on(client.get("https://hyper.rs"))
|
||||
/// .respond_with_body(mock_net.response().status(200).body("Ok"))?;
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
/// ```
|
||||
pub fn on(&self, request_builder: impl Into<reqwest::RequestBuilder>) -> OnRequest {
|
||||
match request_builder.into().build() {
|
||||
Ok(request) => OnRequest::Valid {
|
||||
|
|
@ -216,8 +219,7 @@ impl InnerNet<Mocked> {
|
|||
response: reqwest::Response,
|
||||
match_on: Vec<MatchOn>,
|
||||
) -> Result<()> {
|
||||
let mut write_plans = self.plans.write().map_err(|_| Error::RwLockLocked)?;
|
||||
write_plans.push(Plan {
|
||||
self.plans.borrow_mut().push(Plan {
|
||||
request,
|
||||
response,
|
||||
match_on,
|
||||
|
|
@ -225,30 +227,74 @@ impl InnerNet<Mocked> {
|
|||
Ok(())
|
||||
}
|
||||
|
||||
pub fn reset(&self) -> Result<()> {
|
||||
let mut write_plans = self.plans.write().map_err(|_| Error::RwLockLocked)?;
|
||||
write_plans.clear();
|
||||
Ok(())
|
||||
/// Creates a [http::response::Builder] to be extended and returned by a mocked network request.
|
||||
pub fn response(&self) -> http::response::Builder {
|
||||
Default::default()
|
||||
}
|
||||
|
||||
/// Clears all the expected requests and responses from the [MockNet].
|
||||
///
|
||||
/// When the [MockNet] goes out of scope it will assert that all expected requests and
|
||||
/// responses were consumed. If there are any left unconsumed, then it will `panic`.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// ```rust
|
||||
/// # use kxio::net::Result;
|
||||
/// # fn run() -> Result<()> {
|
||||
/// # let mock_net = kxio::net::mock();
|
||||
/// # let net: kxio::net::Net = mock_net.into();
|
||||
/// let mock_net = kxio::net::MockNet::try_from(net)?;
|
||||
/// mock_net.reset(); // only if explicitly needed
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
/// ```
|
||||
pub fn reset(&self) {
|
||||
self.plans.take();
|
||||
}
|
||||
}
|
||||
impl<T: NetType> Drop for InnerNet<T> {
|
||||
fn drop(&mut self) {
|
||||
let Ok(read_plans) = self.plans.read() else {
|
||||
return;
|
||||
};
|
||||
assert!(read_plans.is_empty())
|
||||
impl From<MockNet> for Net {
|
||||
fn from(mock_net: MockNet) -> Self {
|
||||
Self {
|
||||
// keep the original `inner` around to allow it's Drop impelmentation to run when we go
|
||||
// out of scope at the end of the test
|
||||
plans: Some(RefCell::new(mock_net.plans.take())),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for MockNet {
|
||||
fn drop(&mut self) {
|
||||
assert!(self.plans.borrow().is_empty())
|
||||
}
|
||||
}
|
||||
impl Drop for Net {
|
||||
fn drop(&mut self) {
|
||||
if let Some(plans) = &self.plans {
|
||||
assert!(plans.borrow().is_empty())
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Intermediate struct used while declaring an expected request and its response.
|
||||
pub enum OnRequest<'net> {
|
||||
Valid {
|
||||
net: &'net InnerNet<Mocked>,
|
||||
net: &'net MockNet,
|
||||
request: reqwest::Request,
|
||||
match_on: Vec<MatchOn>,
|
||||
},
|
||||
Error(super::Error),
|
||||
}
|
||||
impl<'net> OnRequest<'net> {
|
||||
|
||||
/// Specify the criteria that a request should be compared against.
|
||||
///
|
||||
/// Given an candidate request, it will be matched against the current request if it has the
|
||||
/// same HTTP Method and Url by default. i.e. if this method is not called.
|
||||
///
|
||||
/// All criteria must be met for the match to be made.
|
||||
///
|
||||
/// Calling this method replaces the default criteria with the new criteria.
|
||||
pub fn match_on(self, match_on: Vec<MatchOn>) -> Self {
|
||||
if let OnRequest::Valid {
|
||||
net,
|
||||
|
|
@ -265,6 +311,12 @@ impl<'net> OnRequest<'net> {
|
|||
self
|
||||
}
|
||||
}
|
||||
|
||||
/// Constructs the response to be returned when a request matched the criteria.
|
||||
///
|
||||
/// The response will have an empty HTTP Body.
|
||||
///
|
||||
/// Each request and response can only be matched once each.
|
||||
pub fn respond(self, response: impl Into<http::response::Builder>) -> Result<()> {
|
||||
match self {
|
||||
OnRequest::Valid {
|
||||
|
|
@ -275,6 +327,10 @@ impl<'net> OnRequest<'net> {
|
|||
OnRequest::Error(error) => Err(error),
|
||||
}
|
||||
}
|
||||
|
||||
/// Constructs the response to be returned when a request matched the criteria.
|
||||
///
|
||||
/// Each request and response can only be matched once each.
|
||||
pub fn respond_with_body<T>(
|
||||
self,
|
||||
body_result: std::result::Result<http::Response<T>, http::Error>,
|
||||
|
|
|
|||
53
tests/net.rs
53
tests/net.rs
|
|
@ -1,6 +1,6 @@
|
|||
use assert2::let_assert;
|
||||
//
|
||||
use kxio::net::{Error, MatchOn, Net};
|
||||
use kxio::net::{Error, MatchOn, MockNet, Net};
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_get_url() {
|
||||
|
|
@ -30,17 +30,20 @@ async fn test_get_url() {
|
|||
#[tokio::test]
|
||||
async fn test_get_wrong_url() {
|
||||
//given
|
||||
let net = kxio::net::mock();
|
||||
let client = net.client();
|
||||
let mock_net = kxio::net::mock();
|
||||
let client = mock_net.client();
|
||||
|
||||
let url = "https://www.example.com";
|
||||
let request = client.get(url);
|
||||
let my_response = net.response().status(200).body("Get OK");
|
||||
let my_response = mock_net.response().status(200).body("Get OK");
|
||||
|
||||
net.on(request)
|
||||
mock_net
|
||||
.on(request)
|
||||
.respond_with_body(my_response)
|
||||
.expect("on request, respond");
|
||||
|
||||
let net = Net::from(mock_net);
|
||||
|
||||
//when
|
||||
let_assert!(
|
||||
Err(Error::UnexpectedMockRequest(invalid_request)) =
|
||||
|
|
@ -51,7 +54,8 @@ async fn test_get_wrong_url() {
|
|||
assert_eq!(invalid_request.url().to_string(), "https://some.other.url/");
|
||||
|
||||
// remove pending unmatched request - we never meant to match against it
|
||||
net.reset().expect("reset");
|
||||
let mock_net = MockNet::try_from(net).expect("recover net");
|
||||
mock_net.reset();
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
|
|
@ -214,19 +218,22 @@ async fn test_post_by_headers() {
|
|||
|
||||
#[tokio::test]
|
||||
#[should_panic]
|
||||
async fn test_unused_post() {
|
||||
async fn test_unused_post_as_net() {
|
||||
//given
|
||||
let net = kxio::net::mock();
|
||||
let client = net.client();
|
||||
let mock_net = kxio::net::mock();
|
||||
let client = mock_net.client();
|
||||
|
||||
let url = "https://www.example.com";
|
||||
let request = client.post(url);
|
||||
let my_response = net.response().status(200).body("Post OK");
|
||||
let my_response = mock_net.response().status(200).body("Post OK");
|
||||
|
||||
net.on(request)
|
||||
mock_net
|
||||
.on(request)
|
||||
.respond_with_body(my_response)
|
||||
.expect("on request, respond");
|
||||
|
||||
let _net = Net::from(mock_net);
|
||||
|
||||
//when
|
||||
// don't send the planned request
|
||||
// let _response = Net::from(net).send(client.post(url)).await.expect("send");
|
||||
|
|
@ -234,3 +241,27 @@ async fn test_unused_post() {
|
|||
//then
|
||||
// Drop implementation for net should panic
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
#[should_panic]
|
||||
async fn test_unused_post_as_mocknet() {
|
||||
//given
|
||||
let mock_net = kxio::net::mock();
|
||||
let client = mock_net.client();
|
||||
|
||||
let url = "https://www.example.com";
|
||||
let request = client.post(url);
|
||||
let my_response = mock_net.response().status(200).body("Post OK");
|
||||
|
||||
mock_net
|
||||
.on(request)
|
||||
.respond_with_body(my_response)
|
||||
.expect("on request, respond");
|
||||
|
||||
//when
|
||||
// don't send the planned request
|
||||
// let _response = Net::from(net).send(client.post(url)).await.expect("send");
|
||||
|
||||
//then
|
||||
// Drop implementation for mock_net should panic
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue