Core: Allow @ExtendedDescription annotation on test methods

[janschaefer]

With an @ExtendedDescription tag on test methods it would be possible to explain in more detail the rational behind a scenario.

[clementheliou]

Hi,

While waiting for this useful feature, is there an equivalent that would allow us to explain the rational behind our scenarios ?

Moreover, do you plan to display the extended description accordingly to the steps ones or in another way (close to a tag's description for example) ?

[janschaefer]

Currently the only way is to use JavaDoc comments. But these will not appear in the report.

It is not clear to me yet what the best way of showing this information would be. I think I have to experiment a bit. Having a tooltip like for the steps would be one possible option.

If you have a good suggestion, let me know :-)

[clementheliou]

I was thinking about the tooltip too. Another option, as suggested in my previous comment, would be to display it as a caption of the scenario.

We could provide the two alternatives using an annotation attribute.

[janschaefer]

So the caption would be in a smaller font directly above the scenario and already visible when scenario is not expanded?

[clementheliou]

Exactly. One will have to experiment a bit to find the best style (smaller size, italic font, etc.).

[janschaefer]

I have tried three different ways: having a small description above the title, having a tooltip on the title and having a separate icon behind the title with a tooltip. I liked the third solution most. Please tell me what you think. Here is the report of the current implementation:

http://jgiven.org/snapshot/jgiven-report/html5/#/tag/HTML5%20Report

[clementheliou]

Hi Jan.

Thanks for the tests.
I like this solution too. However, I think that the icon is not the most appropriated. I would use a question mark or something similar instead.

Moreover, I would try with a formatted content as the explanation could be greater than a single sentence. Did you plan anything about this?

Great job anyway.

[janschaefer]

Regarding the Icon: Choose one: http://fortawesome.github.io/Font-Awesome/icons/ :-)

Regarding the formatting, you are right. A tool tip is a bit limited in this sense. I will think about that a bit more.

[clementheliou]

This one could be great: http://fortawesome.github.io/Font-Awesome/icon/question-circle/
Regarding the formatting, please keep me posted.

Thanks a lot for the job. ;)

[janschaefer]

Ok. I have now changed the icon and addition also show the extended description as a subheader below the title (so you can better compare both approaches):

http://jgiven.org/snapshot/jgiven-report/html5/#/tag/HTML5%20Report

The sub header is now always visible.

[clementheliou]

Hi Jan,

The subheader/caption approach seems to be the best one.

I would add an attribute to the annotation to determinate the default visibility, keeping the icon to toggle the caption. I would also reduce the caption's font size (from 1.1 em to 0.8 em).

What do you think about this solution?

[janschaefer]

Ok, I have experimented a lot now. It is harder than I initially thought :-)
I think a toggle of the extended description is not really needed. It seems like an overkill, because the scenario itself can already be toggled.
I changed the font size to 0.9rem and also added a slight border to the bottom. I also limit the width of the description to 35rem so that a single text line is not getting too wide.
Finally I reduced the size of the icon and also made it a bit lighter.
I am still not sure whether the icon is actually needed or not. Is it really important to know whether a scenario has an extended description or not when looking at the list of scenarios?

Please have another look: http://jgiven.org/snapshot/jgiven-report/html5/#/tag/HTML5%20Report

[clementheliou]

Hi Jan,

I agree with you about the toggle feature.
Current implementation is OK for me.
I would keep the icon.

[janschaefer]

Great. Then I close this issue for now. If we have further ideas we can create a new issue.