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 results:

For options:

For polls:

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.

Shorthands:

  • path ≈ implements AsRef<Path>
  • reader ≈ method reader.read*()
  • readee ≈ function read*(readee)
  • matcher ≈ such as matcher.is_match(matchee)
  • container ≈ such as container.contains(containee)
  • set ≈ a collection such as ::std::collections::BTreeSet
  • bag ≈ a collection such as ::std::collections::BTreeMap

Samples:

  • alfa, bravo, charlie, …
  • lorem, ipsum, dolor, …
  • foo, goo, hoo, …

§Forms

§Forms for panic versus error

All the assert macros have 3 forms for different purposes:

  • Panic form for typical tests.
  • Debug form for debugging runtimes.
  • Result form for runtime checks, verifications, validations, etc.

Examples:

§Forms for messages

All the assert macros have 2 forms for messages.

  • Default message form.
  • Custom message form.

Examples:

§Forms for other versus expression

Many of the assert macros have 2 forms for comparing left hand side and right hand side.

  • Comparing a LHS item to a RHS other of the same type.
  • Comparing a LHS item to a RHS expression.

Examples:

§Change highlights

8.6: Add assert_poll_ready_eq, assert_poll_ready_ne (planned)

8.5: Add assert_option_some_eq, assert_option_some_ne (planned)

8.4: Add assert_result_ok_eq, assert_result_ok_ne

8.3: Add assert_poll_ready, assert_poll_pending.

8.2: Add assert_infix.

8.1: Add assert_result_ok, assert_result_err, assert_option_some, assert_option_none.

8.0: Add assert_fs_read_to_string_*. Breaking change: rename assert_read_to_string_* macros to assert_io_read_to_string_*.

7.x: Add assert_in_delta, assert_in_epsilon. Add assert_fn_* macros with multiple arities.

6.x: Add assert_starts_with, assert_ends_with, assert_contains, assert_is_match. Add debug_assert_* macros everywhere.

§Tracking

  • Package: assertables-rust-crate
  • Version: 8.4.0
  • Created: 2021-03-30T15:47:49Z
  • Updated: 2024-09-11T02:11:16Z
  • 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_poll
    Assert macros for Poll {Ready, Pending}
  • 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§