Robot Framework extension for Sphinx¶

sphinxcontrib-robotframework is a Sphinx-extension, which executes embedded Robot Framework tests during sphinx-build.

sphinxcontrib-robotframework can be used in doctest way to validate examples shown in documentation or with Selenium and its Robot Framework integration, Selenium2Library, to generate scripted screenshots during the documentation compiliation time, for CI-generated up-to-date screenshots.

Examples¶

Getting started¶

Install sphinxcontrib-robotframework into your virtualenv or require it as a dependency of your Sphinx-project.

Enable the extension and execution of embedded Robot Framework tests by adding the following lines into your Sphinx-project’s conf.py:

extensions = ['sphinxcontrib_robotframework']

# Enable Robot Framework tests during Sphinx compilation
sphinxcontrib_robotframework_enabled = True

# Hide Robot Framework syntax from the Sphinx output by default
# (preferred, when you use the extension for scripted screenshots)
sphinxcontrib_robotframework_quiet = True

Write your Robot Framework tests in space separated form as contents of Docutils’ code-directives with robotframework-language:
```
.. code:: robotframework

   *** Settings ***

   ...

   *** Variables ***

   ...

   *** Test cases ***

   ...
```
Each document may contain several code-directives, but their contents are concatenated into a single Robot Framework test suite before execution.

The output of each code-directive can be omitted by setting a special :class: hidden-option. (This is not a standard Sphinx-behavior, but a hard coded feature in sphinxcontrib-robotframework.)
Compile your documentation and see your tests being run.

Note

If you choose to use Robot Framework variables in your test cases, you can override values for those variables in your Sphinx-configuration file (conf.py) with:

sphinxcontrib_robotframework_variables = {
    "VARIABLE": "value"
}

When Sphinx nitpicky mode is enabled, failing Robot Framework run will raise Sphinx Error and leave Robot Framework log files in place.