( )⚙ D10071 copies-rust: add a macro-based unit-testing framework

This is an archive of the discontinued Mercurial Phabricator instance.

Differential D10071

copies-rust: add a macro-based unit-testing framework
ClosedPublic

Authored by SimonSapin on Feb 25 2021, 5:42 AM.

Details

Reviewers
Alphare
Group Reviewers
hg-reviewers
Commits
rHGfa21633af201: copies-rust: add a macro-based unit-testing framework
rHGb92083ad7d52: copies-rust: add a macro-based unit-testing framework
Summary

compare_values, merge_copies_dict, and CombineChangesetCopies
are APIs whose signatures involve non-trivial types.
Calling them directly in unit tests would involve a lot of verbose
setup code that obscures the meaningful parts of a given test case.

This adds a macro-based test-harness with pseudo-syntax to tersely
create arguments and expected return values in the correct types.

For now there is only one (not particularly meaningful) test case
per tested function, just to exercize the macros.

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

SimonSapin created this revision.Feb 25 2021, 5:42 AM
Alphare accepted this revision.Mar 2 2021, 9:18 AM
Alphare added a subscriber: Alphare.

This was a harder one, macro_rules!, for all their usefulness are not the easiest thing to digest.

It's a shame macro definitions cannot have docstrings. I guess your solution is simple enough. Are you planning to write the unit tests using this harness any time soon?

SimonSapin added a subscriber: marmoute.Mar 2 2021, 9:29 AM

The plan is that @marmoute can write test cases using this harness at some point. I’m much less familiar with the *intended* behavior of various algorithms, so while I could write test cases by reverse-engineering the code I risk testing bugs without necessarily realizing they’re bugs.

We can have doc-comments on macro_rules! definitions, I felt that explaining usage was more useful near use sites.

Alphare added a comment.Mar 2 2021, 9:33 AM
In D10071#153177, @SimonSapin wrote:

The plan is that @marmoute can write test cases using this harness at some point. I’m much less familiar with the *intended* behavior of various algorithms, so while I could write test cases by reverse-engineering the code I risk testing bugs without necessarily realizing they’re bugs.

Makes sense.

We can have doc-comments on macro_rules! definitions, I felt that explaining usage was more useful near use sites.

Ah yes, I'm probably confusing this with adding a docstring to a macro call, not a definition.
I think I'd definitely prefer having the docstring on the macro_rules! definition, for sure. If you want to add a comment to point to the docstrings, that's fine.

SimonSapin added a commit: rHGb92083ad7d52: copies-rust: add a macro-based unit-testing framework.Mar 8 2021, 3:27 PM
This revision was not accepted when it landed; it landed in state Needs Review.
Closed by commit rHGb92083ad7d52: copies-rust: add a macro-based unit-testing framework (authored by SimonSapin). · Explain Why
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

Diff 26148

rust/hg-core/src/copy_tracing.rs

#[cfg(test)]
#[macro_use]
mod tests_support;
#[cfg(test)]
mod tests;
use crate::utils::hg_path::HgPath; use crate::utils::hg_path::HgPath;
use crate::utils::hg_path::HgPathBuf; use crate::utils::hg_path::HgPathBuf;
use crate::Revision; use crate::Revision;
use crate::NULL_REVISION; use crate::NULL_REVISION;
use bytes_cast::{unaligned, BytesCast}; use bytes_cast::{unaligned, BytesCast};
use im_rc::ordmap::Entry; use im_rc::ordmap::Entry;
use im_rc::ordmap::OrdMap; use im_rc::ordmap::OrdMap;

rust/hg-core/src/copy_tracing/tests.rs

  • This file was added.
