Skip to content

Commit

Permalink
chore: migrate major parts of the docs to lib.rs
Browse files Browse the repository at this point in the history
  • Loading branch information
@open-schnick
open-schnick committed Nov 12, 2023
1 parent 701086f commit 9b044a5
Show file tree
Hide file tree
Showing 6 changed files with 129 additions and 93 deletions.
101 changes: 20 additions & 81 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,105 +1,44 @@
# Smoothy

Write smooth assertions in a fluent and human readable way.
Write smooth assertions in a fluent and readable way.

## Examples

All asserted are stared by calling [assert_that] on a value.
After that various assertions based on the type of the asserted value can be made.

### Basic value assertions

There are several assertions available for all types:

#### Equality

[equals](struct.AssertionBuilder.html#method.equals) and [not_equals](struct.AssertionBuilder.html#method.not_equals) take anything that can be converted to the asserted type to improve ergonimics.
This is done by implementing the [Into] trait.

```rust
# use smoothy::assert_that;
assert_that(1).equals(1);
assert_that(String::from("Hello")).equals("Hello");
```

```rust
# use smoothy::assert_that;
assert_that(1).not_equals(2);
assert_that(String::from("Hello")).not_equals("Hello There");
```
## Features

Same for [try_equals](struct.AssertionBuilder.html#method.try_equals) and [try_not_equals](struct.AssertionBuilder.html#method.try_not_equals) but here the trait [TryInto] is used.
The crate is heavily inspired by [AssertJ](https://assertj.github.io/doc/)

```rust
# use smoothy::assert_that;
assert_that(1u8).try_equals(1i8);
```
- simple and readable syntax
- assertions based on the type of the asserted value
- assertion values use type conversion traits to make assertions readable

```rust
# use smoothy::assert_that;
assert_that(1u8).not_try_equals(2i8);
```

### Results

Results can be asserted by calling [is_err](struct.AssertionBuilder.html#method.is_err) or [is_ok](struct.AssertionBuilder.html#method.is_ok).
Futhermore their actual content can be asserted aswell.

#### Ok
## Examples

Basic assertion that the result is [Ok]:
All asserted are stared by calling [assert_that] on a value.
After that various assertions based on the type of the asserted value can be made.

```rust
# use smoothy::assert_that;
let result: Result<u8, ()> = Ok(1);
assert_that(result).is_ok();
assert_that(42).equals(42);
```

Asserting the [Ok]-value:

```rust
# use smoothy::assert_that;
let result: Result<u8, ()> = Ok(1);
assert_that(result).is_ok().and_value_equals(1);
assert_that(1u8).try_into_equals(1i8);
```

#### Err

Basic assertion that the result is [Err]:

```rust
# use smoothy::assert_that;
let result: Result<(), String> = Err(String::from("Oh no!"));
assert_that(result).is_err();
assert_that(String::from("Hello")).equals("Hello");
```

When the [Err]-value implements [PartialEq] one can use [and_error_equals](struct.ErrAsserter.html#method.and_error_equals)

```rust
# use smoothy::assert_that;
#[derive(Debug, PartialEq)]
struct CustomError(String);

let result: Result<(), CustomError> = Err(CustomError(String::from("Oh no!")));
assert_that(result).is_err().and_error_equals(CustomError(String::from("Oh no!")));
let result: Result<u8, String> = Ok(42);
assert_that(result)
.is_ok()
.and_value_equals(42);
```

Alternativly one can assert the error message (given the error implements [Display](std::fmt::Display)):

```rust
# use smoothy::assert_that;
# use std::fmt::{Display, Formatter};
#[derive(Debug)]
struct CustomError(String);
#
# impl Display for CustomError {
# fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
# write!(f, "{}", self.0)
# }
# }

let result: Result<(), CustomError> = Err(CustomError(String::from("Oh no!")));
assert_that(result).is_err().and_error_as_string_equals("Oh no!");
let result: Result<(), String> = Err(String::from("ups!"));
assert_that(result)
.is_err()
.and_error_to_string_equals("ups!");
```

## TODO:
Expand Down
3 changes: 1 addition & 2 deletions src/basic/try_equals.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@ impl<AssertedType> AssertionBuilder<AssertedType>
where
AssertedType: PartialEq + std::fmt::Debug,
{
// IDEA: can one combine try_equals with equals?
pub fn try_equals<T>(self, expected: T)
pub fn try_into_equals<T>(self, expected: T)
where
T: TryInto<AssertedType>,
<T as TryInto<AssertedType>>::Error: std::fmt::Debug,
Expand Down
3 changes: 1 addition & 2 deletions src/basic/try_not_equals.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@ impl<AssertedType> AssertionBuilder<AssertedType>
where
AssertedType: PartialEq + std::fmt::Debug,
{
// IDEA: can one combine try_equals with equals?
pub fn not_try_equals<T>(self, expected: T)
pub fn try_into_not_equals<T>(self, expected: T)
where
T: TryInto<AssertedType>,
<T as TryInto<AssertedType>>::Error: std::fmt::Debug,
Expand Down
103 changes: 102 additions & 1 deletion src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,105 @@
#![doc = include_str!("../README.md")]
//! Write smooth assertions in a fluent and human readable way.
//!
//! # Examples
//!
//! All asserted are stared by calling [assert_that] on a value.

Check failure on line 5 in src/lib.rs

View workflow job for this annotation

GitHub Actions / clippy

item in documentation is missing backticks 

error: item in documentation is missing backticks
   --> src/lib.rs:5:41
    |
5   | //! All asserted are stared by calling [assert_that] on a value.
    |                                         ^^^^^^^^^^^
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
note: the lint level is defined here
   --> src/lib.rs:104:9
    |
104 | #![deny(clippy::pedantic, clippy::nursery)]
    |         ^^^^^^^^^^^^^^^^
    = note: `#[deny(clippy::doc_markdown)]` implied by `#[deny(clippy::pedantic)]`
help: try
    |
5   | //! All asserted are stared by calling [`assert_that`] on a value.
    |                                         ~~~~~~~~~~~~~
//! After that various assertions based on the type of the asserted value can be made.
//!
//! ## Basic value assertions
//!
//! There are several assertions available for all types:
//!
//! ### Equality
//!
//! [equals](struct.AssertionBuilder.html#method.equals) and [not_equals](struct.AssertionBuilder.html#method.not_equals) take anything that can be converted to the asserted type to improve ergonimics.

Check failure on line 14 in src/lib.rs

View workflow job for this annotation

GitHub Actions / clippy

item in documentation is missing backticks 

error: item in documentation is missing backticks
  --> src/lib.rs:14:63
   |
14 | //! [equals](struct.AssertionBuilder.html#method.equals) and [not_equals](struct.AssertionBuilder.html#method.not_equals) take anything t...
   |                                                               ^^^^^^^^^^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
help: try
   |
14 | //! [equals](struct.AssertionBuilder.html#method.equals) and [`not_equals`](struct.AssertionBuilder.html#method.not_equals) take anything that can be converted to the asserted type to improve ergonimics.  
   |                                                               ~~~~~~~~~~~~
//! This is done by implementing the [Into] trait.
//!
//! ```
//! # use smoothy::assert_that;
//! assert_that(1).equals(1);
//! assert_that(String::from("Hello")).equals("Hello");
//! ```
//!
//! ```
//! # use smoothy::assert_that;
//! assert_that(1).not_equals(2);
//! assert_that(String::from("Hello")).not_equals("Hello There");
//! ```
//!
//! Same for [try_into_equals](struct.AssertionBuilder.html#method.try_into_equals) and [try_into_not_equals](struct.AssertionBuilder.html#method.try_into_not_equals) but here the trait [TryInto] is used.

Check failure on line 29 in src/lib.rs

View workflow job for this annotation

GitHub Actions / clippy

item in documentation is missing backticks 

error: item in documentation is missing backticks
  --> src/lib.rs:29:188
   |
29 | ...onBuilder.html#method.try_into_not_equals) but here the trait [TryInto] is used.
   |                                                                   ^^^^^^^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
help: try
   |
29 | //! Same for [try_into_equals](struct.AssertionBuilder.html#method.try_into_equals) and [try_into_not_equals](struct.AssertionBuilder.html#method.try_into_not_equals) but here the trait [`TryInto`] is used.
   |                                                                                                                                                                                            ~~~~~~~~~

Check failure on line 29 in src/lib.rs

View workflow job for this annotation

GitHub Actions / clippy

item in documentation is missing backticks 

error: item in documentation is missing backticks
  --> src/lib.rs:29:90
   |
29 | //! Same for [try_into_equals](struct.AssertionBuilder.html#method.try_into_equals) and [try_into_not_equals](struct.AssertionBuilder.htm...
   |                                                                                          ^^^^^^^^^^^^^^^^^^^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
help: try
   |
29 | //! Same for [try_into_equals](struct.AssertionBuilder.html#method.try_into_equals) and [`try_into_not_equals`](struct.AssertionBuilder.html#method.try_into_not_equals) but here the trait [TryInto] is used.
   |                                                                                          ~~~~~~~~~~~~~~~~~~~~~

Check failure on line 29 in src/lib.rs

View workflow job for this annotation

GitHub Actions / clippy

item in documentation is missing backticks 

error: item in documentation is missing backticks
  --> src/lib.rs:29:15
   |
29 | //! Same for [try_into_equals](struct.AssertionBuilder.html#method.try_into_equals) and [try_into_not_equals](struct.AssertionBuilder.htm...
   |               ^^^^^^^^^^^^^^^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
help: try
   |
29 | //! Same for [`try_into_equals`](struct.AssertionBuilder.html#method.try_into_equals) and [try_into_not_equals](struct.AssertionBuilder.html#method.try_into_not_equals) but here the trait [TryInto] is used.
   |               ~~~~~~~~~~~~~~~~~
//!
//! ```
//! # use smoothy::assert_that;
//! assert_that(1u8).try_into_equals(1i8);
//! ```
//!
//! ```
//! # use smoothy::assert_that;
//! assert_that(1u8).try_into_not_equals(2i8);
//! ```
//!
//! ## Results
//!
//! Results can be asserted by calling [is_err](struct.AssertionBuilder.html#method.is_err) or [is_ok](struct.AssertionBuilder.html#method.is_ok).

Check failure on line 43 in src/lib.rs

View workflow job for this annotation

GitHub Actions / clippy

item in documentation is missing backticks 

error: item in documentation is missing backticks
  --> src/lib.rs:43:97
   |
43 | //! Results can be asserted by calling [is_err](struct.AssertionBuilder.html#method.is_err) or [is_ok](struct.AssertionBuilder.html#metho...
   |                                                                                                 ^^^^^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
help: try
   |
43 | //! Results can be asserted by calling [is_err](struct.AssertionBuilder.html#method.is_err) or [`is_ok`](struct.AssertionBuilder.html#method.is_ok).
   |                                                                                                 ~~~~~~~

Check failure on line 43 in src/lib.rs

View workflow job for this annotation

GitHub Actions / clippy

item in documentation is missing backticks 

error: item in documentation is missing backticks
  --> src/lib.rs:43:41
   |
43 | //! Results can be asserted by calling [is_err](struct.AssertionBuilder.html#method.is_err) or [is_ok](struct.AssertionBuilder.html#metho...
   |                                         ^^^^^^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
help: try
   |
43 | //! Results can be asserted by calling [`is_err`](struct.AssertionBuilder.html#method.is_err) or [is_ok](struct.AssertionBuilder.html#method.is_ok).
   |                                         ~~~~~~~~
//! Futhermore their actual content can be asserted aswell.
//!
//! ### Ok
//!
//! Basic assertion that the result is [Ok]:
//!
//! ```
//! # use smoothy::assert_that;
//! let result: Result<u8, ()> = Ok(1);
//! assert_that(result).is_ok();
//! ```
//!
//! Asserting the [Ok]-value:
//!
//! ```
//! # use smoothy::assert_that;
//! let result: Result<u8, ()> = Ok(1);
//! assert_that(result).is_ok().and_value_equals(1);
//! ```
//!
//! ### Err
//!
//! Basic assertion that the result is [Err]:
//!
//! ```
//! # use smoothy::assert_that;
//! let result: Result<(), String> = Err(String::from("Oh no!"));
//! assert_that(result).is_err();
//! ```
//!
//! When the [Err]-value implements [PartialEq] one can use [and_error_equals](struct.ErrAsserter.html#method.and_error_equals)

Check failure on line 74 in src/lib.rs

View workflow job for this annotation

GitHub Actions / clippy

item in documentation is missing backticks 

error: item in documentation is missing backticks
  --> src/lib.rs:74:62
   |
74 | //! When the [Err]-value implements [PartialEq] one can use [and_error_equals](struct.ErrAsserter.html#method.and_error_equals)
   |                                                              ^^^^^^^^^^^^^^^^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
help: try
   |
74 | //! When the [Err]-value implements [PartialEq] one can use [`and_error_equals`](struct.ErrAsserter.html#method.and_error_equals)
   |                                                              ~~~~~~~~~~~~~~~~~~

Check failure on line 74 in src/lib.rs

View workflow job for this annotation

GitHub Actions / clippy

item in documentation is missing backticks 

error: item in documentation is missing backticks
  --> src/lib.rs:74:38
   |
74 | //! When the [Err]-value implements [PartialEq] one can use [and_error_equals](struct.ErrAsserter.html#method.and_error_equals)
   |                                      ^^^^^^^^^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
help: try
   |
74 | //! When the [Err]-value implements [`PartialEq`] one can use [and_error_equals](struct.ErrAsserter.html#method.and_error_equals)
   |                                      ~~~~~~~~~~~
//!
//! ```
//! # use smoothy::assert_that;
//! #[derive(Debug, PartialEq)]
//! struct CustomError(String);
//!
//! let result: Result<(), CustomError> = Err(CustomError(String::from("Oh no!")));
//! assert_that(result).is_err().and_error_equals(CustomError(String::from("Oh no!")));
//! ```
//!
//! Alternativly one can assert the error message (given the error implements [Display](std::fmt::Display)):
//!
//! ```
//! # use smoothy::assert_that;
//! # use std::fmt::{Display, Formatter};
//! #[derive(Debug)]
//! struct CustomError(String);
//! #
//! # impl Display for CustomError {
//! # fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
//! # write!(f, "{}", self.0)
//! # }
//! # }
//!
//! let result: Result<(), CustomError> = Err(CustomError(String::from("Oh no!")));
//! assert_that(result).is_err().and_error_to_string_equals("Oh no!");
//! ```
// enable more lint groups
#![deny(clippy::pedantic, clippy::nursery)]
// check documentation
Expand Down
6 changes: 2 additions & 4 deletions src/result/is_err.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,7 @@ impl<ErrValue> ErrAsserter<ErrValue>
where
ErrValue: Debug + Display,
{
// TODO: think about this Into. Is AsRef better?
pub fn and_error_as_string_equals(self, expected: impl Into<String>) {
let expected: String = expected.into();
implementation::assert_equals(self.value.to_string(), expected);
pub fn and_error_to_string_equals(self, expected: impl AsRef<str>) {
implementation::assert_equals(self.value.to_string().as_ref(), expected.as_ref());
}
}
6 changes: 3 additions & 3 deletions tests/is_err.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ mod assert_error_as_string {

assert_that(result)
.is_err()
.and_error_as_string_equals(String::from("Hello There"));
.and_error_to_string_equals(String::from("Hello There"));
}

#[test]
Expand All @@ -39,7 +39,7 @@ mod assert_error_as_string {

assert_that(result)
.is_err()
.and_error_as_string_equals("Hello There");
.and_error_to_string_equals("Hello There");
}

#[test]
Expand All @@ -50,7 +50,7 @@ mod assert_error_as_string {

assert_that(result)
.is_err()
.and_error_as_string_equals("yo");
.and_error_to_string_equals("yo");
}
}

Expand Down

0 comments on commit 9b044a5

Please sign in to comment.