test_help-rs

Test helpers for Rust

Table of Contents

• Introduction
• Installation
• Components
  • Constants
  • Enumerations
  • Features
  • Functions
  • Macros
  • Structures
  • Traits
• Examples
• Project Information
  • Where to get help
  • Contribution guidelines
  • Dependencies
    • Efferent (fan-out)
    • Build Dependencies
    • Development Dependencies
    • Afferent (fan-in)
  • Related projects
  • License

Introduction

Rust has powerful and easy-to-use unit-testing mechanisms, but there are some missing elements, particularly around the use of floating-point values - f32 and f64 - that are provided by this crate for asserting approximate equality, as in:

use test_helpers::{
	assert_scalar_eq_approx,
	assert_vector_eq_approx,
	margin,
	multiplier,
};

#[test]
fn example_test_of_scalar_evaluation() {
	let expected = 3.0;
	let actual = 3.0001;
	assert_scalar_eq_approx!(expected, actual, margin(0.0001));
}

#[test]
fn example_test_of_vector_evaluation() {
	let expected = &[ 3.0, -40404.0, 1.23456 ];
	let actual = Vec::from([ 3.0, -40410.0, 1.234567 ]);
	assert_vector_eq_approx!(expected, actual, multiplier(0.00015));
}

Installation

Reference in Cargo.toml in the usual way:

test_help-rs = { version = "0.2.1" }

Components

Constants

The following constants are defined in constants:

• DEFAULT_MARGIN — default absolute margin (0.0001, i.e. 1e-4) used by the stock two-argument assertion macros when no custom evaluator is supplied;
• DEFAULT_MULTIPLIER — default relative multiplier (0.000001, i.e. 1e-6) used together with DEFAULT_MARGIN by the stock zero_margin_or_multiplier() evaluator path;

Enumerations

The following enumerations are defined:

• ComparisonResult — outcome of comparing two scalar f64 values:
  • ExactlyEqual — the values are identical (including matching infinities and, when the "nan-equality" feature is enabled, both NaN);
  • ApproximatelyEqual — the values differ but are within the margin or multiplier tolerance of the evaluator;
  • Unequal — the values are not equal under the evaluator;
• VectorComparisonResult — outcome of comparing two vectors of f64 values:
  • ExactlyEqual — same length and every element pair is exactly equal;
  • ApproximatelyEqual — same length and every element pair is equal within the evaluator tolerance;
  • DifferentLengths { expected_length, actual_length } — the vectors have different lengths;
  • UnequalElements { index_of_first_unequal_element, expected_value_of_first_unequal_element, actual_value_of_first_unequal_element } — same length but at least one element pair is unequal under the evaluator;

Features

The following optional features are defined in Cargo.toml:

• Crate-specific features:

  • full — enables all crate-specific features; use a nightly toolchain because it includes nightly-constants;
  • nan-equality — allows two f64::NAN values to be treated as equal for stock comparisons (does not affect custom ApproximateEqualityEvaluator implementations);

• nightly-constants — enables unit tests for additional std::f64 constants that require the unstable more_float_constants feature; build and test with pinned nightly-2026-08-08 via ./scripts/test-nightly-constants (this feature is for crate development only and is not required by downstream consumers);

• General features:

  • null-feature — a feature that has no effect (and, thus, is useful for simplifying driver scripts);

Functions

The following functions are defined:

• margin() -> impl ApproximateEqualityEvaluator — creates a margin-based evaluator;
• multiplier() -> impl ApproximateEqualityEvaluator — creates a multiplier-based evaluator;
• zero_margin_or_multiplier() -> impl ApproximateEqualityEvaluator — applies a margin when either comparand is zero and a multiplier otherwise;
• evaluate_scalar_eq_approx() — compares scalar values that are logically f64 without asserting;
• evaluate_vector_eq_approx() — compares vectors of values that are logically f64 without asserting;

Macros

The following macros are defined (re-exported at the crate root via test_helpers):

• assert_scalar_eq_approx!(expected, actual) — asserts approximate equality using the stock zero_margin_or_multiplier() evaluator (DEFAULT_MULTIPLIER / DEFAULT_MARGIN);
• assert_scalar_eq_approx!(expected, actual, evaluator) — asserts approximate equality using a custom ApproximateEqualityEvaluator;
• assert_scalar_ne_approx!(expected, actual) — asserts approximate inequality using the stock evaluator;
• assert_scalar_ne_approx!(expected, actual, evaluator) — asserts approximate inequality using a custom evaluator;
• assert_vector_eq_approx!(expected, actual) — asserts approximate equality of two vectors (slices, arrays, or Vec) using the stock evaluator;
• assert_vector_eq_approx!(expected, actual, evaluator) — asserts approximate vector equality using a custom evaluator;
• assert_vector_ne_approx!(expected, actual) — asserts approximate vector inequality using the stock evaluator;
• assert_vector_ne_approx!(expected, actual, evaluator) — asserts approximate vector inequality using a custom evaluator;

Structures

No public structures are defined at this time.

Traits

The following traits are defined:

• ApproximateEqualityEvaluator — prescribes the non-mutating evaluate() method, allowing custom evaluators to be used with the assertion macros;
• TestableAsF64 — prescribes the non-mutating testable_as_f64() -> f64 method, with an implementation for any type that implements the ToF64 trait defined in the base-traits crate;

Examples

Example programs are provided in the examples directory:

• examples/scalars.rs — scalar approximate equality and inequality:

cargo run --example scalars

• examples/strings.rs — string-view equality and inequality using a custom AsStr implementation:

cargo run --example strings

• examples/vectors.rs — vector approximate equality and inequality (slice and Vec):

cargo run --example vectors

scalars exercises assert_scalar_eq_approx!() and assert_scalar_ne_approx!() with margin- and multiplier-based evaluators. strings demonstrates custom AsStr implementations. vectors includes the README introduction example and similar pass/fail demonstrations for vector assertions.

Project Information

Where to get help

GitHub Page

Contribution guidelines

Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/test_help-rs.

Dependencies

Efferent (fan-out)

Libraries upon which test_help-rs depends:

• base-traits — ToF64 trait used by TestableAsF64;

The committed Cargo.lock is retained for reproducible development and CI builds; locked Cargo commands are used throughout the workflow.

Build Dependencies

Libraries used only when building test_help-rs (not required by downstream consumers):

• bt-rs — rustc::compiler_version() in build.rs to detect Rust 1.94+ and set the rustc_1_94_or_newer cfg for unit tests of stable std::f64::consts added in that release;

Development Dependencies

None currently.

Afferent (fan-in)

Projects that depend on test_help-rs (typically as a dev-dependency for unit tests):

• auto_buffer.Rust;
• collect-rs;
• libpath.Rust;
• p99.Rust;
• shwild.Rust;

Related projects

• shwild.Rust defines functionality for matching strings against SHell-compatible WILDcard patterns, including matching assertion macros that are useful in unit-testing;

License

test_help-rs is released under the 3-clause BSD license. See LICENSE for details.