Module colored

Functions for highlighting differences between expected and actual values for failed assertions.

The highlighting differences functionality of asserting is gated behind the crate feature colored.

Highlighting differences between expected and actual value helps with spotting the differences between the two values and makes finding the reason for a failed test much easier. The concept is to compare the expected and the actual values and highlight missing and unexpected parts when printing the actual and expected values with the assertion failure.

When printing the expected value parts or the whole value is highlighted as “missing” if there is no related part in the actual value. On the other hand, when printing the actual value parts or the whole value is highlighted as “unexpected” if there is no related part in the expected value. The “missing” parts and the “unexpected” parts are highlighted in two different colors (or in bold glyphs).

Which colors are used or whether bold glyphs should be used instead of colors can be configured via the environment variable ASSERTING_HIGHLIGHT_DIFFS. See the documentation of the function diff_format_for_mode for a list of the supported highlight modes. Using an environment variable to configure the highlight mode (colors) has the advantage that each developer working on the same code base can set the colors to his/her liking.

The intended way to configure the environment variable is to add the setting to the Cargo config.toml in the users home directory. For example, to set the colors to red and blue set the environment variable to red-blue within the [env] section of the ~/.cargo/config.toml file, like so:

[env]
ASSERTING_HIGHLIGHT_DIFFS = "red-blue"

This feature respects the NO_COLOR environment variable. If NO_COLOR is set to a non-empty string, no colors are used, regardless of the mode set with the ASSERTING_HIGHLIGHT_DIFFS environment variable.

The functions provided by this module help with highlighting missing and unexpected parts when composing the failure message for an assertion.

Constants

DEFAULT_DIFF_FORMAT

Default diff format.

DIFF_FORMAT_BOLDcolored

A diff format that highlights differences in the actual value in bold.

DIFF_FORMAT_NO_HIGHLIGHT

Diff format that does not highlight anything.

DIFF_FORMAT_RED_BLUEcolored

A diff format that highlights differences in the colors red and blue.

DIFF_FORMAT_RED_GREENcolored

A diff format that highlights differences in the colors red and green.

DIFF_FORMAT_RED_YELLOWcolored

A diff format that highlights differences in the colors red and yellow.

Functions

configured_diff_format

Reads the configured DiffFormat and returns it.

diff_format_for_modecolored

Returns a DiffFormat for the given highlight mode.

mark_all_entries_in_map

Highlights all entries in a map using the given DiffFormat.

mark_all_items_in_collection

Highlights all items of a collection using the given DiffFormat.

mark_diff

Highlights differences between the expected and the actual value and returns the debug formatted values with marked differences.

mark_diff_str

Highlights differences between the expected and the actual string and returns new strings with marked differences.

mark_missing

Highlights the given value as “missing value” using the color for “missing values” as specified by the given DiffFormat.

mark_missing_char

Highlights the given character as “missing value” using the color for missing values as specified by the given DiffFormat.

mark_missing_char_in_string

Highlights all occurences of a character within a string using the color for missing values as specified by the given DiffFormat.

mark_missing_string

Highlights the given string as “missing value” using the color for missing values as specified by the given DiffFormat.

mark_missing_substring_in_string

Highlights a substring within a string using the color for missing values as specified by the given DiffFormat.

mark_selected_chars_in_string_as_missing

Highlights selected characters within a string using the color for missing values as specified by the given DiffFormat.

mark_selected_chars_in_string_as_unexpected

Highlights selected characters within a string using the color for unexpected values or bold as specified by the given DiffFormat.

mark_selected_entries_in_map

Highlights selected entries in a map using the given DiffFormat.

mark_selected_items_in_collection

Highlights selected items of a collection using the given DiffFormat.

mark_unexpected

Highlights the given value as “unexpected value” using the color for unexpected values or bold as specified by the given DiffFormat.

mark_unexpected_char

Highlights the given character as “unexpected value” using the color for unexpected values or bold as specified by the given DiffFormat.

mark_unexpected_char_in_string

Highlights all occurences of a character within a string using the color for unexpected values or bold as specified by the given DiffFormat.

mark_unexpected_string

Highlights the given string as “unexpected value” using the color for unexpected values or bold as specified by the given DiffFormat.

mark_unexpected_substring_in_string

Highlights a substring within a string using the color for unexpected values or bold as specified by the given DiffFormat.