Module cargo_test_support::compare

Routines for comparing and diffing output.

Deprecated comparisons

Cargo’s tests are in transition from internal-only pattern and normalization routines used in asserts like crate::Execs::with_stdout to assert_e2e and assert_ui.

Patterns

Many of these functions support special markup to assist with comparing text that may vary or is otherwise uninteresting for the test at hand. The supported patterns are:

• [..] is a wildcard that matches 0 or more characters on the same line (similar to .* in a regex). It is non-greedy.
• [EXE] optionally adds .exe on Windows (empty string on other platforms).
• [ROOT] is the path to the test directory’s root.
• [CWD] is the working directory of the process that was run.
• There is a wide range of substitutions (such as [COMPILING] or [WARNING]) to match cargo’s “status” output and allows you to ignore the alignment. See the source of substitute_macros for a complete list of substitutions.
• [DIRTY-MSVC] (only when the line starts with it) would be replaced by [DIRTY] when cfg(target_env = "msvc") or the line will be ignored otherwise. Tests that work around issue 7358 can use this to avoid duplicating the with_stderr call like: if cfg!(target_env = "msvc") {e.with_stderr("...[DIRTY]...");} else {e.with_stderr("...");}.

Normalization

In addition to the patterns described above, the strings are normalized in such a way to avoid unwanted differences. The normalizations are:

• Raw tab characters are converted to the string <tab>. This is helpful so that raw tabs do not need to be written in the expected string, and to avoid confusion of tabs vs spaces.
• Backslashes are converted to forward slashes to deal with Windows paths. This helps so that all tests can be written assuming forward slashes. Other heuristics are applied to try to ensure Windows-style paths aren’t a problem.
• Carriage returns are removed, which can help when running on Windows.

Macros

• regex 🔒
  This makes it easier to write regex replacements that are guaranteed to only get compiled once

Structs

• WildStr 🔒
  A single line string that supports [..] wildcard matching.

Statics

• E2E_LITERAL_REDACTIONS 🔒
• MIN_LITERAL_REDACTIONS 🔒

Functions

• add_regex_redactions 🔒
• add_test_support_redactions 🔒
• assert_e2e
  Assertion policy for functional end-to-end tests
• assert_match_exact 🔒
  Convenience wrapper around match_exact which will panic on error.
• assert_ui
  Assertion policy for UI tests
• collect_json_objects 🔒
• find_json_mismatch 🔒
  Compares JSON object for approximate equality. You can use [..] wildcard in strings (useful for OS-dependent things such as paths). You can use a "{...}" string literal as a wildcard for arbitrary nested JSON (useful for parts of object emitted by other programs (e.g., rustc) rather than Cargo itself).
• find_json_mismatch_r 🔒
• match_contains 🔒
  Checks that the given string contains the given contiguous lines somewhere.
• match_contains_n 🔒
  Checks that the given string contains the given contiguous lines somewhere, and should be repeated number times.
• match_does_not_contain 🔒
  Checks that the given string does not contain the given contiguous lines anywhere.
• match_exact 🔒
  Compares one string against another, checking that they both match.
• match_json 🔒
  Checks that the given string of JSON objects match the given set of expected JSON objects.
• match_json_contains_unordered 🔒
  Checks that the given string of JSON objects match the given set of expected JSON objects, ignoring their order.
• match_unordered 🔒
  Checks that the given string contains the given lines, ignoring the order of the lines.
• match_with_without 🔒
  Checks that the given string has a line that contains the given patterns, and that line also does not contain the without patterns.
• meta_cmp 🔒
• normalize_actual 🔒
  Normalizes the output so that it can be compared against the expected value.
• normalize_expected 🔒
  Normalizes the expected string so that it can be compared against the actual output.
• normalize_windows 🔒
  Normalizes text for both actual and expected strings on Windows.
• replace_dirty_msvc 🔒
• replace_dirty_msvc_impl 🔒
• substitute_macros 🔒