Test Cases, Tasks, Suites, Names, Documentation, and Metadata: Core Concepts and Mental Model

1. The practical problem: readable files are not yet stable execution identities

Chapter 03 established how Robot Framework parses source. Once the source is valid, a new question appears: what exactly did we execute? In a tiny project, “the login test” may sound precise. In a large estate, there may be many tests called “Login succeeds,” spread across product areas, environments, or release suites. CI selection, ownership, reruns, trend analysis, and incident triage need identities that survive beyond a single filename seen by one developer.

Robot Framework solves this by building a hierarchical suite model from the paths you execute. Directory suites contain file suites; file suites contain tests or tasks. Each node has a local name and a full name that includes its parents. Documentation, metadata, and tags enrich that model, but none of them is the filesystem path itself and none is the runtime state of the external system.

2. Mental model: executed path → suite hierarchy → result tree

flowchart TD
A[Executed path] --> B[Root suite]
B --> C[Directory suite]
C --> D[File suite]
D --> E[Test or task]
F[__init__.robot] --> B
F --> C
G[Name / Documentation / Metadata] --> B
G --> C
H[Local test/task name] --> E
E --> I[Full name]
I --> J[Execution status and evidence]
J --> K[output.xml / log.html / report.html]

The critical first arrow is the executed path. Robot does not scan an abstract repository universe and then decide which parents should count. It builds the root from the file or directory inputs you give it. That means the same physical file can have a different full suite/test name when you execute a higher directory versus executing the file directly.

An initialization file can configure a directory suite only when that directory participates in the executed suite tree. Parent initialization files above the chosen root are ignored. This is not an incidental detail: it is part of the suite identity and lifecycle model.

3. Define the objects before using them

4. File suites and directory suites solve different organization problems

A suite file contains tests or tasks and automatically becomes a suite. A suite directory groups child suite files and child suite directories. The hierarchy lets you model product boundaries such as release_acceptance / checkout / payment.robot without stuffing unrelated cases into one giant file.

Robot does not impose an arbitrary hard test count, but the User Guide recommends keeping ordinary suite files focused; very large files make ownership, diagnosis, and review harder. Directory suites are therefore an architectural tool, not just a way to make the tree look tidy.

release_acceptance/
├── __init__.robot
├── checkout/
│   ├── __init__.robot
│   ├── payment.robot
│   └── basket.robot
└── identity/
    └── login.robot

5. Local names, custom names, and full names

By default Robot constructs a suite name from the file or directory source: it removes the extension, removes an optional execution-order prefix separated by __, replaces underscores with spaces, and title-cases a name only when the whole source name is lower case. Starting with Robot Framework 6.1, the Name setting can override the suite name.

*** Settings ***
Name             Release Acceptance
Documentation    Synthetic release-gate examples for Chapter 04.
Metadata         Owner    quality-platform
Metadata         Data Class    synthetic

If checkout/payment.robot is inside a root suite named Release Acceptance and a child directory suite named Checkout, a test named Approved Card Is Accepted can have the full name Release Acceptance.Checkout.Payment.Approved Card Is Accepted. The full name is a model identity; it is not a filesystem path and should not be reconstructed by blindly replacing slashes with dots.

6. The execution root changes identity and inherited directory-suite behavior

Consider the same physical file under release_acceptance/checkout/payment.robot. These commands intentionally produce different suite trees:

# Full hierarchy: root and child initialization files participate.
python -m robot --dryrun --outputdir results/root release_acceptance

# Checkout becomes the root. release_acceptance/__init__.robot is above the root and is ignored.
python -m robot --dryrun --outputdir results/checkout release_acceptance/checkout

# The file itself becomes the root. Parent directory initialization files are ignored.
python -m robot --dryrun --outputdir results/file release_acceptance/checkout/payment.robot

This is why “I ran the same file” is incomplete incident evidence. Record the input path and selection options. If a parent suite provides metadata, tags, setups, or naming through __init__.robot, those controls exist only when that parent is inside the execution tree.

7. Tests and tasks share syntax patterns but express different execution intent

Robot Framework recommends tasks when the purpose is automation rather than testing. The syntax is largely the same, but the terminology and execution mode are explicit. A single file cannot contain both *** Test Cases *** and *** Tasks ***. Keep test and task projects or roots deliberately separated when their semantics differ.

8. Documentation, metadata, and tags are not interchangeable

Documentation explains intent and context. Metadata stores free suite-level name/value information such as an owner, component, evidence class, or synthetic environment label. Tags classify individual tests/tasks and participate directly in filtering and selection. Choose the field based on the behavior you need, not based on which one is easiest to type.

9. What __init__.robot does — and does not do

A directory suite cannot contain settings directly, so Robot Framework uses a special initialization file, normally __init__.robot. It can set suite-level properties such as Name, Documentation, Metadata, Suite Setup, and Suite Teardown. On current Robot versions, directory initialization can also define recursive test/task defaults such as tags and selected setup/timeout settings.

*** Settings ***
Name             Release Acceptance
Documentation    Root directory suite for synthetic release checks.
Metadata         Owner    quality-platform
Test Tags        chapter-04    synthetic

Two boundaries are easy to miss. First, an initialization file above the executed root has no effect. Second, variables and keywords defined or imported in an initialization file are not automatically available in lower-level suite files. If children need reusable keywords or variables, put them in a resource/variable file and import that file where needed. Initialization is suite configuration, not an inheritance container for arbitrary keyword scope.

10. Inspect identities from result evidence, not from assumptions

Use dry-run when you want to prove discovery, parsing, imports, keyword resolution, and suite identity without running normal domain keywords. Then inspect the result model with the stable public API.

python -m robot --dryrun --outputdir results release_acceptance

from robot.api import ExecutionResult

result = ExecutionResult("results/output.xml")

def show(suite, depth=0):
    print("  " * depth + f"SUITE: {suite.full_name}")
    for test in suite.tests:
        print("  " * (depth + 1) + f"TEST: {test.full_name} [{test.status}]")
    for child in suite.suites:
        show(child, depth + 1)

show(result.suite)

full_name is the current property name in Robot Framework 7.4.2. Older examples may use longname, but that property has been deprecated since Robot Framework 7.0. New course content should use the current API.

11. Why this matters in DevOps

Stable suite identity becomes an operational contract. CI jobs select suites and tests by name or tags; ownership dashboards aggregate results; rerun tooling needs to identify the same failing scope; incident tickets refer to a concrete full name; and governance rules often align with suite boundaries. If teams reorganize directories casually or run inconsistent roots, historical results become harder to compare and selectors can silently target a different tree.

That does not mean paths can never change. It means suite reorganization is an observable interface change and should be reviewed, versioned, and accompanied by updates to selectors, ownership rules, and documentation.

12. Knowledge check

13. Summary and next step

You now have the identity model for Robot Framework: paths build a suite tree; __init__.robot configures participating directory suites; files contain tests or tasks; local names combine into full names; documentation and metadata enrich suites; tags classify executable cases; and the result tree records what actually ran.

Lesson 2 turns this model into a disposable nested project and compares the exact result hierarchy produced by different execution roots.

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.