Test docstrings are not rendered in the report in a consistent way

[harmin-parra]

[//]: # ( . Note: for support questions, please use Stackoverflow or Gitter. . This repository's issues are reserved for feature requests and bug reports. . . In case of any problems with Allure Jenkins plugin please use the following repository . to create an issue: https://github.com/jenkinsci/allure-plugin/issues . . Make sure you have a clear name for your issue. The name should start with a capital . letter and no dot is required in the end of the sentence. An example of good issue names: . . - The report is broken in IE11 . - Add an ability to disable default plugins . - Support emoji in test descriptions )

I'm submitting a ...

• [x] bug report
• [ ] feature request
• [ ] support request => Please do not submit support request here, see note at the top of this template.

What is the current behavior?

Execute this pytest code

def test_1():
    """ First description """
    pass

def test_2():
    """
    Second description
    """
    pass

In the Allure report, the descriptions are included as follows:

<div class="description__text">
    <p>First description</p>
</div>

<div class="description__text">
    <pre>
        <code>Second description</code>
    </pre>
</div>

One-line docstrings are included with the <p> tag. Multi-line docstrings are included with the <pre><code> tags.

If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem

Execute the pytest code provided above

What is the expected behavior?

Docstrings should be included in the report in a consistent way.

What is the motivation / use case for changing the behavior?

It is desirable to have a consistent behavior

Please tell us about your environment:

• Allure version: 2.24.1
• Test framework: pytest@4.1.1
• Allure adaptor: allure-pytest@2.13.2

Other information

[//]: # ( . e.g. detailed explanation, stacktraces, related issues, suggestions . how to fix, links for us to have more context, eg. Stackoverflow, Gitter etc )

[delatrie]

It's actually pretty consistent, just not in the intuitive way. Allure renders a description as markdown. Here are several examples:

Paragraph

In your first example the docstring is just a line of text. It's rendered as a paragraph:

Python:

def test_1():
    """First description"""

Docstring value:

First description

Rendered description:

Block code

The second example has a docstring consisting of three lines. The first and the last lines are essentially empty and are ignored. The second line is prepended by four spaces, hence is rendered as a block code:

Python:

def test_2():
    """
    Second description
    """

Docstring value:

    Second description

Rendered description:

Complex description

Now, as you see how it works, it's easy to put something even more complicated into the docstring.

Python:

def test_3():
    """The next line will appear as a block code:

    This is rendered as a block code.

This is a table:

| Name | ID  |
| ---- | --- |
| John | 1   |
| Jane | 2   |

    """

Docstring value:

The next line will appear as a block code:

    This is rendered as a block code.

This is a table:

| Name | ID  |
| ---- | --- |
| John | 1   |
| Jane | 2   |

Rendered description:

So it's pretty consistent. It's just that raw markdown isn't that convenient to be put in python docstrings. As you see, it makes docstrings quite ugly.

I think we may try to dedent docstrings before putting them to the test's description, so that the third example could be written like this:

def test_3():
    """
    The next line will appear as a block code:

    This is rendered as a block code.

    This is a table:

    | Name | ID  |
    | ---- | --- |
    | John | 1   |
    | Jane | 2   |

    """

That will help making the whole thing more predictable and user-friendly.

[joaonc]

I think we may try to dedent docstrings before putting them to the test's description

@delatrie Please do! I've been working w/ Allure for several months now and it was nagging at me that we couldn't have formatted text from the docstring, never imagining I needed to dedent! Don't remember seeing this info in any documentation.

Dedenting in code is quite counter-intuitive and doesn't really follow Python aesthetics. Also, some linters like black auto-indent (ie, insert indentation), which makes use of these linters harder or impossible (black doesn't have an option to not indent docstrings).

Dendenting in Allure, like you suggested, would be the way to go.