Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 36 ยท Syntax and Test Cases

Robot File Syntax: Sections, Separators and Comments

Learn the .robot file format: the four sections, two-space separators, the pipe format, line continuation with three dots, comments and escaping.

A .robot file is plain text with a very small grammar. There are no braces or colons: structure comes from section headers, indentation and separators. Once you know these three things you can read any Robot file. This lesson also explains the mistakes that cause most first-day errors.

Sections

A file is divided into sections. A section starts with a header line made of three or more asterisks, a name, and (optionally) more asterisks:

ROBOTFRAMEWORK
*** Settings ***
Documentation    What this file is about.
Library          Collections

*** Variables ***
${GREETING}      Hello

*** Test Cases ***
Greeting is set
    Should Be Equal    ${GREETING}    Hello

*** Keywords ***
Say hello to
    [Arguments]    ${name}
    Log    ${GREETING}, ${name}!

*** Comments ***
Anything here is ignored, including notes for teammates.
Section Holds
*** Settings *** Imports (libraries, resources, variable files), documentation, setup and teardown, tags
*** Variables *** Variables available to the whole file
*** Test Cases *** The tests (or *** Tasks *** for automation)
*** Keywords *** Your own reusable keywords
*** Comments *** Free text that Robot ignores

Header names are case-insensitive, and both singular and plural forms work (*** Test Case ***). The sections may appear in any order, and each may be omitted. A file cannot mix Test Cases and Tasks. Text before the first header is ignored, so you can put a note at the top.

Separating cells

Robot reads each line as a row of cells. Two or more spaces, or a tab, separate cells:

ROBOTFRAMEWORK
Should Be Equal    ${a}    ${b}

has three cells: the keyword name and two arguments. A single space is part of a cell, which is why keyword names can contain spaces (Should Be Equal). This is the space-separated format, and it is by far the most common. Many people align cells with extra spaces for readability, which is fine.

The second format is pipe-separated: a pipe with a space on both sides.

ROBOTFRAMEWORK
| *** Test Cases ***     |
| Example                |
|    | Log               | A pipe example |

Pipes help when an argument contains runs of spaces. In pipe format the first and last pipe are optional, and a trailing pipe is allowed. Most projects stay with spaces.

Indentation

The first column is special: names that start at the left edge are definitions (a test name, a keyword name, a setting name, a variable). Indented lines are the body of the definition above them. The amount of indentation does not matter as long as the line starts with a separator, but four spaces is the convention.

ROBOTFRAMEWORK
*** Test Cases ***
Login works                  # a test name: column 1
    Open Login Page          # steps: indented
    Submit Credentials    admin    secret

Continuing a line

Use ... (three dots) at the start of a continuation line, which joins the cells to the previous row:

ROBOTFRAMEWORK
*** Test Cases ***
Long call
    Create List
    ...    first
    ...    second
    ...    third

Settings and variables continue the same way.

Comments

A cell beginning with # starts a comment that runs to the end of the line. Whole-line comments are fine anywhere, and also inside a section.

ROBOTFRAMEWORK
*** Test Cases ***
Commented example
    # this line is a comment
    Log    visible     # this part is a comment too

There is also a Comment keyword, which writes its arguments into the log, and *** Comments *** for blocks of text.

Escaping

Some characters mean something to Robot. Put a backslash before them to use them literally:

You want Write
A literal # \#
A literal ${var} instead of a variable \${var}
An empty string argument ${EMPTY} (or \)
A newline \n
A tab \t
A cell that starts with ... \...
A literal backslash \\
Leading or trailing spaces ${SPACE} or \

\n and \t are processed by Robot, so Log line one\nline two writes two lines.

Stand-in 1: splitting rows into cells

The blocks below are not Robot Framework. This one reproduces the cell-splitting rules: two or more spaces or a tab separate cells, ... continues the previous row, and # starts a comment.

Python Stand-in: tokenizing rows

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: finding the sections

Headers follow a regular pattern, so a tiny parser can split a file into sections, ignoring case, plural or singular names and trailing asterisks.

Python Stand-in: section parser

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common syntax mistakes

  • One space instead of two. Log Hello is read as a single keyword named "Log Hello". Align with at least two spaces.
  • Tabs mixed with spaces by an editor. Tabs are valid separators, but invisible. Configure your editor to show whitespace.
  • An indented test name. Test names, keyword names and setting names belong in column 1.
  • A trailing ... with nothing after it or ... on the first line of a body.
  • A comment that looks like an argument. Log # not printed has no argument; the log message is empty.
  • Forgetting the header. Anything outside a recognized section produces an error such as "Non-existing setting".

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What separates a keyword from its arguments in the usual format?

    Cells are separated by two or more spaces or a tab. A single space belongs to the cell, which allows keyword names with spaces.
  2. 2. How do you continue a long row on the next line?

    A continuation line starts with three dots after the separator, and its cells are appended to the previous row.
  3. 3. What is ${EMPTY} for?

    A cell cannot simply be blank, so ${EMPTY} (or a backslash) gives an explicit empty string.
  4. 4. Which header is valid?

    Headers are three or more asterisks around a section name. The name is case-insensitive and may be singular or plural.

Summary

  • A file has sections introduced by *** Name *** headers: Settings, Variables, Test Cases (or Tasks), Keywords, Comments.
  • Cells are separated by two or more spaces or a tab; the pipe format is an alternative.
  • Names at column 1 define things; indented lines are bodies. Use ... to continue a row and # for comments.
  • Escape special characters with a backslash; use ${EMPTY} and ${SPACE} for empty and space-only values.

Next: Writing Test Cases