Install python-docutils

Installing python-docutils package on Ubuntu 12.04 (Precise Pangolin) is as easy as running the following command on terminal:

sudo apt-get update

sudo apt-get install python-docutils

Using code blocks

reStructuredText documents can contain code examples in so called code blocks. When these documents are compiled into HTML or other formats, the code blocks are syntax highlighted using Pygments. In standard reST code blocks are started using the code directive, but Sphinx uses code-block or sourcecode instead. The name of the programming language in the code block is given as an argument to the directive. For example, following code blocks contain Python and Robot Framework examples, respectively:

.. code:: python

def example_keyword():

print 'Hello, world!'

.. code:: robotframework

* Test Cases *

Example Test

Example Keyword

When Robot Framework parses reStructuredText files, it first searches for possible code, code-block or sourcecode blocks containing Robot Framework test data. If such code blocks are found, data they contain is written into an in-memory file and executed. All data outside the code blocks is ignored.

The test data in the code blocks must be defined using the plain text format. As the example below illustrates, both space and pipe separated variants are supported:

Example

This text is outside code blocks and thus ignored.

.. code:: robotframework

* Settings *

Library OperatingSystem

* Variables *

${MESSAGE} Hello, world!

* Test Cases *

My Test

[Documentation] Example test

Log ${MESSAGE}

My Keyword /tmp

Another Test

Should Be Equal ${MESSAGE} Hello, world!

Also this text is outside code blocks and ignored. Above block used

the space separated plain text format and the block below uses the pipe

separated variant.

.. code:: robotframework

| * Keyword * | | |

| My Keyword | [Arguments] | ${path} |

| | Directory Should Exist | ${path} |

Note

Escaping using the backslash character works normally in this format. No double escaping is needed like when using reST tables.

Note

Support for test data in code blocks is a new feature in Robot Framework 2.8.2.

Using tables

If a reStructuredText document contains no code blocks with Robot Framework data, it is expected to contain the data in tables similarly as in the HTML format. In this case Robot Framework compiles the document to HTML in memory and parses it exactly like it would parse a normal HTML file.

Robot Framework identifies test data tables based on the text in the first cell and all content outside of the recognized table types is ignored. An example of each of the four test data tables is shown below using both simple table and grid table syntax:

Example

This text is outside tables and thus ignored.

============ ================ ======= =======

Setting Value Value Value

============ ================ ======= =======

Library OperatingSystem

============ ================ ======= =======

============ ================ ======= =======

Variable Value Value Value

============ ================ ======= =======

${MESSAGE} Hello, world!

============ ================ ======= =======

============= ================== ============ =============

Test Case Action Argument Argument

============= ================== ============ =============

My Test [Documentation] Example test

\ Log ${MESSAGE}

\ My Keyword /tmp

\

Another Test Should Be Equal ${MESSAGE} Hello, world!

============= ================== ============ =============

Also this text is outside tables and ignored. Above tables are created

using the simple table syntax and the table below uses the grid table

approach.

+-------------+------------------------+------------+------------+

| Keyword | Action | Argument | Argument |

+-------------+------------------------+------------+------------+

| My Keyword | [Arguments] | ${path} | |

+-------------+------------------------+------------+------------+

| | Directory Should Exist | ${path} | |

+-------------+------------------------+------------+------------+

Note

Empty cells in the first column of simple tables need to be escaped. The above example uses \ but .. could also be used.

Note

Because the backslash character is an escape character in reST, specifying a backslash so that Robot Framework will see it requires escaping it with an other backslash like \. For example, a new line character must be written like \n. Because the backslash is used for escaping also in Robot Framework data, specifying a literal backslash when using reST tables requires double escaping like c:\\temp.

Generating HTML files based on reST files every time tests are run obviously adds some overhead. If this is a problem, it can be a good idea to convert reST files to HTML using external tools separately, and let Robot Framework use the generated files only.

Editing and encoding

Test data in reStructuredText files can be edited with any text editor, and many editors also provide automatic syntax highlighting for it. reST format is not supported by RIDE, though.

Robot Framework requires reST files containing non-ASCII characters to be saved using UTF-8 encoding.

Syntax errors in reST source files

If a reStructuredText document is not syntactically correct (a malformed table for example), parsing it will fail and no test cases can be found from that file. When executing a single reST file, Robot Framework will show the error on the console. When executing a directory, such parsing errors will generally be ignored.

2.1.3 Test data tables

Test data is structured in four types of tables listed below. These test data tables are identified by the first cell of the table, and the last column in the table below lists different aliases that can be used as a table name.

2.1.4 Rules for parsing the data

Ignored data

When Robot Framework parses the test data, it ignores:

