From d3472e8ae4a0dc1fbf8616a3a626ee9a9f557058 Mon Sep 17 00:00:00 2001 From: Veetaha Date: Wed, 29 Jan 2020 03:52:13 +0200 Subject: test_utils: updated documentation and some typos --- crates/test_utils/src/lib.rs | 52 ++++++++++++++++++++++++++++++++++-------- crates/test_utils/src/marks.rs | 2 +- 2 files changed, 43 insertions(+), 11 deletions(-) diff --git a/crates/test_utils/src/lib.rs b/crates/test_utils/src/lib.rs index 659f77b71..87778fd04 100644 --- a/crates/test_utils/src/lib.rs +++ b/crates/test_utils/src/lib.rs @@ -21,6 +21,12 @@ pub use difference::Changeset as __Changeset; pub const CURSOR_MARKER: &str = "<|>"; +/// Asserts that two strings are equal, otherwise displays a rich diff between them. +/// +/// The diff shows changes from the "original" left string to the "actual" right string. +/// +/// All arguments starting from and including the 3rd one are passed to +/// `eprintln!()` macro in case of text inequality. #[macro_export] macro_rules! assert_eq_text { ($left:expr, $right:expr) => { @@ -42,6 +48,7 @@ macro_rules! assert_eq_text { }}; } +/// Infallible version of `try_extract_offset()`. pub fn extract_offset(text: &str) -> (TextUnit, String) { match try_extract_offset(text) { None => panic!("text should contain cursor marker"), @@ -49,6 +56,8 @@ pub fn extract_offset(text: &str) -> (TextUnit, String) { } } +/// Returns the offset of the first occurence of `<|>` marker and the copy of `text` +/// without the marker. fn try_extract_offset(text: &str) -> Option<(TextUnit, String)> { let cursor_pos = text.find(CURSOR_MARKER)?; let mut new_text = String::with_capacity(text.len() - CURSOR_MARKER.len()); @@ -58,6 +67,7 @@ fn try_extract_offset(text: &str) -> Option<(TextUnit, String)> { Some((cursor_pos, new_text)) } +/// Infallible version of `try_extract_range()`. pub fn extract_range(text: &str) -> (TextRange, String) { match try_extract_range(text) { None => panic!("text should contain cursor marker"), @@ -65,6 +75,8 @@ pub fn extract_range(text: &str) -> (TextRange, String) { } } +/// Returns `TextRange` between the first two markers `<|>...<|>` and the copy +/// of `text` without both of these markers. fn try_extract_range(text: &str) -> Option<(TextRange, String)> { let (start, text) = try_extract_offset(text)?; let (end, text) = try_extract_offset(&text)?; @@ -85,6 +97,11 @@ impl From for TextRange { } } +/// Extracts `TextRange` or `TextUnit` depending on the amount of `<|>` markers +/// found in `text`. +/// +/// # Panics +/// Panics if no `<|>` marker is present in the `text`. pub fn extract_range_or_offset(text: &str) -> (RangeOrOffset, String) { if let Some((range, text)) = try_extract_range(text) { return (RangeOrOffset::Range(range), text); @@ -93,7 +110,7 @@ pub fn extract_range_or_offset(text: &str) -> (RangeOrOffset, String) { (RangeOrOffset::Offset(offset), text) } -/// Extracts ranges, marked with ` ` paris from the `text` +/// Extracts ranges, marked with ` ` pairs from the `text` pub fn extract_ranges(mut text: &str, tag: &str) -> (Vec, String) { let open = format!("<{}>", tag); let close = format!("", tag); @@ -127,9 +144,9 @@ pub fn extract_ranges(mut text: &str, tag: &str) -> (Vec, String) { (ranges, res) } +/// Inserts `<|>` marker into the `text` at `offset`. pub fn add_cursor(text: &str, offset: TextUnit) -> String { - let offset: u32 = offset.into(); - let offset: usize = offset as usize; + let offset: usize = offset.to_usize(); let mut res = String::new(); res.push_str(&text[..offset]); res.push_str("<|>"); @@ -236,11 +253,10 @@ fn lines_match_works() { assert!(!lines_match("b", "cb")); } -// 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). Arrays are sorted before comparison. +/// 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. Arrays are sorted before comparison. pub fn find_mismatch<'a>(expected: &'a Value, actual: &'a Value) -> Option<(&'a Value, &'a Value)> { use serde_json::Value::*; match (expected, actual) { @@ -286,6 +302,14 @@ pub fn find_mismatch<'a>(expected: &'a Value, actual: &'a Value) -> Option<(&'a } } +/// Calls callback `f` with input code and file paths of all `.rs` files from `test_data_dir` +/// subdirectories defined by `paths`. +/// +/// If the content of the matching `.txt` file differs from the output of `f()` +/// the test will fail. +/// +/// If there is no matching `.txt` file it will be created and filled with the +/// output of `f()`, but the test will fail. pub fn dir_tests(test_data_dir: &Path, paths: &[&str], f: F) where F: Fn(&str, &Path) -> String, @@ -307,6 +331,7 @@ where } } +/// Collects all `.rs` files from `test_data_dir` subdirectories defined by `paths`. pub fn collect_tests(test_data_dir: &Path, paths: &[&str]) -> Vec<(PathBuf, String)> { paths .iter() @@ -321,6 +346,7 @@ pub fn collect_tests(test_data_dir: &Path, paths: &[&str]) -> Vec<(PathBuf, Stri .collect() } +/// Collects paths to all `.rs` files from `dir` in a sorted `Vec`. fn test_from_dir(dir: &Path) -> Vec { let mut acc = Vec::new(); for file in fs::read_dir(&dir).unwrap() { @@ -334,6 +360,7 @@ fn test_from_dir(dir: &Path) -> Vec { acc } +/// Returns the path to the root directory of `rust-analyzer` project. pub fn project_dir() -> PathBuf { let dir = env!("CARGO_MANIFEST_DIR"); PathBuf::from(dir).parent().unwrap().parent().unwrap().to_owned() @@ -356,6 +383,9 @@ pub fn read_text(path: &Path) -> String { .replace("\r\n", "\n") } +/// Returns `false` if slow tests should not run, otherwise returns `true` and +/// also creates a file at `./target/.slow_tests_cookie` which serves as a flag +/// that slow tests did run. pub fn skip_slow_tests() -> bool { let should_skip = std::env::var("CI").is_err() && std::env::var("RUN_SLOW_TESTS").is_err(); if should_skip { @@ -367,8 +397,9 @@ pub fn skip_slow_tests() -> bool { should_skip } -const REWRITE: bool = false; - +/// Asserts that `expected` and `actual` strings are equal. If they differ only +/// in trailing or leading whitespace the test won't fail and +/// the contents of `actual` will be written to the file located at `path`. fn assert_equal_text(expected: &str, actual: &str, path: &Path) { if expected == actual { return; @@ -381,6 +412,7 @@ fn assert_equal_text(expected: &str, actual: &str, path: &Path) { fs::write(path, actual).unwrap(); return; } + const REWRITE: bool = false; if REWRITE { println!("rewriting {}", pretty_path.display()); fs::write(path, actual).unwrap(); diff --git a/crates/test_utils/src/marks.rs b/crates/test_utils/src/marks.rs index fe1813947..f8fabfaff 100644 --- a/crates/test_utils/src/marks.rs +++ b/crates/test_utils/src/marks.rs @@ -1,4 +1,4 @@ -//! This module implements manually tracked test coverage, which useful for +//! This module implements manually tracked test coverage, which is useful for //! quickly finding a test responsible for testing a particular bit of code. //! //! See -- cgit v1.2.3