Boilerplate markup for test snippets

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Boilerplate markup for test snippets

melix

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:


// tag::implementinghandler[]
class Handler implements DefaultHandler, SayHandler, LoggingHandler {}
// end::implementinghandler[]
use (PC) {
    // tag::implementinghandler_assert[]
    def h = new Handler()
    h.on('foo', [:])
    h.on('sayHello', [:])
    // end::implementinghandler_assert[]
    def expect = """// tag::implementinghandler_output[]
Seeing foo with payload [:]
Received foo with payload [:]
Seeing sayHello with payload [:]
I say Hello!
// end::implementinghandler_output[]"""
    assert PC.BUFFER.toString() == filterTags(expect)
    PC.reset()
}

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.

Reply | Threaded
Open this post in threaded view
|

Re: Boilerplate markup for test snippets

mojavelinux
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:

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:


// tag::implementinghandler[]
class Handler implements DefaultHandler, SayHandler, LoggingHandler {}
// end::implementinghandler[]
use (PC) {
    // tag::implementinghandler_assert[]
    def h = new Handler()
    h.on('foo', [:])
    h.on('sayHello', [:])
    // end::implementinghandler_assert[]
    def expect = """// tag::implementinghandler_output[]
Seeing foo with payload [:]
Received foo with payload [:]
Seeing sayHello with payload [:]
I say Hello!
// end::implementinghandler_output[]"""
    assert PC.BUFFER.toString() == filterTags(expect)
    PC.reset()
}

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.




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Boilerplate-markup-for-test-snippets-tp1691.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--