Improve assert_eq failure message formatting to increase legibility

[lpil]

• Feature Name: prettier-assert
• Start Date: 2017-01-22
• RFC PR:
• Rust Issue:

Summary

Improve assert_eq failure message formatting to increase legibility.

Motivation

Currently when assert_eq fails the default panic text has all the information on one long line, which is difficult to parse. This is more difficult when working with larger data structures. I'd like to alter the format of this text in order improve legibility, putting each piece of information on a different line.

Detailed design

Here is an failing test with the current format:

---- log_packet::tests::syntax_error_test stdout ----
        thread 'log_packet::tests::syntax_error_test' panicked at 'assertion failed: `(left == right)` (left: `"Syntax Error: a.rb:1: syntax error, unexpected end-of-input\n\n"`, right: `"Syntax error: a.rb:1: syntax error, unexpected end-of-input\n\n"`)', src/log_packet.rs:102
note: Run with `RUST_BACKTRACE=1` for a backtrace.

Here is a failing test with an alternate format:

---- log_packet::tests::syntax_error_test stdout ----
        thread 'log_packet::tests::syntax_error_test' panicked at 'assertion failed: `(left == right)`

left:  `"Syntax Error: a.rb:1: syntax error, unexpected end-of-input\n\n"`
right: `"Syntax error: a.rb:1: syntax error, unexpected end-of-input\n\n"`

', src/log_packet.rs:102
note: Run with `RUST_BACKTRACE=1` for a backtrace.

In addition to putting each expression on a separate line I've also padding the word "left" with an extra space. This makes the values line up and easier to visually diff.

This could be further improved with coloured diff'ing. i.e. If two strings are between a certain levenshtein distance colour additional chars green and missing ones red.

Here is a screenshot of the output of the Elixir lang ExUnit test assertion macro, which I think is extremely clear:

Drawbacks

?

Unresolved questions

This could be implemented as an alternative assert macro in a library. Is there more value in doing this? Is there value in keeping the stdlib assert_eq as it is?

Have I opened the RFC correctly? I'm unsure. ;P

Etc

Thank you.

+ I'm happy to work on implementing this feature, though I am a newbie Rustacean :)

[alilleybrinker]

Would changing the message be a stability issue? Is there any guarantee about compilation error messages? I'm guessing there isn't, based on the recent overhaul.

[jethrogb]

I think panics in general could benefit from a multi-line scheme

[crowdagger]

This could be implemented as an alternative assert macro in a library. Is there more value in doing this?

Not sure about this, but I think colour diffing might require additional libraries than just std (e.g.in order to correctly display colors portably?). OTOH, the first alternate version (with multiple lines but no colour diffing) would already be a nice improvement.

[withoutboats]

This seems like a great improvement. I've definitely had to redirect stderr and create files to diff these messages before.

I'm not sure if you intended this to be a 'pre-RFC' discussion or an RFC, but in order to track RFCs we ask users to open a pull request against this repository with the text of the RFC as a file located at text/0000-${feature_name}.md.

My only other feedback is that we also have an assert_ne! macro, and any change applied to the output of assert_eq! should be applied to that macro as well.

[seanmonstar]

Standard compiler errors already use colors in addition to whitespace formatting.

[withoutboats]

But assert_eq! is not a compiler error, its a part of the standard library. AFAIK, the standard library doesn't contain any terminal output manipulation more complex than printing text.

[p-kraszewski]

I guess LLVMy way of underlining errors might do. It does not use terminal control codes.

---- log_packet::tests::syntax_error_test stdout ----
        thread 'log_packet::tests::syntax_error_test' panicked at 'assertion failed: `(left == right)`

left:  `"Syntax Error: a.rb:1: syntax error, unexpected end-of-input\n\n"`
right: `"Syntax error: a.rb:1: syntax error, unexpected end-of-input\n\n"`
         ~~~~~~ ^ ~~~~
', src/log_packet.rs:102
note: Run with `RUST_BACKTRACE=1` for a backtrace.

[lpil]

I'll move this over to a PR.