2.1 Test data syntax

This section covers Robot Framework's overall test data syntax. The following sections will explain how to actually create test cases, test suites and so on.

2.1.1 Files and directories

The hierarchical structure for arranging test cases is built as follows:

Test cases are created in test case files.
A test case file automatically creates a test suite containing the test cases in that file.
A directory containing test case files forms a higher-level test suite. Such a test suite directory has suites created from test case files as its sub test suites.
A test suite directory can also contain other test suite directories, and this hierarchical structure can be as deeply nested as needed.
Test suite directories can have a special initialization file.

In addition to this, there are:

Test libraries containing the lowest-level keywords.
Resource files with variables and higher-level user keywords.
Variable files to provide more flexible ways to create variables than resource files.

Robot Framework test data is defined in tabular format, using either hypertext markup language (HTML), tab-separated values (TSV), plain text, or reStructuredText (reST) formats. The details of these formats, as well as the main benefits and problems with them, are explained in the subsequent sections. Which format to use depends on the context, but the plain text format is recommended if there are no special needs.

Robot Framework selects a parser for the test data based on the file extension. The extension is case-insensitive, and the recognized extensions are .html, .htm and .xhtml for HTML, .tsv for TSV, .txt and special .robot for plain text, and .rst and .rest for reStructuredText.

Different test data templates are available for HTML and TSV formats to make it easier to get started writing tests.

Note

The special .robot extension with plain text files is supported starting from Robot Framework 2.7.6.

HTML format

HTML files support formatting and free text around tables. This makes it possible to add additional information into test case files and allows creating test case files that look like formal test specifications. The main problem with HTML format is that editing these files using normal text editors is not that easy. Another problem is that HTML does not work as well with version control systems because the diffs resulting from changes contain HTML syntax in addition to changes to the actual test data.

In HTML files, the test data is defined in separate tables (see the example below). Robot Framework recognizes these test data tables based on the text in their first cell. Everything outside recognized tables is ignored.

Using the HTML format
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!

Keyword	Action	Argument	Argument
My Keyword	[Arguments]	${path}
	Directory Should Exist	${path}

Editing test data

Test data in HTML files can be edited with whichever editor you prefer, but a graphic editor, where you can actually see the tables, is recommended. RIDE can read and write HTML files, but unfortunately it loses all HTML formatting and also possible data outside test case tables.

Encoding and entity references

HTML entity references (for example, ä) are supported. Additionally, any encoding can be used, assuming that it is specified in the data file. Normal HTML files must use the META element as in the example below:

XHTML files should use the XML preamble as in this example:

<?xml version="1.0" encoding="Big5"?>

If no encoding is specified, Robot Framework uses ISO-8859-1 by default.

TSV format

TSV files can be edited in spreadsheet programs and, because the syntax is so simple, they are easy to generate programmatically. They are also pretty easy to edit using normal text editors and they work well in version control, but the plain text format is even better suited for these purposes.

The TSV format can be used in Robot Framework's test data for all the same purposes as HTML. In a TSV file, all the data is in one large table. Test data tables are recognized from one or more asterisks (*), followed by a normal table name and an optional closing asterisks. Everything before the first recognized table is ignored similarly as data outside tables in HTML data.

Using the TSV format
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!


Keyword	Action	Argument	Argument
My Keyword	[Arguments]	${path}
	Directory Should Exist	${path}

Editing test data

You can create and edit TSV files in any spreadsheet program, such as Microsoft Excel. Select the tab-separated format when you save the file and remember to set the file extension to .tsv. It is also a good idea to turn all automatic corrections off and configure the tool to treat all values in the file as plain text.

TSV files are relatively easy to edit with any text editor, especially if the editor supports visually separating tabs from spaces. The TSV format is also supported by RIDE.

Robot Framework parses TSV data by first splitting all the content into rows and then rows into cells on the basis of the tabular characters. Spreadsheet programs sometimes surround cells with quotes (for example, "my value") and Robot Framework removes them. Possible quotes inside the data are doubled (for example, "my ""quoted"" value") and also this is handled correctly. If you are using a spreadsheet program to create TSV data, you should not need to pay attention to this, but if you create data programmatically, you have to follow the same quoting conventions as spreadsheets.

