How do I create custom assertions that reuse existing assertions

[davidarkemp]

Given the following types:

Coord {
   x: u8;
   y: u8;
}

Snake {
   length: usize;
   head: Coord;
   body: Vec<Coord>;
}

How would I implement the following as a custom assertion?

   let snake: Snake = ....; 'Some Snake
   let expected_body = vec![Coord(1,1)];
   assert_that!(snake).extracting(|s| s.length).is_equal_to(expect_body.len());
   assert_that!(snake).extracting(|s| s.body).contains_exactly(expected_body);
   assert_that!(snake).extracting(|s| s.head).contains_exactly(expected_body[0]);

Ideally I'd like something like:

assert_that!(snake).has_body(&[Coord(1,1)]);

[haraldmaida]

I have thought about the easiest way this can be achieved and here is what I have come up so far:

https://github.com/innoave/asserting/blob/c2f784b6d5d9d6321899a0629ef85e5182d8e464/examples/custom_assertion_for_struct.rs

Currently there is no easy way to reuse existing assertions in combination with extracting fields from a custom struct.
But I will think about how asserting could support this use case in a much more easier way.

Another idea I have is to write a helper function for your tests like so:

fn assert_snake_body(actual_snake: &Snake, expected_body: &[Coord]) {
    assert_that!(snake).extracting(|s| s.length).is_equal_to(expect_body.len());
    assert_that!(snake).extracting(|s| s.body).contains_exactly(expected_body);
    assert_that!(snake).extracting(|s| s.head).is_equal_to(expected_body[0]);
}

let snake: Snake = ....; 'Some Snake
let expected_body = vec![Coord(1,1)];

assert_snake_body(&snake, &expected_body);

[davidarkemp]

Thanks @haraldmaida, that's a useful start.

I guess I was hoping to reuse the current code so I could get better failure results than:

assertion failed: expected snake to contain exactly in order [Coord { x: 2, y: 1 }, Coord { x: 1, y: 1 }, Coord { x: 1, y: 3 }]
       but was: [Coord { x: 2, y: 1 }, Coord { x: 1, y: 1 }, Coord { x: 1, y: 2 }]
      expected: [Coord { x: 2, y: 1 }, Coord { x: 1, y: 1 }, Coord { x: 1, y: 3 }]
       missing: []
         extra: []
  out-of-order: []

[haraldmaida]

Thanks @davidarkemp for your feedback. Its much appreciated.

I've now tried a sightly changed variant of the helper function to assert snake bodies.
https://github.com/innoave/asserting/blob/ffa718aa680bb05234c8c4e82a52bd9128ec3e2a/examples/naming_extracted_fields.rs

It uses the named method, to give the extracted fields a custom name, which is displayed in the failure result. For example

 assert_that!(snake).extracting(|s| s.body).named("snake.body").contains_exactly(expected_body);

gives a failure result like:

assertion failed: expected snake.body to contain exactly in order [Coord { x: 2, y: 1 }, Coord { x: 1, y: 1 }, Coord { x: 1, y: 2 }]
       but was: [Coord { x: 2, y: 1 }, Coord { x: -1, y: 1 }, Coord { x: 1, y: 2 }]
      expected: [Coord { x: 2, y: 1 }, Coord { x: 1, y: 1 }, Coord { x: 1, y: 2 }]
       missing: [Coord { x: 1, y: 1 }]
         extra: [Coord { x: -1, y: 1 }]
  out-of-order: []

Differences are the given field name is printed in "expected snake.body to..." and the "missing" and "extra" elements are also listed.
The string given to the named() can be any. E.g. "body", "snake.body", "Snake::body", "foo blah", .... This string is just used as the subject's name in the failure result.

[davidarkemp]

Thanks again for looking at this. That's the kind of output that would be really useful to me.
I guess I was hoping to avoid a helper function like this, as it'll fail at the first assertion, rather than telling me all the failures.

[haraldmaida]

With asserting you can also collect the failures without panicking immediately.

fn assert_snake_body(snake: &Snake, expected_body: &[Coord]) {
    let mut failures = verify_that!(snake)
        .extracting(|s| s.length)
        .named("snake.length")
        .is_equal_to(expected_body.len())
        .display_failures();
    failures.extend(
        verify_that!(snake)
            .extracting(|s| &s.body)
            .named("snake.body")
            .contains_exactly(expected_body)
            .display_failures(),
    );
    failures.extend(
        verify_that!(snake)
            .extracting(|s| s.head)
            .named("snake.head")
            .is_equal_to(expected_body[0])
            .display_failures(),
    );
    assert!(failures.is_empty(), "{}", failures.join("\n"));
}

This would give failure results like this:

assertion failed: expected snake.length to be equal to 3
   but was: 2
  expected: 3

assertion failed: expected snake.body to contain exactly in order [Coord { x: 2, y: 1 }, Coord { x: 1, y: 1 }, Coord { x: 1, y: 2 }]
       but was: [Coord { x: 2, y: 1 }, Coord { x: 1, y: 2 }, Coord { x: -1, y: 1 }]
      expected: [Coord { x: 2, y: 1 }, Coord { x: 1, y: 1 }, Coord { x: 1, y: 2 }]
       missing: [Coord { x: 1, y: 1 }]
         extra: [Coord { x: -1, y: 1 }]
  out-of-order: [Coord { x: 1, y: 2 }]

assertion failed: expected snake.head to be equal to Coord { x: 2, y: 1 }
   but was: Coord { x: 3, y: 1 }
  expected: Coord { x: 2, y: 1 }

I for myself don't like that the "assertion failed: " phrase is repeated in every failure message. I have this on my list of future improvements.
With your thoughts and feedback in mind I will think about how asserting could be improved to better support reusing existing assertions in combination with extracted fields. Unfortunately I can not promise if and when something is ready to be used.

[davidarkemp]

Thanks. Appreciate your help with this. Despite being an experienced dev, I'll still learning Rust, so this is really useful insight.

[haraldmaida]

Glad that the discussion is of some help for you. For me it is valuable, as I get some feedback, of how others are using and thinking about test assertions.

[haraldmaida]

I forgot to mention that when using verfiy_that! the failure result does not color highlight differences in the terminal by default. It must be switched on explicitly by calling with_configured_diff_format(). The helper function would then look like this:

fn assert_snake_body(snake: &Snake, expected_body: &[Coord]) {
    let mut failures = verify_that!(snake)
        .with_configured_diff_format()
        .extracting(|s| s.length)
        .named("snake.length")
        .is_equal_to(expected_body.len())
        .display_failures();
    failures.extend(
        verify_that!(snake)
            .with_configured_diff_format()
            .extracting(|s| &s.body)
            .named("snake.body")
            .contains_exactly(expected_body)
            .display_failures(),
    );
    failures.extend(
        verify_that!(snake)
            .with_configured_diff_format()
            .extracting(|s| s.head)
            .named("snake.head")
            .is_equal_to(expected_body[0])
            .display_failures(),
    );
    assert!(failures.is_empty(), "{}", failures.join("\n"));
}

[haraldmaida]

Since version 0.13.0 of asserting it is possible to write custom assertion methods with reusing of existing assertions.

I have rewritten the example for the Snake struct here.

The actual implementation is similar to the helper function above. Main advantage ist that we can use the custom assertion methods in the tests.