Skip to content

Commit

Permalink
Improve docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexliesenfeld
alexliesenfeld committed Sep 1, 2024
1 parent 9a4b6d9 commit 58a77a4
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 36 deletions.
48 changes: 27 additions & 21 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<h1>httpmock</h1>
</div>

<p align="center">HTTP mocking library for Rust.</p>
<p align="center">Simple yet powerful HTTP mocking library for Rust</p>
<div align="center">

[![Build](https://github.com/alexliesenfeld/httpmock/actions/workflows/build.yml/badge.svg)](https://github.com/alexliesenfeld/httpmock/actions/workflows/build.yml)
Expand Down Expand Up @@ -37,17 +37,16 @@

* Simple, expressive, fluent API.
* Many built-in helpers for easy request matching ([Regex](https://docs.rs/regex/), JSON, [serde](https://crates.io/crates/serde), cookies, and more).
* Parallel test execution.
* Custom request matchers.
* Record and Playback
* Forward and Proxy Mode
* HTTPS support
* Fault and network delay simulation.
* Custom request matchers.
* Standalone mode with an accompanying [Docker image](https://hub.docker.com/r/alexliesenfeld/httpmock).
* Helpful error messages
* [Advanced verification and debugging support](https://alexliesenfeld.github.io/posts/mocking-http--services-in-rust/#creating-mocks) (including diff generation between actual and expected HTTP request values)
* Parallel test execution.
* Fully asynchronous core with synchronous and asynchronous APIs.
* Support for [Regex](https://docs.rs/regex/) matching, JSON, [serde](https://crates.io/crates/serde), cookies, and more.
* Support for [mock configuration using YAML files](https://github.com/alexliesenfeld/httpmock/tree/master#file-based-mock-specification).

## Getting Started
Expand Down Expand Up @@ -92,32 +91,39 @@ The above example will spin up a lightweight HTTP mock server and configure it t
to path `/translate` with query parameter `word=hello`. The corresponding HTTP response will contain the text body
`Привет`.

In case the request fails, `httpmock` would show you a detailed error description including a diff between the
expected and the actual HTTP request:
When the specified expectations do not match the received request, `httpmock` provides a detailed error description,
including a diff that shows the differences between the expected and actual HTTP requests. Example:

![colored-diff.png](https://raw.githubusercontent.com/alexliesenfeld/httpmock/master/docs/diff.png)
```bash
0 of 1 expected requests matched the mock specification.
Here is a comparison with the most similar unmatched request (request number 1):

# Usage
------------------------------------------------------------
1 : Query Parameter Mismatch
------------------------------------------------------------
Expected:
key [equals] word
value [equals] hello-rustaceans

See the [reference docs](https://docs.rs/httpmock/) for detailed API documentation.
Received (most similar query parameter):
word=hello

## Examples
All received query parameter values:
1. word=hello

You can find examples in the
[`httpmock` test directory](https://github.com/alexliesenfeld/httpmock/blob/master/tests/).
The [reference docs](https://docs.rs/httpmock/) also contain _**a lot**_ of examples. There is an [online tutorial](https://alexliesenfeld.com/mocking-http-services-in-rust) as well.
Matcher: query_param
Docs: https://docs.rs/httpmock/0.8.0/httpmock/struct.When.html#method.query_param
```

## Standalone Mock Server
# Usage

You can use `httpmock` to run a standalone mock server that is executed in a separate process. There is a
[Docker image](https://hub.docker.com/r/alexliesenfeld/httpmock) available at Dockerhub to get started quickly.
See the [official documentation](http://alexliesenfeld.github.io/httpmock) for detailed API documentation.

The standalone mode allows you to mock HTTP based APIs for many API clients, not only the ones
inside your Rust tests, but also completely different programs running on remote hosts.
This is especially useful if you want to use `httpmock` in system or end-to-end tests that require mocked services
(such as REST APIs, data stores, authentication providers, etc.).
## Examples

Please refer to [the docs](https://docs.rs/httpmock/0.5.8/httpmock/#standalone-mode) for more information
You can find examples in the
[`httpmock` test directory](https://github.com/alexliesenfeld/httpmock/blob/master/tests/).
The [official documentation](http://alexliesenfeld.github.io/httpmock) and [reference docs](https://docs.rs/httpmock/) also contain _**a lot**_ of examples.

## License

Expand Down
55 changes: 40 additions & 15 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,16 @@
//! # Features
//! * Simple, expressive, fluent API.
//! * Many built-in helpers for easy request matching ([Regex](https://docs.rs/regex/), JSON, [serde](https://crates.io/crates/serde), cookies, and more).
//! * Parallel test execution.
//! * Custom request matchers.
//! * Record and Playback
//! * Forward and Proxy Mode
//! * HTTPS support
//! * Fault and network delay simulation.
//! * Custom request matchers.
//! * Standalone mode with an accompanying [Docker image](https://hub.docker.com/r/alexliesenfeld/httpmock).
//! * Helpful error messages
//! * [Advanced verification and debugging support](https://alexliesenfeld.github.io/posts/mocking-http--services-in-rust/#creating-mocks) (including diff generation between actual and expected HTTP request values)
//! * Parallel test execution.
//! * Fully asynchronous core with synchronous and asynchronous APIs.
//! * Support for [Regex](https://docs.rs/regex/) matching, JSON, [serde](https://crates.io/crates/serde), cookies, and more.
//! * Support for [mock configuration using YAML files](https://github.com/alexliesenfeld/httpmock/tree/master#file-based-mock-specification).
//!
//! # Getting Started
Expand Down Expand Up @@ -52,22 +51,48 @@
//! assert_eq!(response.status(), 200);
//! ```
//!
//! In case the request fails, `httpmock` would show you a detailed error description including a diff between the
//! expected and the actual HTTP request:
//! When the specified expectations do not match the received request, `httpmock` provides a detailed error description,
//! including a diff that shows the differences between the expected and actual HTTP requests. Example:
//!
//! ```bash
//! 0 of 1 expected requests matched the mock specification.
//! Here is a comparison with the most similar unmatched request (request number 1):
//!
//! ------------------------------------------------------------
//! 1 : Query Parameter Mismatch
//! ------------------------------------------------------------
//! Expected:
//! key [equals] word
//! value [equals] hello-rustaceans
//!
//! Received (most similar query parameter):
//! word=hello
//!
//! All received query parameter values:
//! 1. word=hello
//!
//! Matcher: query_param
//! Docs: https://docs.rs/httpmock/0.8.0/httpmock/struct.When.html#method.query_param
//! ```
//!
//! # Usage
//!
//! See the [official documentation](http://alexliesenfeld.github.io/httpmock) a for detailed
//! API documentation.
//!
//! ## Examples
//!
//! ![colored-diff.png](https://raw.githubusercontent.com/alexliesenfeld/httpmock/master/docs/diff.png)
//! You can find examples in the
//! [`httpmock` test directory](https://github.com/alexliesenfeld/httpmock/blob/master/tests/).
//! The [official documentation](http://alexliesenfeld.github.io/httpmock) and [reference docs](https://docs.rs/httpmock/)
//! also contain _**a lot**_ of examples.
//!
//! # Online Documentation
//! Please find the official `httpmock` documentation and website at: http://alexliesenfeld.github.io/httpmock
//! ## License
//!
//! # License
//! `httpmock` is free software: you can redistribute it and/or modify it under the terms
//! of the MIT Public License.
//! `httpmock` is free software: you can redistribute it and/or modify it under the terms of the MIT Public License.
//!
//! This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
//! without even the implied
//! warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the MIT Public
//! License for more details.
//! This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
//! warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the MIT Public License for more details.
extern crate lazy_static;

use std::{borrow::BorrowMut, net::ToSocketAddrs};
Expand Down

0 comments on commit 58a77a4

Please sign in to comment.