• All tables that do not start with a recognized table name in the first cell.
• Everything else on the first row of a table apart from the first cell.
• All data before the first table. If the data format allows data between tables, also that is ignored.
• All empty rows, which means these kinds of rows can be used to make the tables more readable.
• All empty cells at the end of rows, unless they are escaped.
• All single backslashes () when not used for escaping.
• All characters following the hash character (#), when it is the first character of a cell. This means that hash marks can be used to enter comments in the test data.
• All formatting in the HTML/reST test data.

When Robot Framework ignores some data, this data is not available in any resulting reports and, additionally, most tools used with Robot Framework also ignore them. To add information that is visible in Robot Framework outputs, place it to the documentation or other metadata of test cases or suites, or log it with the BuiltIn keywords Log or Comment.

Handling whitespace

Robot Framework handles whitespace the same way as they are handled in HTML source code:

• Newlines, carriage returns, and tabs are converted to spaces.
• Leading and trailing whitespace in all cells is ignored.
• Multiple consecutive spaces are collapsed into a single space.

In addition to that, non-breaking spaces are replaced with normal spaces. This is done to avoid hard-to-debug errors when a non-breaking space is accidentally used instead of a normal space.

If leading, trailing, or consecutive spaces are needed, they must be escaped. Newlines, carriage returns, tabs, and non-breaking spaces can be created using escape sequences \n, \r, \t, and \xA0 respectively.

Escaping

The escape character in Robot Framework test data is the backslash () and additionally built-in variables ${EMPTY} and ${SPACE} can often be used for escaping. Different escaping mechanisms are discussed in the sections below.

Escaping special characters

The backslash character can be used to escape special characters so that their literal values are used.

Forming escape sequences

The backslash character also allows creating special escape sequences that are recognized as characters that would otherwise be hard or impossible to create in the test data.

Note

All strings created in the test data, including characters like \x02, are Unicode and must be explicitly converted to byte strings if needed. This can be done, for example, using Convert To Bytes or Encode String To Bytes keywords in BuiltIn and String libraries, respectively, or with something like str(value) or value.encode('UTF-8') in Python code.

Note

If invalid hexadecimal values are used with \x, \u or \U escapes, the end result is the original value without the backslash character. For example, \xAX (not hex) and \U00110000 (too large value) result with xAX and U00110000, respectively. This behavior may change in the future, though.

Note

Built-in variable ${\n} can be used if operating system dependent line terminator is needed (\r\n on Windows and \n elsewhere).

Note

Possible un-escaped whitespace character after the \n is ignored. This means that two lines\nhere and two lines\n here are equivalent. The motivation for this is to allow wrapping long lines containing newlines when using the HTML format, but the same logic is used also with other formats. An exception to this rule is that the whitespace character is not ignored inside the extended variable syntax.

Note

\x, \u and \U escape sequences are new in Robot Framework 2.8.2.

Prevent ignoring empty cells

If empty values are needed as arguments for keywords or otherwise, they often need to be escaped to prevent them from being ignored. Empty trailing cells must be escaped regardless of the test data format, and when using the space separated format all empty values must be escaped.

Empty cells can be escaped either with the backslash character or with built-in variable ${EMPTY}. The latter is typically recommended as it is easier to understand. An exception to this recommendation is escaping the indented cells in for loops with a backslash when using the space separated format. All these cases are illustrated in the following examples first in HTML and then in the space separated plain text format:

* Test Cases *

Using backslash

Do Something first arg \

Using ${EMPTY}

Do Something first arg ${EMPTY}

Non-trailing empty

Do Something ${EMPTY} second arg # Escaping needed in space separated format

For loop

:FOR ${var} IN @{VALUES}

\ Log ${var} # Escaping needed here too

Prevent ignoring spaces

Because leading, trailing, and consecutive spaces in cells are ignored, they need to be escaped if they are needed as arguments to keywords or otherwise. Similarly as when preventing ignoring empty cells, it is possible to do that either using the backslash character or using built-in variable${SPACE}.

As the above examples show, using the ${SPACE} variable often makes the test data easier to understand. It is especially handy in combination with the extended variable syntax when more than one space is needed.

Dividing test data to several rows

If there is more data than readily fits a row, it possible to use ellipsis (...) to continue the previous line. In test case and user keyword tables, the ellipsis must be preceded by at least one empty cell. In settings and variable tables, it can be placed directly under the setting or variable name. In all tables, all empty cells before the ellipsis are ignored.

Additionally, values of settings that take only one value (mainly documentations) can be split to several columns. These values will be then catenated together with spaces when the test data is parsed. Starting from Robot Framework 2.7, documentation and test suite metadata split into multiple rows will be catenated together with newlines.

All the syntax discussed above is illustrated in the following examples. In the first three tables test data has not been split, and the following three illustrate how fewer columns are needed after splitting the data to several rows.