Plone 4.3 will ship with Dexterity , the new content type framework of Plone. One of the many great features in Dexterity is the schema ed...

Archived

Write testable documentation with Robot Framework

If you have background as a Python programmer, you must be familiar with
doctests -- testable code examples embedded into documentation. When Timo
Stollenwerk presented Robot Framework in his TDD-presentation in Plone
Conference 2012, the first question from the audience was, can Robot
Framework test be in embedded into documentation, similarly to Python doctests.

Soon you can.

I've been mentoring Vivek Kumar Verma in this years Google Summer of Code to
implement a better ReStructureText parser into Robot Framework. The first
part of his GSOC project was to actually enhance the parser, and the second
part is implementing a Sphinx-plugin to execute embedded Robot Framework tests
while compiling the documentation. You can follow Vivek's dive into Python
world in his blog and find him as viku__ on Freenode-channels
#plone and #robotframework.

How does it work?

As you may have guessed from the title. The first part of Vivek's GSOC is
pretty much completed and is waiting for a review from the Robot Framework
team. It's a minimal, but very powerful enhancement for the old Robot
Framework's ReST parser. While the old parser supported only so called table
syntax, the new parser allows you to use the famous plain text format
when embedding your Robot Framework tests into ReST-documents.

Your first Robot Framework doctest==================================
With the Robot Framework plain text syntax, a minimal test suite
would consists of ``*** Test Cases ***`` header and at least
one test case, like:
..code::robotframework*** Test Cases ***Foo is always FooShould be equalFooFooOne ``*** Test Cases ***``-header may be followed by as many
tests as required, like:
..code::robotframework*** Test Cases ***Foo is still FooShould be equalFooFooFoo is never BarShould not be equalFooBar

With Vivek, we decided to re-use the existing code-directive of Docutils
for embedding plain text Robot Framework tests suites into
ReStructuredText-documents. Each document can contain as many
code-directives with robotframework-language as required and Robot
Framework will concatenate their contents into a single Robot Framework test
suite.

There is a small price, of course. Docutils will tag code-directives with
robotframework-language only when also Pygments-package is installed.
Luckily you will want to have it, because since with Pygments (>= 1.6) you
will also get syntax highlighting your embedded Robot Framework tests.

Try it out

Even Vivek's GSOC-work has not been merged into Robot Framework yet, you
can try it out with the following steps:

Your first Robot Framework doctest==================================
With the Robot Framework plain text syntax, a minimal test suite
would consists of ``*** Test Cases ***`` header and at least
one test case, like:
..code::robotframework*** Test Cases ***Foo is always FooShould be equalFooFooOne ``*** Test Cases ***``-header may be followed by as many
tests as required, like:
..code::robotframework*** Test Cases ***Foo is still FooShould be equalFooFooFoo is never BarShould not be equalFooBar

I'm not sure if it will be possible (or even reasonable) to write actual tests
in such a descriptive language that they can be included into final
documentation. Yet, embedding screenshot-resulting tests into documentation
would make sense, because those would keep documentation screenshots up to date
and would also work as acceptance tests for the documented features.

That's why the rest of Vivek's GSOC will be about running the tests within
Sphinx: the same compilation run could both execute tests to create screenshots
and include those screenshots into the final documentation.