Robot File Syntax, Sections, Tables, Whitespace, and Parsing Rules: Guided Hands-On Workflow

1. Setup and preflight

Create a new disposable directory rather than editing an existing project. The lab should be safe to delete as one unit. Reconfirm interpreter and framework ownership before writing source; otherwise a version mismatch can be mistaken for a grammar issue.

mkdir rf-syntax-lab
cd rf-syntax-lab
python -m robot --version
python --version

On Windows PowerShell the same python -m robot form works when python resolves to the Chapter 02 virtual environment. If your installation uses the Python launcher, use py -m robot consistently and record that fact in the evidence packet.

2. Create the smallest useful suite

Start with a file that shows four section responsibilities without introducing external libraries. BuiltIn is available automatically, so Log and Should Be Equal keep the example focused on parsing rather than installation.

*** Settings ***
Documentation    Syntax laboratory: minimal suite.

*** Variables ***
${MESSAGE}    parser-visible value

*** Test Cases ***
Minimal Parseable Test
    Log    ${MESSAGE}
    Should Be Equal    ${MESSAGE}    parser-visible value

*** Keywords ***
Echo Value
    [Arguments]    ${value}
    Log    ${value}

Save it as minimal.robot. The section headers occupy the first cell. The test name also starts in the first cell. Body keyword calls are indented one conventional cell, and keyword arguments are separated by four spaces.

3. Dry-run establishes executable structure without normal actions

python -m robot --dryrun --outputdir results/minimal minimal.robot

Expected evidence: the console reports one test and a PASS status if keyword resolution succeeds; the explicit output directory contains output.xml, log.html, and report.html. Dry-run does not execute ordinary keyword behavior, so it is ideal for proving that the suite is structurally executable before connecting to any external system.

4. Prove grammar and style are different

Create two_spaces.robot using exactly two spaces at cell boundaries. It is deliberately not the preferred style, but it should remain parser-valid.

*** Test Cases ***
Two Space Example
  Log  two spaces are grammar-valid
  Should Be Equal  ok  ok

python -m robot --dryrun --outputdir results/two-spaces two_spaces.robot

Record the successful dry-run and then reformat the same rows to four spaces. The functional result should remain the same. This is an evidence-based way to teach the distinction: style improves consistency; grammar decides whether cells can be recognized.

5. Create an equivalent pipe-separated test

Now express the same intent with visible pipe boundaries. Save the following as pipe.robot.

| *** Test Cases *** |
| Pipe Example        |
|                     | Log             | pipe cell boundaries |
|                     | Should Be Equal | ok | ok |

Run it with an explicit result directory. Notice that the leading pipe is significant: it tells the parser to use pipe-separated rules for that row. The visually aligned columns are for humans; semantic correctness comes from the pipe cell boundaries.

python -m robot --dryrun --outputdir results/pipe pipe.robot

6. Separate reusable content into a resource file

Create helpers.resource. Resource files use the same high-level tabular syntax but cannot contain tests/tasks. This one defines a variable and a reusable keyword.

*** Settings ***
Documentation    Shared syntax-lab helpers.

*** Variables ***
${RESOURCE VALUE}    from resource

*** Keywords ***
Log Resource Value
    Log    ${RESOURCE VALUE}

Then create uses_resource.robot and import it through the Settings section:

*** Settings ***
Resource    helpers.resource

*** Test Cases ***
Resource Import Is Resolved
    Log Resource Value

python -m robot --dryrun --outputdir results/resource uses_resource.robot

The resource owns reusable keyword/variable definitions; the suite owns the executable test. This file boundary becomes much more important in Chapter 12, but the parser distinction belongs here.

7. Continuations and comments: inspect logical statements

*** Settings ***
Documentation    First physical line of one logical documentation statement
...              second physical line of the same statement.

*** Test Cases ***
Continuation And Comment
    # This row is commentary and does not call a keyword.
    Log    ordinary executable row

Save as continuation.robot. The continuation row begins with ... and extends the preceding statement. Do not insert unrelated code between a statement and its continuation. A comment is not a substitute for a continuation and vice versa.

8. Inspect the parsed model with the public API

Create inspect_model.py. This is a source-inspection tool, not a custom Robot library, so it imports the documented public parsing API.

from pathlib import Path
from robot.api.parsing import ModelVisitor, get_model

class Reporter(ModelVisitor):
    def generic_visit(self, node):
        if node.errors:
            for error in node.errors:
                print(f"ERROR line {node.lineno}: {error}")
        ModelVisitor.generic_visit(self, node)

path = Path("minimal.robot")
model = get_model(path)
print(f"source={model.source}")
for section in model.sections:
    print(f"section={type(section).__name__} lines={section.lineno}-{section.end_lineno}")
Reporter().visit(model)

python inspect_model.py

Expected observations include a root file model and section node names such as SettingSection, VariableSection, TestCaseSection, and KeywordSection. The exact AST details are tooling-oriented; the learning objective is to prove that the parser exposes structure independently of a real test run.

9. Break three files deliberately — and classify the failures

Create failures only in this disposable directory and keep a copy of the original text before repair.

Case A — malformed section header

*** Test Case **
Broken Header
    Log    never classified under a valid Test Cases section

This is an early source/model problem. The header spelling/marker structure is not a recognized section header.

Case B — one-space “separator”

*** Test Cases ***
One Space Trap
    Log one-argument

This is the important nuance from Lesson 1: the row can become one keyword-name cell. The parser may build a test, while dry-run reports that the combined keyword name cannot be found. The failure is real, but it occurs later than a malformed section.

Case C — orphan continuation

*** Test Cases ***
Broken Continuation
    ...    no preceding keyword statement to continue

A continuation only has meaning as part of a preceding logical statement. Use the parser model and dry-run output to record exactly how the current stable version reports the problem; do not invent a generic “syntax error” label when the tool provides a more specific diagnostic.

10. Repair, verify, and preserve before/after evidence

Repair only the smallest cause. Do not change the Python path, reinstall Robot Framework, or delete result artifacts for a source-grammar issue. For each specimen, keep:

• the broken source;
• the exact validation command;
• the first diagnostic;
• the repaired source;
• the second validation result;
• a one-sentence classification: token/section, model/block, keyword resolution, or runtime.

This evidence discipline scales directly to CI triage: a reviewer can see both what failed and why the chosen repair was minimal.

11. Small challenge: choose the correct layer

You receive three reports: (1) “Unrecognized section header,” (2) “No keyword with name ‘Log hello’ found,” and (3) “HTTP connection refused.” Without changing any files, rank the first inspection layer for each.

A correct answer starts with parser/model inspection for (1), cell/keyword resolution for (2), and only reaches external-system/network diagnosis for (3) after source/import/keyword validation has already succeeded.

12. Knowledge check

13. Summary and next step

You have created valid space-separated, pipe-separated, continued, and resource sources; proved parser-versus-style behavior; inspected the model through the public API; and repaired failures without touching unrelated runtime layers.

Lesson 3 uses this evidence to make design decisions: when to choose pipe format, how much alignment is enough, when comments become documentation, and where static validation stops.

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.