Lib.rs

Table of content

• Introducing clearcheck
• Key features
• Usage
• Assertions vs Matchers
• Supported assertions
  • Bool
    • Assertions
    • Usage
  • Char
    • Assertions
    • Usage
  • Collections (Vector, Arrays, Slices)
    • Assertions
    • Size based assertions
    • Usage
  • Date
    • Assertions
    • Usage
  • Filepath
    • Assertions
    • Usage
  • Float
    • Assertions
    • Usage
  • Integer
    • Assertions
    • Usage
  • HashMap
    • Assertions
    • Usage
  • Option
    • Assertions
    • Usage
  • Result
    • Assertions
    • Usage
  • T: PartialOrd
    • Assertions
    • Usage
  • T: Eq
    • Assertions
    • Usage
  • String
    • Assertions
    • Length based assertions
    • Usage
• Changelog
  • Version 0.0.2
• Unleashing the power of custom matchers and assertions
• Rust features
• Example project
• Reference
• Mention

Introducing clearcheck

Write expressive and elegant assertions with ease!

clearcheck is designed to make assertion statements as clear and concise as possible. It allows chaining multiple assertions together for a fluent and intuitive syntax, leading to more self-documenting test cases.

let pass_phrase = "P@@sw0rd1 zebra alpha";
pass_phrase.should_not_be_empty()
    .should_have_at_least_length(10)
    .should_contain_all_characters(vec!['@', ' '])
    .should_contain_a_digit()
    .should_not_contain_ignoring_case("pass")
    .should_not_contain_ignoring_case("word");

Key features:

🔹 Fluent API: Chain assertions for a natural and readable experience.

🔹 Extensive assertions: Variety of assertions covering common validation needs.

🔹 Customizable: Extend with your own assertions for specific domain requirements.

🔹 Type-safe: Built with Rust's type system for reliable and expressive assertions.

🔹 Custom assertions: Craft assertions tailored to your exact needs, ensuring comprehensive validations for various data structures.

Usage

Add this to your Cargo.toml (no features):

[dev-dependencies]
clearcheck = { version = "0.0.2" }

Add this to your Cargo.toml (all features):

[dev-dependencies]
clearcheck = { version = "0.0.2", features = ["num", "date", "regex", "file"] }
chrono = { version = "0.4.31" }
num = { version = "0.4.1" }
regex = { version = "1.10.2" }
walkdir = { version = "2.4.0", features = [] }

Assertions vs Matchers

Assertions serve as the cornerstone of the test cases, defining the exact expectations the code must fulfill. They act as a contract, ensuring that each data type (/data structure) adheres to its intended behavior.

Matchers, on the other hand, provide the granular tools for carrying out these assertions. They examine data and verify that the data conforms to specific criteria.

In essence, assertions orchestrate the high-level validation logic, while matchers act as the code-level inspectors, ensuring every detail aligns with the expectations.

Supported assertions

Bool

Assertions

Usage

let value = true;
value.should_be_true();

Char

Assertions

Usage

let letter = 'd';
letter.should_be_in_inclusive_range('a'..='d');

let letter = 'D';
letter.should_be_equal_ignoring_case('d');

Collections (Vector, Arrays, Slices)

Assertions

Size based assertions

Usage

let keywords = ["testing", "automation", "clearcheck", "junit"];
keywords.should_not_be_empty()
    .should_have_size_in_inclusive_range(4..=10)
    .should_not_contain_duplicates()
    .should_contain_any(vec!["junit", "clearcheck", "testing"])
    .should_not_contain_any(vec!["scalatest", "gotest"]);

Date (enabled by 'date' feature, depends on chrono)

Assertions

Usage

use chrono::NaiveDate;

let date = NaiveDate::from_ymd_opt(2024, 1, 10).unwrap();
date
     .should_be_a_leap_year()
     .should_have_month(1)
     .should_be_greater_than(&NaiveDate::from_ymd_opt(2023, 1, 10).unwrap());

Filepath (enabled by 'file' feature, depends on walkdir)

Assertions

Usage

use tempdir::TempDir;

let temporary_directory = TempDir::new(".").unwrap();
let file_path_junit = temporary_directory.path().join("junit.txt");
let file_path_clearcheck = temporary_directory.path().join("clearcheck.txt");

let _ = File::create(file_path_junit).unwrap();
let _ = File::create(file_path_clearcheck).unwrap();

let directory_path = temporary_directory.path();
directory_path
    .should_be_a_directory()
    .should_contain_any_of_file_names(vec!["junit.txt", "clearcheck.txt"]);

Float (enabled by 'num' feature, depends on num)

Assertions

Usage

let value: f64 = 1.34589;
value
   .should_not_be_nan()
   .should_be_positive()
   .should_be_in_inclusive_range_with_tolerance(1.11..=1.3458, 0.23);

Integer (enabled by 'num' feature, depends on num)

Assertions

Usage

let value = 24;
value
    .should_be_positive()
    .should_be_even()
    .should_be_in_inclusive_range(10..=40);

HashMap

Assertions

Usage

#[derive(Eq, Debug, PartialEq, Hash)]
struct Book {
    id: usize,
    title: &'static str,
}

impl Book {
    fn new(id: usize, title: &'static str) -> Self {
        Book { id, title }
    }
}