use super::*;
/// Unit tests for:
///
/// ```ignore
/// fn compare_value(
/// current_merge: Revision,
/// merge_case_for_dest: impl Fn() -> MergeCase,
/// src_minor: &CopySource,
/// src_major: &CopySource,
/// ) -> (MergePick, /* overwrite: */ bool)
/// ```
#[test]
fn test_compare_value() {
// The `compare_value!` macro calls the `compare_value` function with
// arguments given in pseudo-syntax:
//
// * For `merge_case_for_dest` it takes a plain `MergeCase` value instead
// of a closure.
// * `CopySource` values are represented as `(rev, path, overwritten)`
// tuples of type `(Revision, Option<PathToken>, OrdSet<Revision>)`.
// * `PathToken` is an integer not read by `compare_value`. It only checks
// for `Some(_)` indicating a file copy v.s. `None` for a file deletion.
// * `OrdSet<Revision>` is represented as a Python-like set literal.
use MergeCase::*;
use MergePick::*;
assert_eq!(
compare_value!(1, Normal, (1, None, { 1 }), (1, None, { 1 })),
(Any, false)
);
}
/// Unit tests for:
///
/// ```ignore
/// fn merge_copies_dict(
/// path_map: &TwoWayPathMap, // Not visible in test cases
/// current_merge: Revision,
/// minor: InternalPathCopies,
/// major: InternalPathCopies,
/// get_merge_case: impl Fn(&HgPath) -> MergeCase + Copy,
/// ) -> InternalPathCopies
/// ```
#[test]
fn test_merge_copies_dict() {
// The `merge_copies_dict!` macro calls the `merge_copies_dict` function
// with arguments given in pseudo-syntax:
//
// * `TwoWayPathMap` and path tokenization are implicitly taken care of.
// All paths are given as string literals.
// * Key-value maps are represented with `{key1 => value1, key2 => value2}`
// pseudo-syntax.
// * `InternalPathCopies` is a map of copy destination path keys to
// `CopySource` values.
// - `CopySource` is represented as a `(rev, source_path, overwritten)`
// tuple of type `(Revision, Option<Path>, OrdSet<Revision>)`.
// - Unlike in `test_compare_value`, source paths are string literals.
// - `OrdSet<Revision>` is again represented as a Python-like set
// literal.
// * `get_merge_case` is represented as a map of copy destination path to
// `MergeCase`. The default for paths not in the map is
// `MergeCase::Normal`.
//
// `internal_path_copies!` creates an `InternalPathCopies` value with the
// same pseudo-syntax as in `merge_copies_dict!`.
use MergeCase::*;
assert_eq!(
merge_copies_dict!(
1,
{"foo" => (1, None, {})},
{},
{"foo" => Merged}
),
internal_path_copies!("foo" => (1, None, {}))
);
}
/// Unit tests for:
///
/// ```ignore
/// impl CombineChangesetCopies {
/// fn new(children_count: HashMap<Revision, usize>) -> Self
///
/// // Called repeatedly:
/// fn add_revision_inner<'a>(
/// &mut self,
/// rev: Revision,
/// p1: Revision,
/// p2: Revision,
/// copy_actions: impl Iterator<Item = Action<'a>>,
/// get_merge_case: impl Fn(&HgPath) -> MergeCase + Copy,
/// )
///
/// fn finish(mut self, target_rev: Revision) -> PathCopies
/// }
/// ```
#[test]
fn test_combine_changeset_copies() {
// `combine_changeset_copies!` creates a `CombineChangesetCopies` with
// `new`, then calls `add_revision_inner` repeatedly, then calls `finish`
// for its return value.
//
// All paths given as string literals.
//
// * Key-value maps are represented with `{key1 => value1, key2 => value2}`
// pseudo-syntax.
// * `children_count` is a map of revision numbers to count of children in
// the DAG. It includes all revisions that should be considered by the
// algorithm.
// * Calls to `add_revision_inner` are represented as an array of anonymous
// structs with named fields, one pseudo-struct per call.
//
// `path_copies!` creates a `PathCopies` value, a map of copy destination
// keys to copy source values. Note: the arrows for map literal syntax
// point **backwards** compared to the logical direction of copy!
use crate::NULL_REVISION as NULL;
use Action::*;
use MergeCase::*;
assert_eq!(
combine_changeset_copies!(
{ 1 => 1, 2 => 1 },
[
{ rev: 1, p1: NULL, p2: NULL, actions: [], merge_cases: {}, },
{ rev: 2, p1: NULL, p2: NULL, actions: [], merge_cases: {}, },
{
rev: 3, p1: 1, p2: 2,
actions: [CopiedFromP1("destination.txt", "source.txt")],
merge_cases: {"destination.txt" => Merged},
},
],
3,
),
path_copies!("destination.txt" => "source.txt")
);
}

rust/hg-core/src/copy_tracing/tests_support.rs

  • This file was added.
