At work, we have been using Robot Framework for all kinds of tests for a few years now and it’s proven to be the good choice. Robot Framework’s simple syntax and grammar does not scare testers away (usually). At the same time, its design makes it easy to support complex use cases as well as simple ones through the power of the Python programming language.
One blind spot however, in my opinion anyway, is the way Robot Framework let you document your tests. It provides a section for this, with basic HTML support but it has always felt limited and not really friendly.
Luckily, in the recent releases, the Robot Framework developers have provided a built-in support for reStructuredText. Not that the documentation section supports this syntax, but instead, you can embed Robot Framework tests into a reStructuredText document, and therefore into Sphinx as well.
The gain isn’t so much visible in the Robot Framework reports since the reStructuredText sections won’t appear in those, but it means you can generate HTML documents which embed executable tests. Fans of doctests will be in known territory.
I think this is a powerful combination as it bridges the tests with the specifications and ensure they are both kept locally at the same place, imrpoving their chance to stay synchronised. In my mind, it provides a great framework to follow the Specification by Example that Gojko Adzic described so eloquently.
Here is a simple:
- The sphinx documentation.
- The Robot Framework log result for the embedded test.
Finally, a related powerful extension provides a simple mechanism to include Robot Framework tests into Sphinx documentation. We use it extensively at work as we wanted to keep our tests outside in distinct files without losing the ability to see them embedded into the generated HTML documentation.
