docstrings as a note

[koaning]

Is your feature request related to a problem? Please describe.
This might be a thing in our team, but we really like docstrings. When a unit-test fails our current team relies on reliable docstrings to explain what is happening in a test. This is nice, because sometimes code is a language that is too cryptic to explain why a test is important

Describe the solution you'd like
I must admit that I'm just starting out with the project and there's parts that I love. I really enjoy the locals view in a failed test. But instead of notes, we might be interested in seeing the doctoring attached to the testing method. This might be a highly preferential thing on our team, but may just be worth considering.

Describe alternatives you've considered
Part of this problem could be explained with a note but a docstring feels like a more natural place to write a long part of text.

Additional context
This definitely falls into the nice-to-have category, something that one would only see if a certain flag is passed from the command line (like --verbose). We're curious what the thoughts are on your side.

ps. Thanks again for speaking at PyData Amsterdam.

[thejunglejane]

I have thought about this, though admittedly not very much! What you could do for now is pass your test method's docstring to the note parameter via the _testMethodDoc attribute:

import marbles.core


class MyDocumentedTestCase(marbles.core.TestCase):

    def test_foo(self):
        '''Hi, Vincent!'''

        self.assertTrue(False, note=self._testMethodDoc)


if __name__ == '__main__':
    marbles.core.main()

and when you run it you'll get:

$ python -m marbles test.py 
F
======================================================================
FAIL: test_foo (test.MyDocumentedTestCase)
Hi, Vincent!
----------------------------------------------------------------------
marbles.core.marbles.ContextualAssertionError: False is not true

Source (/home/jane/test.py):
      8 
 >    9 self.assertTrue(False, note=self._testMethodDoc)
     10 
Note:
	Hi, Vincent!


----------------------------------------------------------------------
Ran 1 test in 0.001s

FAILED (failures=1)

One thing to keep in mind is that marbles respects the whitespace in note annotations (so that you can do things like indent lists, etc.), so lines after the first line of your docstring will be unfortunately indented in the "Note" section. You may be able to get around this by stripping the indentation level whitespace in _testMethodDoc before passing it to note.

When I come up with a more "unified" solution to this I'll reach out and ask you to give it a try :)

[thejunglejane]

ps. thanks again for having me!

[koaning]

Assigning it to a note variable is a way to deal with it, sure.

But what could I now put in the docstring that I wouldn't put in the note? What would one put in a note that one wouldn't put in a docstring?

Let me know when you're considering a unification. I'd be interested in helping out.

[thejunglejane]

Sure. Could you add some more details about what behavior you'd like to see for docstrings and notes? e.g., "If I have a test method with docstring abc, I'd like to see output xyz"

[koaning]

I would expect a failing test with verbose mode to show the doctoring of the method.