[enhance] inline doc that appears in HTML report

[peterquiel]

The following Scenario doesn't terminate and executes the request in a loop:

    Scenario: Doc string..
      Given url "https://www.google.de"
      """
      This is text to document your scenario in detail.
      """
      When method get
      Then status 200

The Scenario works without the documentation string:

    Scenario: Doc string..
      Given url "https://www.google.de"
      When method get
      Then status 200

I don't know if karate really supports doc string, but I want them to be used in cucumber reports to add some detail information about the usecase aso.

Tested with: 0.9.5.RC3

[ptrthomas]

@peterquiel can you see if the karate.embed() api solves at least for embedding content into the report.

else IMO changes to standard Gherkin syntax should be considered carefully.

we could possibly introduce a karate keyword called doc maybe ?

* some.step()
# some comment
* doc 'THIS IS DOCUMENTATION ' + foo
* doc
"""
This is
multi line
"""
* some.step()

wdyt

[peterquiel]

@ptrthomas

* karate.embed("a doc string", "text/plain") 

works when showAllSteps configuration is false. Replacing * with a Gherkin word like And works in every case.

I thought that doc strings in tripple quotes are part of the standard Gherkin syntax .. -> https://cucumber.io/docs/gherkin/reference/#doc-strings

Using a karate keyword like doc would be ok, .. but that reminds me of the syntax highlighting issue I have with textmate grammas, multi line json/js and normal multi line text.

Well,.. I would face the same issue with the doc string Gherkin syntax and deciding whether it's a doc string or an assignment would become even more difficult I guess.

With that in mind, I prefer the suggestion you made.

I just wonder If that could be improved with respect to embed more than just simple text like the karate.embed does.

What do you think?

[peterquiel]

One additional Note.

The result of karate.embed is seen as an attachment in cucumber reports. This is a good solution for pdf, images aso. but this looks a bit clumsy when you want to add a few lines of text.
A simple documentation like it's done when print is used would be perfect.

[ptrthomas]

@peterquiel ok, I'm also leaning towards a new keyword. will think through also if doc is a good enough keyword. will keep this issue open as a feature req

btw, I've always wanted karate to include api-documentation capabilities - refer #25

and maybe this feature will be a way to make that happen / unified

another BTW is that I plan to bake HTML reporting into karate, you may have heard this already in other forums. so this is an opportunity to design it to cater to all these use-cases

which brings a serious question - should the content of doc be some kind of markdown or asciidoc. so many decisions >_<

[peterquiel]

adoc over md:
I prefer adoc, because it's richer and I belive it's easier to integerate with karate - see https://github.com/asciidoctor/asciidoctorj

I would like to embed the request, response aso. into the document. Having some sort of expression like it's done with json integration would be awesome.

This leads to general thoughts:
Why do I need additional documentation?
Because I want to explain the steps because not every important step is so clear at all - karate is a real DSL and I like it.
In this case, I want the documentation in the report instead of the step itself.

A simple example:

Then status 201

What's the meaning of that statement?
The meaning is:

User 'Peter' created successfully

And it would be great to have that in the report. Turing the report into a readable spec.

I know, this is a simple example and replacing such a "simple" statement with a documents seems too much, but a more complicated match could be replaced in a meaningful way.

I don't have an idea how to embed that feature into karate and may be there is no good way to do that, but I thinks it's worth considering it.

Furthermore, when you say backe HTML reporting into karate. What did you mean exactly?
You still need a tool to generate a report to make it readable, don't you?
Is cucumber report the way to go? Cucumber report doesn't support html very well, does it?
Is there an alternative?

[ptrthomas]

@peterquiel I was thinking of "natively" including cucumber HTML report generation into karate-core we already do it for the junit report as you know. the idea is we should have just one HTML report, and this solves for both JUnit (one at a time) or parallel execution. the reason we haven't rolled the cucumber-reporting lib into karate-core is because it has too much maven dependency bloat. one of the improvements badly needed for HTML reports IMO is a left-nav for each feature. and of course a way to in-line documentation and images like we are discussing now

of course if we decide on asciidoc, we may need to bring in that dependency. I would hope it can be made an optional dependency or maven-shaded if it is not too much

totally agree with your example, and that we should be able to pull in any variable. because of the JS engine, I think templating should be very easy.

[ptrthomas]

rolling into #1281 - most likely will not do markdown or asciidoc for now (can always be added later once we have a foundation). but we will build our own HTML templating approach, there are some interesting ideas in the works, stay tuned !