Crate assertables

source ·
Expand description

§Assertables: Rust crate of assert macros for testing

The assertables Rust crate provides many assert macros to improve your compile-time tests and run-time reliability.

§Introduction

The Rust programming language provides a few built-in assert macros to test code:

The Rust programming language provides a few built-in assert macros to test code:

  • assert!()
  • assert_eq!(a, b)
  • assert_ne!(a, b)

The assertables crate provides many more, so you can write smarter tests.

For values:

For numbers:

For strings:

For matching:

For infix numeric operators and infix logical operators:

For maybes:

For collections such as arrays, vectors, maps, sets:

For file system paths and input/output readers:

For command capture of standard output and standard error:

There are many more macros that are grouped into modules.

Modules for enums:

Modules for collections, such as arrays, vectors, lists, maps:

Modules for functions:

Modules for readers:

Modules for external calls:

§Benefits

  • Your tests are more purposeful and powerful. This helps your code be more reliable.

  • Your assert failures provide more information. This helps you troubleshoot faster.

  • You gain runtime asserts. This helps you with validations and verifications.

§Features

  • Easy to use: each macro is well-documented with runnable examples and tests.

  • Zero overhead: if you don’t use a macro, then it’s never compiled into your code.

  • Zero dependencies: the crate has no release dependencies, and just a short list of development dependencies.

§Naming conventions

Abbreviations:

  • eq ≈ equal

  • ne ≈ not equal.

  • lt ≈ less than

  • le ≈ less than or equal.

  • gt ≈ greater than

  • ge ≈ greater than or equal.

Types:

  • path ≈ implements AsRef<Path> such as std::path::PathBuf.

  • reader ≈ implements method .read_to_string() such as std::io::Read.

  • matcher ≈ implements .is_match(…) such as regex::Regex.

  • containee ≈ usable inside .contains(…) such as a std::string::String substring.

  • set ≈ a collection such as ::std::collections::BTreeSet.

  • bag ≈ a collection such as ::std::collections::BTreeMap which has key counts.

§Forms

§Forms for panic! versus Err()

All the assert macros have three forms that you can use depending on your goals.

Panic form for typical tests:

Debug form for runtime:

Result form for runtime, validation, verification, sanitization, and more:

§Forms for messages

All the assert macros have 2 forms that are for default messages versus custom messages.

Default message form:

Custom message form:

§Forms for comparing an other versus an expression

Many of the assert macros have 2 forms that are for comparing a value to an other versus to an expression.

Compare the item to an other i.e. of the same type:

Compare an item to an expression:

§Change highlights

§Version 8

8.2:

  • Add assert_infix

  • Add modules for better discoverability and testability.

8.1:

  • Add Result macros assert_result_ok and assert_result_err

  • Add Option macros assert_option_some and assert_option_none

8.0:

  • Add assert_fs_read_to_string_* macros for comparing files.

  • Breaking change: rename assert_read_to_string_* macros to assert_io_read_to_string_*. If you use these macros, then please update your code to use the new naming convention.

§Version 7

  • Add assert_in_delta, assert_in_epsilon.

  • Add assert_fn_* macros with multiple arities.

  • Add cargo release for optimized tagged releases.

§Version 6

  • Add assert_starts_with, assert_ends_with, assert_contains, assert_is_match.

  • Add debug_assert_* macros everywhere.

  • Add GPL-3.0 license.

§Tracking

  • Package: assertables-rust-crate
  • Version: 8.2.1
  • Created: 2021-03-30T15:47:49Z
  • Updated: 2024-09-07T12:31:17Z
  • License: MIT or Apache-2.0 or GPL-2.0 or GPL-3.0 or contact us for more
  • Contact: Joel Parker Henderson (joel@sixarm.com)

Modules§

  • assert
    Assert a condition is true.
  • assert_bag
    Assert macros for comparing bag collections.
  • assert_command
    Assert macros for comparing commands and their stdout & stderr.
  • assert_contains
    Assert a container is a match for an expression.
  • assert_ends_with
    Assert an expression (such as a string) ends with an expression (such as a string).
  • assert_eq
    Assert an expression is equal to another.
  • assert_fn
    Assert macros for comparing functions.
  • assert_fn_err
    Assert macros for comparing functions that return errors.
  • assert_fn_ok
    Assert macros for comparing functions that return Result::Ok.
  • assert_fs_read_to_string
    Assert macros for comparing file system path contents.
  • assert_ge
    Assert a value is greater than or equal to an expression.
  • assert_gt
    Assert a value is greater than an expression.
  • assert_in_delta
    Assert a number is within delta of another number.
  • assert_in_epsilon
    Assert a number is within epsilon of another number.
  • assert_infix
    Assert a infix operator, such as assert_infix!(a == b).
  • assert_io_read_to_string
    Assert macros for comparing input/output reader streams.
  • assert_is_match
    Assert a matcher is a match for an expression.
  • assert_le
    Assert a value is less than or equal to an expression.
  • assert_lt
    Assert a value is less than an expression.
  • assert_ne
    Assert an expression is not equal to an expression.
  • assert_not_contains
    Assert an expression (such as a string) does not contain an expression (such as a substring).
  • assert_not_ends_with
    Assert an expression (such as a string) does not end with an expression (such as a string).
  • assert_not_match
    Assert an expression (such as a regex) is not a match for an expression (such as a string).
  • assert_not_starts_with
    Assert an expression (such as a string) does not start with an expression (such as a string).
  • assert_option
    Assert macros for Option {Some, None}
  • assert_program_args
    Assert macros for comparing programs with arguments.
  • assert_result
    Assert macros for Result {Ok, Err}
  • assert_set
    Assert macros for comparing set collections.
  • assert_starts_with
    Assert an expression (such as a string) starts with an expression (such as a string).

Macros§