Encoding

TSV files are always expected to use UTF-8 encoding. Because ASCII is a subset of UTF-8, plain ASCII is naturally supported too.

Plain text format

The plain texts format is very easy to edit using any text editor and they also work very well in version control. Because of these benefits it has became the most used data format with Robot Framework.

The plain text format is technically otherwise similar to the TSV format but the separator between the cells is different. The TSV format uses tabs, but in the plain text format you can use either two or more spaces or a pipe character surrounded with spaces (|).

The test data tables must have one or more asterisk before their names similarly as in the TSV format. Otherwise asterisks and possible spaces in the table header are ignored so, for example, Settings and *Settings work the same way. Also similarly as in the TSV format, everything before the first table is ignored.

In plain text files tabs are automatically converted to two spaces. This allows using a single tab as a separator similarly as in the TSV format. Notice, however, that in the plain text format multiple tabs are considered to be a single separator whereas in the TSV format every tab would be a separator.

Space separated format

The number of spaces used as separator can vary, as long as there are at least two spaces, and it is thus possible to align the data nicely. This is a clear benefit over editing the TSV format in a text editor because with TSV the alignment cannot be controlled.

* 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!

* Keywords *

My Keyword

[Arguments] ${path}

Directory Should Exist ${path}

Because space is used as separator, all empty cells must be escaped with ${EMPTY} variable or a single backslash. Otherwise handling whitespace is not different than in other test data because leading, trailing, and consecutive spaces must always be escaped.

Tip

It is recommend to use four spaces between keywords and arguments.

Pipe and space separated format

The biggest problem of the space delimited format is that visually separating keywords form arguments can be tricky. This is a problem especially if keywords take a lot of arguments and/or arguments contain spaces. In such cases the pipe and space delimited variant can work better because it makes the cell boundary more visible.

| Setting | Value |

| Library | OperatingSystem |

| Variable | Value |

| ${MESSAGE} | Hello, world! |

| Test Case | Action | Argument |

| My Test | [Documentation] | Example test |

| | Log | ${MESSAGE} |

| | My Keyword | /tmp |

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

| Keyword |

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

| | Directory Should Exist | ${path}

A plain text file can contain test data in both space-only and space-and-pipe separated formats, but a single line must always use the same separator. Pipe and space separated lines are recognized by the mandatory leading pipe, but the pipe at the end of the line is optional. There must always be at least one space on both sides of the pipe (except at the beginning and end) but there is no need to align the pipes other than if it makes the data more clear.

There is no need to escape empty cells (other than the trailing empty cells) when using the pipe and space separated format. The only thing to take into account is that possible pipes surrounded by spaces in the actual test data must be escaped with a backslash:

| Escaping Pipe | ${file count} = | Execute Command | ls -1 *.txt | wc -l |

| | Should Be Equal | ${file count} | 42 |

Editing and encoding

One of the biggest benefit of the plain text format over HTML and TSV is that editing it using normal text editors is very easy. Many editors and IDEs (at least Eclipse, Emacs, Vim, and TextMate) also have plugins that support syntax highlighting Robot Framework test data and may also provide other features such as keyword completion. The plain text format is also supported by RIDE.

Similarly as with the TSV test data, plain text files are always expected to use UTF-8 encoding. As a consequence also ASCII files are supported.

Recognized extensions

Starting from Robot Framework 2.7.6, it is possible to save plain text test data files using a special .robot extension in addition to the normal .txt extension. The new extension makes it easier to distinguish test data files from other plain text files.

reStructuredText format

reStructuredText (reST) is an easy-to-read plain text markup syntax that is commonly used for documentation of Python projects (including Python itself, as well as this User Guide). reST documents are most often compiled to HTML, but also other output formats are supported.

Using reST with Robot Framework allows you to mix richly formatted documents and test data in a concise text format that is easy to work with using simple text editors, diff tools, and source control systems. In practice it combines many of the benefits of plain text and HTML formats.

When using reST files with Robot Framework, there are two ways to define the test data. Either you can use code blocks and define test cases in them using the plain text format or alternatively you can use tables exactly like you would with the HTML format.

Note

Using reST files with Robot Framework requires the Python docutils module to be installed.

2.1 Test data syntax