Test Cases, Tasks, Suites, Names, Documentation, and Metadata: Guided Hands-On Workflow

1. Preflight: prove the runtime before creating project state

Record the interpreter and framework identity exactly as you did in Chapter 02. A suite-name discrepancy is difficult to diagnose if two terminals are running different Robot versions.

python --version
python -m robot --version

# Create the disposable lab root, then enter it.
mkdir rf-suite-lab
cd rf-suite-lab

PowerShell users can use the same Python commands. Create the directory with New-Item -ItemType Directory rf-suite-lab if preferred. Keep all result directories inside this lab so cleanup has a clear boundary.

2. Build a nested test project and a separate task project

Create this tree. The test and task roots are separate by design so execution mode remains unambiguous.

rf-suite-lab/
├── acceptance/
│   ├── __init__.robot
│   └── platform/
│       ├── __init__.robot
│       ├── api_health.robot
│       └── ui_contract.robot
├── tasks/
│   ├── __init__.robot
│   └── daily_summary.robot
└── results/

3. Give the test root a deliberate public identity

*** Settings ***
Name             Release Acceptance
Documentation    Synthetic release-gate suites used only for Chapter 04.
Metadata         Owner    quality-platform
Metadata         Evidence Class    synthetic
Test Tags        chapter-04    synthetic

Save this as acceptance/__init__.robot. The Name setting intentionally decouples the public suite identity from the directory name. Documentation explains purpose; metadata records non-sensitive ownership/evidence facts; Test Tags adds stable recursive classification to tests below this directory on the current stable Robot version.

4. Configure the child directory without pretending it is an import inheritance layer

*** Settings ***
Name             Platform Acceptance
Documentation    Contract-level synthetic checks for the platform boundary.
Metadata         Component    platform

Save this as acceptance/platform/__init__.robot. There are deliberately no shared variables or user keywords here. If lower files needed reusable data/keywords, the project would use explicit resource or variable files. Keeping initialization focused on suite configuration prevents hidden scope assumptions.

5. Create two focused file suites

Save the first source as acceptance/platform/api_health.robot:

*** Settings ***
Documentation    Synthetic service-contract checks.
Metadata         Requirement    RF-CH04-API

*** Variables ***
${EXPECTED STATUS}    healthy

*** Test Cases ***
Service Reports Healthy State
    [Tags]    smoke    positive
    Should Be Equal    ${EXPECTED STATUS}    healthy

Unexpected State Is Rejected
    [Tags]    negative
    Should Not Be Equal    degraded    healthy

Save the second as acceptance/platform/ui_contract.robot:

*** Settings ***
Documentation    Synthetic UI-contract vocabulary checks.
Metadata         Requirement    RF-CH04-UI

*** Test Cases ***
Primary Action Label Is Stable
    [Tags]    smoke    positive
    Should Be Equal    Continue    Continue

Dangerous Placeholder Is Not Accepted
    [Tags]    negative
    Should Not Be Equal    DELETE-PRODUCTION    Continue

These are intentionally tiny. Their purpose is identity and hierarchy evidence, not domain automation. BuiltIn assertions create deterministic PASS results with no external state.

6. Build the separate task project

Save this as tasks/__init__.robot:

*** Settings ***
Name             Synthetic Operations Tasks
Documentation    Harmless local task examples for Chapter 04.
Metadata         Owner    automation-platform
Metadata         Data Class    synthetic

Save this as tasks/daily_summary.robot:

*** Settings ***
Documentation    Demonstrates task identity without external side effects.

*** Tasks ***
Prepare Synthetic Daily Summary
    Log    summary-id=chapter04-example
    Should Be Equal    ready    ready

The task still produces PASS/FAIL and evidence, but it is not pretending to validate an application requirement. The result should be interpreted as task execution evidence.

7. Predict identities before running anything

Write these predictions in a small text file before execution. This forces the mental model to become falsifiable.

8. Run each root into an isolated result directory