//! Supporting macros for `tests.rs` in the same directory.
//! See comments there for usage.
/// Python-like set literal
macro_rules! set {
(
$Type: ty {
$( $value: expr ),* $(,)?
}
) => {{
#[allow(unused_mut)]
let mut set = <$Type>::new();
$( set.insert($value); )*
set
}}
}
/// `{key => value}` map literal
macro_rules! map {
(
$Type: ty {
$( $key: expr => $value: expr ),* $(,)?
}
) => {{
#[allow(unused_mut)]
let mut set = <$Type>::new();
$( set.insert($key, $value); )*
set
}}
}
macro_rules! copy_source {
($rev: expr, $path: expr, $overwritten: tt) => {
CopySource {
rev: $rev,
path: $path,
overwritten: set!(OrdSet<Revision> $overwritten),
}
};
}
macro_rules! compare_value {
(
$merge_revision: expr,
$merge_case_for_dest: ident,
($min_rev: expr, $min_path: expr, $min_overwrite: tt),
($maj_rev: expr, $maj_path: expr, $maj_overwrite: tt) $(,)?
) => {
compare_value(
$merge_revision,
|| $merge_case_for_dest,
&copy_source!($min_rev, $min_path, $min_overwrite),
&copy_source!($maj_rev, $maj_path, $maj_overwrite),
)
};
}
macro_rules! tokenized_path_copies {
(
$path_map: ident, {$(
$dest: expr => (
$src_rev: expr,
$src_path: expr,
$src_overwrite: tt
)
),*}
$(,)*
) => {
map!(InternalPathCopies {$(
$path_map.tokenize(HgPath::new($dest)) =>
copy_source!(
$src_rev,
Option::map($src_path, |p: &str| {
$path_map.tokenize(HgPath::new(p))
}),
$src_overwrite
)
)*})
}
}
macro_rules! merge_case_callback {
(
$( $merge_path: expr => $merge_case: ident ),*
$(,)?
) => {
#[allow(unused)]
|merge_path| -> MergeCase {
$(
if (merge_path == HgPath::new($merge_path)) {
return $merge_case
}
)*
MergeCase::Normal
}
};
}
macro_rules! merge_copies_dict {
(
$current_merge: expr,
$minor_copies: tt,
$major_copies: tt,
$get_merge_case: tt $(,)?
) => {
{
#[allow(unused_mut)]
let mut map = TwoWayPathMap::default();
let minor = tokenized_path_copies!(map, $minor_copies);
let major = tokenized_path_copies!(map, $major_copies);
merge_copies_dict(
&map, $current_merge, minor, major,
merge_case_callback! $get_merge_case,
)
.into_iter()
.map(|(token, source)| {
(
map.untokenize(token).to_string(),
(
source.rev,
source.path.map(|t| map.untokenize(t).to_string()),
source.overwritten.into_iter().collect(),
),
)
})
.collect::<OrdMap<_, _>>()
}
};
}
macro_rules! internal_path_copies {
(
$(
$dest: expr => (
$src_rev: expr,
$src_path: expr,
$src_overwrite: tt $(,)?
)
),*
$(,)*
) => {
map!(OrdMap<_, _> {$(
String::from($dest) => (
$src_rev,
$src_path,
set!(OrdSet<Revision> $src_overwrite)
)
),*})
};
}
macro_rules! combine_changeset_copies {
(
$children_count: tt,
[
$(
{
rev: $rev: expr,
p1: $p1: expr,
p2: $p2: expr,
actions: [
$(
$Action: ident($( $action_path: expr ),+)
),*
$(,)?
],
merge_cases: $merge: tt
$(,)?
}
),*
$(,)?
],
$target_rev: expr $(,)*
) => {{
let count = map!(HashMap<Revision, usize> $children_count);
let mut combine_changeset_copies = CombineChangesetCopies::new(count);
$(
let actions = vec![$(
$Action($( HgPath::new($action_path) ),*)
),*];
combine_changeset_copies.add_revision_inner(
$rev, $p1, $p2, actions.into_iter(),
merge_case_callback! $merge
);
)*
combine_changeset_copies.finish($target_rev)
}};
}
macro_rules! path_copies {
(
$( $expected_destination: expr => $expected_source: expr ),* $(,)?
) => {
map!(PathCopies {$(
HgPath::new($expected_destination).to_owned()
=> HgPath::new($expected_source).to_owned(),
),*})
};
}