let mut book_id_by_name = HashMap::new();
book_id_by_name.insert("Database internals", 1);
book_id_by_name.insert("Designing data intensive applications", 2);

book_id_by_name
    .should_not_be_empty()
    .should_contain_key("Database internals")
    .should_contain_value(&1)
    .should_have_at_least_size(2)
    .should_contain("Database internals", &1);

Option

Assertions

Usage

let option = Some("clearcheck");
option.should_be_some();

Result

Assertions

Usage

let value: Result<i32, &str> = Ok(32);
value.should_be_ok();

T: PartialOrd

Assertions

Usage

let value = 12.56;
value
    .should_be_greater_than(&10.90)
    .should_be_less_than(&15.98)
    .should_be_in_inclusive_range(10.90..=13.10);

T: Eq

Assertions

Usage

#[derive(Debug, Eq, PartialEq)]
struct Book { name: &'static str }

let books = vec![
  Book {name: "Database internals"},
  Book {name: "Rust in action"}
];

let other = vec![
  Book {name: "Database internals"},
  Book {name: "Rust in action"}
];

books.should_equal(&other);

String

Assertions

Length based assertions

Usage

let pass_phrase = "P@@sw0rd1 zebra alpha";
pass_phrase.should_not_be_empty()
    .should_have_at_least_length(10)
    .should_contain_all_characters(vec!['@', ' '])
    .should_contain_a_digit()
    .should_not_contain_ignoring_case("pass")
    .should_not_contain_ignoring_case("word");

Changelog

Version 0.0.2

Version 0.0.2 refactored the String assertions to remove the duplication and introduced the following assertions:

Collection (Predicate based assertions)

Collection (Min-max based assertions)

Option (Predicate based assertions)

Result (Predicate based assertions)

Unleashing the power of custom matchers and assertions

While this crate comes loaded with a plethora of ready-made assertions, sometimes your testing needs demand a bespoke touch. clearcheck allows crafting your own custom matchers and assertions!

The possibilities are endless:

• Domain-specific validation: Craft assertions that understand the nuances of your business logic.
• Enhanced readability: Write clear and concise matchers that mirror your domain vocabulary, making your tests self-documenting and understandable.
• Reduced redundancy: Eliminate repetitive code by encapsulating complex validation logic within reusable matchers.

Let's craft a custom password matcher with specific criteria like length, digits, and banned patterns.

fn be_a_valid_password<T: AsRef<str> + Debug>() -> Matchers<T> {
    MatchersBuilder::start_building_with_inverted(be_empty().boxed())
      .push(have_atleast_same_length(10).boxed())
      .push(contain_a_digit().boxed())
      .push(contain_any_of_characters(vec!['@', '#']).boxed())
      .push_inverted(begin_with("pass").boxed())
      .push_inverted(contain_ignoring_case("pass").boxed())
      .push_inverted(contain_ignoring_case("word").boxed())
      .combine_as_and()
}

The matcher enforces the following:

• Input must not be empty.
• Input must have a minimum length of 10 characters.
• Input must contain at least one digit.
• Input must contain any of the following characters: '@', '#'.
• Input must not begin with the string "pass" (case-insensitive).
• Input must not contain the strings "pass" or "word" (case-insensitive).

Let's combine it into a powerful assertion for valid passwords.

trait PasswordAssertion {
    fn should_be_a_valid_password(&self) -> &Self;
}

impl PasswordAssertion for &str {
    fn should_be_a_valid_password(&self) -> &Self {
        self.should(&be_a_valid_password());
        self
    }
}

Time to put our password assertion to use.

#[test]
fn should_be_a_valid_password() {
    let password = "P@@sw0rd9082";
    password.should_be_a_valid_password();
}

Let's add one more condition for a password to be valid. It must be greater than the string "pass". That means, a password is valid if:

• it satisfies the previous matcher conditions
• it is greater than the string "pass"

It might appear that we can combine an OrderedMatcher in the existing be_a_valid_password method.

A key idea behind matcher compatibility is that the matchers can only be combined if they work with the same data type(s).

In this case, OrderedMatcher handles any partially ordered types (T: PartialOrd), while other matchers in be_a_valid_password work with string slices (&str).

To get around this, a separate matcher, be_greater_than_pass, can be created to handle the "greater than 'pass'" condition. This matcher works with String values, ensuring compatibility.

fn be_greater_than_pass() -> Matchers<String> {
    MatchersBuilder::start_building(be_greater_than(String::from("pass")).boxed())
        .push_inverted(be_empty().boxed())
        .combine_as_and()
}

It returns an instance of Matchers<String>, so PasswordAssertion is now implemented for String. The method should_be_a_valid_password now uses both the composed matchers to assert that the password is valid.

impl PasswordAssertion for String {
    fn should_be_a_valid_password(&self) -> &Self {
        self.should(&be_a_valid_password());
        self.should(&be_greater_than_pass());
        self
    }
}

#[test]
fn should_be_a_valid_password() {
    let password = "P@@sw0rd9082".to_string();
    password.should_be_a_valid_password();
}

Rust features

clearcheck crate supports the following features:

• date enables assertions on date
• file enables assertions on filepath
• num enables assertions on float and assertions on integer
• regex enables regular expression assertions on string

Example project

Head over to the examples project to understand the usage of this crate.

Reference

• kotest

Mention

• Google bard helped with the documentation and README :).