Checkpoint Lab — Robot File Syntax, Sections, Tables, Whitespace, and Parsing Rules

1. Automation charter and success criteria

The checkpoint domain is deliberately small: “prove that the team can classify Robot source before runtime.” Success is not merely making every file green. You must explain why each specimen is valid or invalid, identify the earliest failing layer, preserve the first diagnostic, repair only the cause, and document whether the final rule is grammar or team style.

2. Setup and preflight

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

Record the exact output. Confirm the directory is disposable before creating the specimen tree. If the command resolves a different environment than Chapter 02, fix environment ownership first; do not continue and later classify version mismatch as a syntax failure.

3. Create the syntax-lab tree

rf-syntax-checkpoint/
├── specimens/
│   ├── 01_valid_space.robot
│   ├── 02_valid_pipe.robot
│   ├── 03_shared.resource
│   ├── 04_bad_header.robot
│   ├── 05_single_space.robot
│   ├── 06_broken_block.robot
│   └── 07_orphan_continuation.robot
├── tools/
│   └── inspect.py
└── evidence/
    ├── before/
    └── after/

Do not place real project resources in this tree. Every variable and value is synthetic so the resulting output.xml, HTML logs, and source files are safe to retain as course evidence.

4. Valid specimens: predict before validating

01_valid_space.robot

*** Settings ***
Documentation    Stable space-separated example.

*** Variables ***
${VALUE}    safe-demo

*** Test Cases ***
Space Format Is Valid
    Log    ${VALUE}
    Should Be Equal    ${VALUE}    safe-demo

02_valid_pipe.robot

| *** Test Cases *** |
| Pipe Format Is Valid |
|                      | Log             | pipe-demo |
|                      | Should Be Equal | ok | ok |

03_shared.resource

*** Settings ***
Documentation    Reusable checkpoint resource.

*** Variables ***
${SHARED VALUE}    resource-demo

*** Keywords ***
Log Shared Value
    Log    ${SHARED VALUE}

Prediction: all three should form valid source models. The resource is not itself an executable suite because it contains no tests/tasks, which is correct for its responsibility.

5. Invalid or semantically broken specimens

04_bad_header.robot — early section/token/model problem

*** Test Case **
Bad Header
    Log    not under a recognized test section

05_single_space.robot — cell-boundary/keyword-resolution trap

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

06_broken_block.robot — model/block problem

*** Test Cases ***
Broken Block
    IF    ${True}
        Log    missing END

07_orphan_continuation.robot — logical-statement ownership problem

*** Test Cases ***
Orphan Continuation
    ...    cannot continue a missing statement

Before running anything, write one predicted classification for each. The checkpoint is explicitly testing whether your mental model precedes tool output.

6. Prediction worksheet

7. Build the public parsing-API inspection tool

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

class Reporter(ModelVisitor):
    def __init__(self):
        self.count = 0

    def generic_visit(self, node):
        if node.errors:
            for error in node.errors:
                self.count += 1
                print(f"ERROR line {getattr(node, 'lineno', '?')}: {error}")
        ModelVisitor.generic_visit(self, node)

path = Path(sys.argv[1])
model = get_resource_model(path) if path.suffix == '.resource' else get_model(path)
print(f"source={path}")
for section in model.sections:
    print(f"section={type(section).__name__} lines={section.lineno}-{section.end_lineno}")
reporter = Reporter()
reporter.visit(model)
print(f"error_count={reporter.count}")

The tool intentionally selects get_resource_model() for .resource sources because resource validity rules differ from executable suite rules. It reports model errors but does not mutate the files.

8. Verify the original state and capture first failures

Run the parsing tool for every specimen and redirect/save its console output under evidence/before. Then run dry-run only for the .robot suite files, each into its own output directory so failures cannot overwrite one another.

python tools/inspect.py specimens/01_valid_space.robot
python tools/inspect.py specimens/02_valid_pipe.robot
python tools/inspect.py specimens/03_shared.resource
python tools/inspect.py specimens/04_bad_header.robot
python tools/inspect.py specimens/05_single_space.robot
python tools/inspect.py specimens/06_broken_block.robot
python tools/inspect.py specimens/07_orphan_continuation.robot

python -m robot --dryrun --outputdir evidence/before/01 specimens/01_valid_space.robot
python -m robot --dryrun --outputdir evidence/before/02 specimens/02_valid_pipe.robot
python -m robot --dryrun --outputdir evidence/before/04 specimens/04_bad_header.robot
python -m robot --dryrun --outputdir evidence/before/05 specimens/05_single_space.robot
python -m robot --dryrun --outputdir evidence/before/06 specimens/06_broken_block.robot
python -m robot --dryrun --outputdir evidence/before/07 specimens/07_orphan_continuation.robot

Do not use a shell loop unless you already know how your shell propagates non-zero exit codes; the explicit commands make each checkpoint result independently reviewable.

9. Repair each failure minimally

Make one causal repair per broken specimen:

• 04: change the header to *** Test Cases ***.
• 05: change Log hello to Log hello.
• 06: add the required END at the correct block indentation.
• 07: add a real preceding statement to continue, or remove the continuation and write an ordinary keyword call. Choose based on the intended semantics.

Do not simultaneously rename tests, reformat unrelated rows, or upgrade Robot Framework. A minimal diff makes the cause/effect relationship observable.

*** Test Cases ***
Repaired Block
    IF    ${True}
        Log    block is complete
    END

10. Independently verify repaired state

Repeat parser inspection and dry-run into evidence/after. Your acceptance criterion is not “the console looks quieter”; it is that every repaired suite has the expected discovered test name, dry-run status, and structured result artifacts, while the resource still parses as a resource model.

11. Produce the team-ready grammar-versus-style checklist

Create formatting-checklist.md with two explicit columns. A suggested final policy:

The checklist should never label a style preference as a parser fact. That precision prevents later lint/format rules from being mistaken for language semantics.

12. Evidence packet and independent review

The final packet should contain:

• original specimen files;
• repaired specimen files or version-control diff;
• Robot/Python version output;
• parser-inspection outputs;
• dry-run output.xml, log.html, and report.html for representative before/after cases;
• prediction worksheet with actual outcomes;
• the grammar-versus-style checklist;
• a short incident note explaining why no external-system troubleshooting was needed.

Treat result files as potentially sensitive in real projects. This lab contains only synthetic values, but the production operating model should apply retention and redaction rules.

13. Cleanup and rollback

After reviewing the evidence, delete only the guarded checkpoint root if you no longer need it. Confirm the current path before removal. Do not use broad recursive cleanup commands copied from a lesson against an arbitrary working directory.

# POSIX / Bash — first print and verify the path
pwd
# Then remove only the known disposable lab from its parent when appropriate.

# PowerShell — inspect before removal
Get-Location
# Remove-Item should target only the known disposable rf-syntax-checkpoint directory.

The course deliberately avoids giving a blind destructive command here. The cleanup lesson is the guard: know the exact disposable root, verify it, then remove only that root.

14. Knowledge check

15. Production operating model and bridge to Chapter 04

Chapter 03 adds a source-quality gate to the production Robot Framework operating model: version-provenant parsing, explicit grammar/style separation, non-destructive model inspection, dry-run validation, first-failure retention, and minimal causal repairs. This gate can run before expensive external automation and can fail fast with actionable evidence.

Chapter 04 moves one layer up. With parser semantics established, the next problem is executable identity: how files and directories become suites, how tests/tasks receive stable names, how documentation and metadata appear in results, and how execution roots change the result hierarchy.

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.