Robot File Syntax, Sections, Tables, Whitespace, and Parsing Rules: Core Concepts and Mental Model

1. Why parser literacy matters

A Robot Framework file looks like readable prose, but the runtime does not execute prose. It first interprets the file as structured tabular data. A few invisible spaces can therefore change where one cell ends and another begins, which section owns a statement, or whether a line is a test name, a keyword call, a continuation, or unrecognized data.

This is operationally important. If a suite never forms a valid model, there is no browser, API, database, SSH connection, or RPA workflow to debug yet. Parser literacy lets you stop at the earliest failing layer instead of restarting services, changing network settings, or adding retries to a source-structure problem.

2. Mental model: source text → model → execution

flowchart TD
A[UTF-8 source file] --> B[Physical lines]
B --> C[Cells and tokens]
C --> D[Section context]
D --> E[Statements and blocks]
E --> F[Parsed AST model]
F --> G[Executable suite/resource model]
G --> H[Keyword resolution]
H --> I[Runtime result]
I --> J[output.xml / log.html / report.html]

The parser starts with source text and separates it into tokens. Section headers such as *** Test Cases *** establish the grammar for following rows. Statements and blocks are then assembled into a model. The public parsing API exposes that model as an AST-like structure. Execution is a later phase: keyword resolution and external actions happen only after the source is accepted sufficiently to build an executable structure.

This separation explains why two broken files can fail differently. A misspelled section header can be reported while tokenizing/modeling. A correctly parsed keyword row with the wrong keyword name can survive parsing but fail in dry-run or execution during keyword resolution.

3. Sections define what a row means

Section headers are not decoration. They change how the rows underneath are interpreted. A row that is valid under *** Variables *** may be meaningless under *** Test Cases ***. Learn the section boundary before memorizing individual keywords.

A plain .robot suite may contain tests or tasks. A resource file is for reusable variables, keywords, documentation, and imports; it cannot contain tests/tasks. Keeping those responsibilities separate gives later import and suite-architecture chapters a clean foundation.

4. Cell boundaries: parser minimum versus team style

In the normal space-separated format, Robot Framework recognizes two or more spaces (or one or more tab characters) as a cell separator. The current community style guide recommends four spaces because cell boundaries are easier for humans and code review tools to see. Those are different rules: two spaces is grammar; four spaces is style.

*** Test Cases ***
Parser Valid With Two Spaces
  Log  accepted by the parser

Recommended Four Space Style
    Log    easier cell boundaries for humans

5. Pipe-separated format is an alternative grammar

Pipe-separated rows are useful when arguments themselves contain many spaces or when explicit column boundaries improve readability. A pipe row is recognized by a leading pipe. Pipes separating cells must be surrounded by whitespace except at the line boundaries. Space-separated and pipe-separated rows can coexist, although a team should normally choose a consistent style within a file.

| *** Test Cases *** |
| Pipe Example        |
|                     | Log | value with ordinary spaces |

The pipe characters are syntax, not merely a visual table. Removing the leading pipe changes how the line is tokenized. Conversely, aligning every pipe into a visually perfect grid is optional; readability should not become a maintenance burden.

6. Indentation is an empty first cell, not Python whitespace

Robot Framework is tabular, not Python. In a test case or keyword body, indentation normally means the first cell is empty and the keyword call begins in the next cell. Four spaces is the common style because it creates one visible empty-cell boundary. Nested native control structures add further indentation, but the parser is reasoning in cells and block structure rather than Python indentation tokens.

*** Test Cases ***
Readable Structure
    Log    first body row
    IF    ${True}
        Log    nested body row
    END

A test name begins in the first cell. A body row does not. This is why accidental left alignment can cause ordinary text to become a new test or keyword definition. Chapter 10 will teach the control structures themselves; here the key concept is that indentation and section context decide how the parser classifies a row.

7. Physical lines, continuations, and comments

A logical Robot statement can span multiple physical lines. A continuation row begins with ... in the first data cell and extends the preceding statement. The parser’s public token API distinguishes end-of-line from end-of-statement, which is why continuation rows remain part of one logical statement.

*** Settings ***
Documentation    This suite demonstrates a long logical statement
...              continued on another physical line.

*** Test Cases ***
Comment Example
    # This whole row is a comment in the test body.
    Log    executable row

Continuation is valuable when one statement is genuinely long. It is not a substitute for decomposing a procedural mega-keyword. Comments should explain intent or non-obvious constraints; durable user-facing explanation belongs in documentation fields and later in library/test documentation conventions.

8. Suite files, resource files, and other supported formats

The normal suite extension is .robot. Reusable resources should use .resource; current guidance recommends that dedicated extension, and resource files cannot contain tests or tasks. Text data is UTF-8. Robot Framework also supports reStructuredText-backed .robot.rst sources and JSON .rbt data, but those formats solve specialized documentation/tooling cases rather than improving an ordinary beginner project.

9. Read-only inspection before mutation

Chapter 02 established interpreter and package provenance. Keep that habit. Before repairing a suspicious file, first record the Robot version and inspect it without touching an external system. --dryrun validates suites and keyword resolution without executing normal keywords, while the public parsing API lets tools inspect tokens and the AST model directly.

python -m robot --version
python -m robot --dryrun --outputdir results syntax_example.robot

from robot.api.parsing import get_model

model = get_model("syntax_example.robot")
print(type(model).__name__)
for section in model.sections:
    print(type(section).__name__, section.lineno, section.end_lineno)

Dry-run is non-destructive with respect to ordinary test keywords, but it still parses imports and creates result artifacts when configured. The parsing API is even narrower: it can inspect source structure without building your domain integrations. In both cases, store evidence under a disposable project directory.

10. Why this matters in DevOps

Automation is often used as a release gate. A parser failure should therefore be classified differently from a failed assertion, a missing library, or an unavailable service. When CI can report “syntax/model validation failed before runtime,” teams route the incident to the right owner and avoid unnecessary infrastructure changes.

Parser literacy also improves reviews. Reviewers can distinguish a grammar requirement from a style preference, enforce a stable team format without claiming that alternative formatting is invalid, and recognize when a source change alters suite structure rather than only appearance.

11. Knowledge check

12. Summary and next step

You can now separate the source layers: physical text becomes cells and tokens; section context turns tokens into statements and blocks; the parsed model precedes keyword resolution and runtime execution. You also know the critical grammar/style distinction: two spaces are enough for the parser, while four are the current human-facing recommendation.

Lesson 2 turns that model into a disposable syntax laboratory where valid and broken files are inspected with --dryrun and robot.api.parsing.

Further reading

• Robot Framework User Guide — source formats, data syntax, sections, resource files, execution, and parser semantics.
• Robot Framework 7.4.2 public API documentation — robot.api.parsing, tokens, AST models, visitors, and error reporting.
• Robot Framework Style Guide — current community formatting guidance, including four-space cell separation.
• Robot Framework on PyPI — stable/pre-release and supported-Python verification.