python -m robot --dryrun --outputdir results/acceptance acceptance
python -m robot --dryrun --outputdir results/platform acceptance/platform
python -m robot --dryrun --outputdir results/file acceptance/platform/api_health.robot
python -m robot --dryrun --outputdir results/tasks tasks

Expected observation: all four dry-runs pass. The first includes the root and child initialization settings. The second ignores acceptance/__init__.robot because that file is above the executed root. The third ignores both parent initialization files because the suite file itself is the root. The task run uses task terminology and its independent hierarchy.

9. Inspect full names and metadata with the public result API

from robot.api import ExecutionResult

for label in ("acceptance", "platform", "file", "tasks"):
    result = ExecutionResult(f"results/{label}/output.xml")
    print(f"\n[{label}]")

    def walk(suite, depth=0):
        print("  " * depth + f"SUITE {suite.full_name}")
        if suite.metadata:
            print("  " * (depth + 1) + f"META {dict(suite.metadata)}")
        for test in suite.tests:
            print("  " * (depth + 1) + f"ITEM {test.full_name} {test.status}")
        for child in suite.suites:
            walk(child, depth + 1)

    walk(result.suite)

Compare the printed full names to your prediction sheet. Then open each log.html and report.html locally. The HTML presentation should tell the same hierarchy story as output.xml; it is not an independent source of truth.

10. Preserve the root while selecting a narrower suite

Sometimes you want one child suite but still need parent identity, metadata, tags, setup/teardown, or governance. In that case execute the higher root and select the child instead of executing the file directly.

python -m robot   --dryrun   --suite "Release Acceptance.Platform Acceptance.Api Health"   --outputdir results/selected   acceptance

On Robot Framework 7.x, parent-qualified suite selection should match the whole suite name from the root when parent names are included. If you intentionally want to match a nested parent anywhere, use the documented wildcard form. This is another reason stable full names matter.

11. Challenge: choose the right layer

Your team wants the root suite owner to appear in reports, every descendant test to receive a synthetic-data tag, and one child file to keep its own requirement identifier. Where should each piece live?

• Put root ownership in root suite metadata.
• Put the recursive classification in the root initialization file using Test Tags on the current stable line.
• Put the file-specific requirement in the file suite’s metadata.
• Do not encode any of these as a fake variable solely so it “exists somewhere.”

Modify the lab to add a second component directory and predict its full names before running it.

12. Verification and cleanup

Verification checklist:

• four result directories exist and each contains output.xml, log.html, and report.html;
• the full names change exactly where the execution root changes;
• root metadata/tags disappear when their root initialization file is outside the executed tree;
• the task root remains separate from the test root;
• no real credentials, production URLs, or personal paths appear in source or artifacts.

Keep the evidence if you are continuing to Lesson 3. Otherwise verify that your current directory is the disposable rf-suite-lab parent before removing only that lab directory. Never copy a broad recursive deletion command into an unrelated project.

13. Knowledge check

14. Summary and next step

You built two deliberate execution domains—tests and tasks—then proved that execution root, initialization scope, and suite names determine the full result hierarchy. You also used result evidence instead of guessing from paths.

Lesson 3 turns these observations into architecture choices: where to draw suite boundaries, when to customize names, how to use metadata versus tags, and when a path reorganization becomes an operational breaking change.

Further reading

• Robot Framework 7.4.2 User Guide — creating tests, tasks, suite files/directories, suite initialization files, names, documentation, metadata, execution selection, and result behavior.
• Robot Framework 7.4.2 public API documentation — stable model/result APIs including ExecutionResult, TestSuite.full_name, and TestCase.full_name.
• RFCP syllabus — Suite File & Tree Structure — suite organization, settings, and metadata terminology.
• RFCP syllabus — Initialization Files — purpose and boundary behavior of __init__.robot.
• Robot Framework Style Guide — current naming, section ordering, documentation, and maintainability guidance.
• Robot Framework 7.4.2 release notes — current stable-line clarifications, including parent __init__.robot behavior.