Hi guys, As some of you may already know, the Groovy build makes use of a combination of asciidoctor + unit tests for the docs. All the snippets of codes and expected outputs that are found in the documentation are tested. This afternoon, I have encountered something that I would call "bloated" for this purpose. Basically, I needed a way to display some code and show the output. Of course, since all code is tested, the output is tested too. This led to this commit. Now, if you take a closer look, you will see that I'm using a Groovy category to redirect "println" to a stringbuilder, but since I am also testing the output, I need to write the expectation into a string:
Since I need to display the output into my asciidoctor document, the expectation block includes asciidoctor tags, but I need to remove them before executing the assertion: this is the role of the "filterTags" method code. I am wondering if anyone has a better idea on how to do this... PS: Should you need to take a look at the result, here it is. |
Administrator
|
Cédric,
This scenario has come up in several AsciiDoc brainstorming sessions I've participated in. I always tend to gravitate towards the following solution. The console output that appears in the document should be injected as the result of executing the code instead of manually snipping the output from a console session or from an assertion. That way, you know that the output in the documentation is real.
Of course, this takes a bit more effort because it requires a tight integration between the test run and the documentation build. That may not be the approach all teams want to take, but it certainly seems to be the most pure solution.
If you want to stick with your current approach, but make it a bit cleaner, you could override the include handler and implement a smarter "tagger". Something like:
include::testcase.groovy[str=implementinghandler_output]
where testcase.groovy contains: // str::implementinghandler_output[] def expect = """ Seeing foo with payload [:] Received foo with payload [:] Seeing sayHello with payload [:] I say Hello! """ // end::implementinghandler_output[] The handler would only take what is inside """ just like Groovy would.
What we need to do is design the documentation syntax the way we want it to be, then we'll implement it either in an Asciidoctor extension or in the core. -Dan On Tue, Apr 22, 2014 at 12:29 PM, melix [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Dan Allen | http://google.com/profiles/dan.j.allen |
Free forum by Nabble | Edit this page |