Please document the meaning of - and + in the output of failed string-equality assertions

[offby1]

I'm using pytest-3.6.3

I realized that that when I am looking at the output of a failed string-equality assertion, I didn't know what the - and the + meant. Here's an example that I created once I deduced their meanings:

def test_wat_plus():
    # This failure's output includes a +, since the right-hand side has more stuff.
    assert 'one\ntwo\nthree\n' == 'one\ntwo\ntwo-anna-half\nthree\n'


def test_wat_minus():
    # This failure's output includes a -, since the left-hand side has more stuff.
    assert 'one\ntwo\ntwo-anna-half\nthree\n' == 'one\ntwo\nthree\n'

Running pytest yields this output:

python3 -m pytest test_wat.py 
=============================================================================================================== test session starts ================================================================================================================
platform darwin -- Python 3.7.0, pytest-3.6.3, py-1.5.4, pluggy-0.6.0
rootdir: /private/tmp, inifile:
collected 2 items                                                                                                                                                                                                                                  

test_wat.py FF                                                                                                                                                                                                                               [100%]

===================================================================================================================== FAILURES =====================================================================================================================
__________________________________________________________________________________________________________________ test_wat_plus ___________________________________________________________________________________________________________________

    def test_wat_plus():
        # This failure's output includes a +, since the right-hand side has more stuff.
>       assert 'one\ntwo\nthree\n' == 'one\ntwo\ntwo-anna-half\nthree\n'
E       AssertionError: assert 'one\ntwo\nthree\n' == 'one\ntwo\ntwo-anna-half\nthree\n'
E           one
E           two
E         + two-anna-half
E           three

test_wat.py:3: AssertionError
__________________________________________________________________________________________________________________ test_wat_minus __________________________________________________________________________________________________________________

    def test_wat_minus():
        # This failure's output includes a -, since the left-hand side has more stuff.
>       assert 'one\ntwo\ntwo-anna-half\nthree\n' == 'one\ntwo\nthree\n'
E       AssertionError: assert 'one\ntwo\ntw...half\nthree\n' == 'one\ntwo\nthree\n'
E           one
E           two
E         - two-anna-half
E           three

test_wat.py:8: AssertionError
============================================================================================================= 2 failed in 0.18 seconds =============================================================================================================

pytest itself is working fine; my complaint is that I had to write up this little example to be certain that - and + meant what I thought they meant.

[pytestbot]

GitMate.io thinks possibly related issues are #3638 (Full diff thinks unittest.mock.ANY fails equality check in assertions), #79 (assertion rewriting fails with 'in' and 'and' operators), #637 (Assertion reverse engineering often fails), #2314 (capsys fails to capture the output by stdout), and #2172 (Capturing output causes test to fail.).

[nicoddemus]

@offby1 thanks for writing.

Was it confusing because of the order of the direction of the +/- characters? I ask because we were discussing exactly this in #3333.

[offby1]

It was confusing because I simply didn't know what + and - meant. To be honest, I can't think of a better way to indicate which is which ... except, perhaps, to include a "legend" the way the diff program does when invoked with -u:

$ command diff -u this that
--- this	2018-07-30 09:54:15.000000000 -0700
+++ that	2018-07-30 09:57:33.000000000 -0700
@@ -8,5 +8,6 @@
 
-a line in this that is not in that
 a line in both files
+
+an extra line