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.

• Crate: https://crates.io/crates/assertables
• Docs: https://docs.rs/assertables/
• Repo: https://github.com/sixarm/assertables-rust-crate/
• Contact: joel@joelparkerhenderson.com

Introduction

The Rust programming language provides assert macros to test code:

• assert!()
• assert_eq!(a, b)
• [assert_ne!(a, b)]((https://doc.rust-lang.org/std/macro.assert_ne.html)

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

For values:

• assert_lt!(a, b) // less than
• assert_le!(a, b) // less than or equal to
• assert_gt!(a, b) // greater than
• assert_ge!(a, b) // greater than or equal to

For strings:

• assert_starts_with!(a, b)
• assert_ends_with!(a, b)

For matching:

• assert_contains!(a, b)
• assert_is_match!(a, b)

For infix operators:

• assert_infix!(a == b)
• assert_infix!(a && b)

For numbers:

• assert_in_delta!(a, b, delta)
• assert_in_epsilon!(a, b, epsilon)

For results:

• assert_result_ok!(a)
• assert_result_ok_eq!(a)
• assert_result_ok_ne!(a)
• assert_result_err!(a)

For options:

• assert_option_some!(a)
• assert_option_some_eq!(a)
• assert_option_some_ne!(a)
• assert_option_none!(a)

For polls:

• assert_poll_ready!(a)
• assert_poll_ready_eq!(a, b)
• assert_poll_ready_ne!(a, b)
• assert_poll_pending!(a)

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

• assert_set_subset_eq!(collection1, collection2)
• assert_set_disjoint_eq!(collection1, collection2)

For file system paths and input/output readers:

• assert_fs_read_to_string_eq!(path1, path2)
• assert_io_read_to_string_eq!(reader1, reader2)

For command capture of standard output and standard error:

• assert_command_stdout_eq!(command1, command2)
• assert_program_args_stdout_eq!(program1, args1, program2, args2)

There are many more macros that are grouped into modules.

Modules for enums:

• assert_optionfor Option {Some, None}
• assert_result for Result {Ok, Err}
• assert_poll for Poll {Ready, Pending}

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

• assert_set for set collections
• assert_bag for bag collections

Modules for functions:

• assert_fn for functions in general.
• assert_fn_ok for functions that return Result::Ok.
• assert_fn_err for functions that return Result::Err.

Modules for readers:

• assert_fs_read_to_string for file system path contents.
• assert_io_read_to_string for input/output reader streams.

Modules for external calls:

• assert_command for commands with stdout/stderr.
• assert_program_args for programs with args with stdout/stderr.

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.

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:

• assert_starts_with!(a, b) // panic!
• debug_assert_starts_with!(a, b) // panic! in debug mode
• assert_starts_with_as_result!(a, b) // return Ok or Err

Forms for messages

All the assert macros have 2 forms for messages.

• Default message form.
• Custom message form.

Examples:

• assert_starts_with!(a, b)
• assert_starts_with!(a, b, "Your custom message here")

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:

• assert_io_read_to_string_eq!(reader1, reader2)
• assert_io_read_to_string_eq_expr!(reader, expr)

Tracking

• Package: assertables-rust-crate
• Version: 8.6.0
• Created: 2021-03-30T15:47:49Z
• Updated: 2024-09-18T03:02:31Z
• 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)