Robot File Syntax, Sections, Tables, Whitespace, and Parsing Rules: Diagnostics, Failure Modes, and Production Practices

1. Failure taxonomy: stop at the earliest broken layer

flowchart TD
A[Source file] --> B{Token/section valid?}
B -- no --> B1[Header/token error]
B -- yes --> C{Model/block valid?}
C -- no --> C1[Control/continuation/model error]
C -- yes --> D{Imports + keyword names resolve?}
D -- no --> D1[Import/keyword resolution failure]
D -- yes --> E{Runtime keyword succeeds?}
E -- no --> E1[Robot/library runtime failure]
E -- yes --> F{External state meets assertion?}
F -- no --> F1[System-under-automation failure]
F -- yes --> G[PASS]

The key production habit is to classify before changing. A malformed section header cannot be repaired with a longer timeout. A missing keyword cannot be repaired by restarting a database. An HTTP outage is not a parser incident merely because the test is written in a .robot file.

2. Diagnostic sequence

1. Preserve the first failure: source file, command, console output, and result directory.
2. Confirm versions: Robot/Python and any editor/tool involved.
3. Confirm path and selection: prove which file was parsed.
4. Inspect tokens/model: section headers, cell boundaries, continuation/block errors.
5. Inspect imports and keyword resolution: only after source structure is credible.
6. Inspect runtime/library/external state: only when earlier layers pass.
7. Repair the smallest cause and rerun the smallest controlled slice.

This order protects evidence and makes the eventual fix explainable in code review.

3. Failure mode: single-space cell collapse

*** Test Cases ***
Single Space Trap
    Log hello

The visual intent is “call Log with argument hello.” With only one space, the parser may see one cell containing Log hello. That can be structurally acceptable as a keyword call but fails keyword resolution because BuiltIn has no keyword with that combined name.

Minimal repair: restore an actual cell separator:

*** Test Cases ***
Single Space Repaired
    Log    hello

Do not reinstall BuiltIn, add a custom keyword named Log hello, or change Python paths. The evidence points to a source cell-boundary error.

4. Failure mode: malformed or unknown section header

*** Test Case **
Broken Header
    Log    unreachable under intended section

Unknown/unrecognized data can be reported during tokenization/model construction. Inspect the original exact characters first: number of asterisks, section spelling, and any invisible Unicode whitespace. Correct the header to a recognized stable section such as *** Test Cases ***.

5. Failure mode: broken native control-block structure

Native IF/FOR/WHILE/TRY syntax forms model blocks. Some failures are therefore model-validation errors rather than token errors. This chapter does not teach control-flow behavior yet; it only teaches how to recognize that block structure is a parser/model concern.

*** Test Cases ***
Broken Block
    IF    ${True}
        Log    branch body
    # END is deliberately missing

Use model errors or dry-run to capture the exact stable-version diagnostic. The repair is to restore valid block structure, not to wrap the file in a broad TRY/EXCEPT or retry the suite.

6. Failure mode: broken continuation ownership

*** Test Cases ***
Continuation Trap
    ...    argument without a statement to continue

A continuation row extends a preceding logical statement. When ownership is absent or the row appears in an invalid context, the model reports a structural problem. Repair the underlying statement structure; do not convert the continuation marker into ordinary text to silence the error.

7. Failure mode: tabs and invisible whitespace

Tabs can be valid Robot separators, which is exactly why mixed whitespace can be confusing: two rows that look aligned may be tokenized differently by an editor, formatter, or review view. Non-ASCII spaces are preserved rather than silently normalized by modern Robot Framework.

Diagnostic approach: enable whitespace visualization in the editor, inspect a preserved copy, and if necessary inspect token values/column offsets with the public parsing API. Then normalize the project to a documented visible-space policy.

# Example policy for new source (not a Robot setting):
# - UTF-8
# - spaces, not tabs
# - four spaces between cells
# - no trailing whitespace

8. Failure mode: mixing stable and pre-release syntax

A developer experimenting with a pre-release may commit syntax or semantics unavailable on the project’s stable pin. The wrong fix is “upgrade CI to whatever is latest.” First confirm the repository’s supported version and the official release status of the feature.

For this course, stable Robot Framework 7.4.2 is the authority. Robot Framework 7.5b1 is explicitly a pre-release. New syntax must not become mandatory course code until it is part of the chosen stable baseline and the project intentionally upgrades.

9. Public parsing-API error reporter

The stable public model exposes an errors attribute on nodes. Create report_errors.py to inspect a suspect file without importing private parser implementation modules.

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

class ErrorReporter(ModelVisitor):
    def generic_visit(self, node):
        if node.errors:
            location = getattr(node, "lineno", "?")
            for error in node.errors:
                print(f"line {location}: {error}")
        ModelVisitor.generic_visit(self, node)

path = Path("suspect.robot")
model = get_model(path)
ErrorReporter().visit(model)

This reporter can surface both Error nodes created from unrecognized data and syntax errors attached to normal model nodes. It remains an inspection tool: it does not prove keyword runtime or external-system correctness.

10. Preserve first-failure artifacts

Run dry-run into a uniquely named evidence directory rather than overwriting the only copy of earlier results:

python -m robot --dryrun --outputdir evidence/first-failure suspect.robot

Keep the source hash or untouched copy, exact command, Robot/Python versions, console output, and generated result artifacts. If a repair is attempted, write the second run to a different directory such as evidence/after-repair. This prevents a successful rerun from erasing the original diagnostic context.

11. Troubleshooting shortcuts to reject

• Blanket retry: deterministic syntax does not become correct on a second attempt.
• Giant timeout: parsing is not waiting on an application-ready condition.
• Broad EXCEPT: control-flow recovery cannot repair a file that fails before execution reaches the intended block.
• Arbitrary PYTHONPATH changes: only appropriate when evidence identifies import-path ownership, not whitespace or section grammar.
• Deleting results: destroys the evidence needed for comparison.
• Production experiments: syntax can be diagnosed locally; there is no reason to point a broken parser lab at a real target.

12. Performance: keep causality honest

Syntax incidents are usually correctness incidents, not tuning problems. When performance is relevant, distinguish parse/discovery time from imports, library initialization, keyword runtime, external latency, output generation, parallel scheduling, and CI startup. Do not “optimize” a parsing problem by disabling validation or shrinking evidence.

13. Knowledge check

14. Summary and next step

You now have a production diagnostic sequence for Robot source: preserve, classify, inspect the model, repair minimally, and only then move downstream. Syntax, keyword resolution, runtime, and external-system incidents are separate failure domains.

Lesson 5 consolidates the chapter into a checkpoint laboratory with multiple valid and invalid specimens, prediction before execution, repairs, and a team-ready grammar-versus-style checklist.

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.