Test Cases, Tasks, Suites, Names, Documentation, and Metadata: Configuration, Design Patterns, and Trade-Offs

1. Treat suite structure as architecture, not folder decoration

Suite hierarchy is part of the automation product’s public surface. Humans see it in reports, CI selectors depend on it, ownership rules map to it, and historical trends aggregate around it. A good hierarchy groups cases that share business responsibility or lifecycle while keeping each file small enough to review and diagnose.

The goal is not maximum nesting. Every level should answer a useful question such as “which product area?”, “which workflow family?”, or “which evidence boundary?” If a directory exists only because a repository template created it, it may not deserve a suite identity.

2. Decision model for a suite boundary

flowchart TD
A[Candidate group of tests/tasks] --> B{Shared business responsibility?}
B -- No --> C[Keep separate]
B -- Yes --> D{Need shared suite metadata/lifecycle?}
D -- Yes --> E[Directory suite + __init__.robot]
D -- No --> F{Small cohesive set?}
F -- Yes --> G[Focused file suite]
F -- No --> H[Directory suite with focused child files]
E --> I[Record stable name and owner]
G --> I
H --> I
I --> J[Review selectors and history before renaming/moving]

This flow is intentionally conservative. Initialization files add suite configuration and lifecycle, so using one in every directory creates more hidden context. Prefer them where the directory genuinely represents a suite boundary.

3. File suite versus directory suite

4. Concise names versus documentation

A name should be short enough to scan in a report yet specific enough to distinguish the node. Documentation should carry the explanation that would make the name unreadably long. For example, Checkout Contract is a better suite name than Checkout Contract Tests That Run Against The Synthetic Fixture Before Every Release; the latter detail belongs in documentation.

Custom Name is useful when source names include implementation-oriented prefixes or when a durable human identity should survive a local filename convention. It is not a license to make path and report identity unrelated without documentation. Future maintainers still need to map a result node back to source.

5. Metadata versus tags

Metadata and tags solve different lookup problems. Suite metadata answers “what context describes this suite?” Tags answer “which executable items belong to this selectable class?” Using metadata as a selector or tags as a dumping ground for paragraphs creates brittle automation.

6. Initialization at directory boundaries versus per-file configuration

Place a __init__.robot where the directory has real suite identity or shared suite-level lifecycle/configuration. Do not use it as a hidden “global imports” file. Child suite files do not inherit its user keywords and variables automatically, and parent initialization outside the execution root is ignored.

If every child needs the same reusable keyword library, an explicit resource import makes the dependency visible. If every child should receive a common test tag or timeout because they belong to the same release boundary, the appropriate initialization setting can express that suite-level policy.

7. Stable paths versus frequent reorganization

Repository cleanup often looks harmless: rename api_health.robot, move it to a new folder, or change a directory Name. Each can change suite full names and therefore CI selectors, dashboards, rerun records, links, ownership mappings, and historical trend continuity.

Treat a hierarchy change like an interface migration:

1. inventory selectors and consumers;
2. record old and new full names;
3. update CI and reporting configuration in the same change;
4. preserve a migration note for historical results;
5. run a dry-run from the production execution root to prove the new tree.

8. Execute a child directly or select it under the root?

9. Tests versus tasks: separate semantics before optimizing structure

Do not choose *** Tasks *** merely because an automation is long-running, and do not choose *** Test Cases *** merely because the team already has test reporting. The question is intent. A test validates an outcome as release/quality evidence. A task performs an operation. Both can fail, but their failure means different things to the organization.

When one repository contains both, keep separate roots, jobs, artifact policies, and ownership where practical. That prevents a task failure from masquerading as a product regression or a test failure from being treated as an operational workflow interruption.

10. Worked scenario: choose a structure for a release platform

Suppose a team owns checkout, identity, and catalog validation. They need a release smoke slice across all three, component ownership, and a nightly synthetic maintenance task.

automation/
├── acceptance/
│   ├── __init__.robot          # Name=Release Acceptance, Owner metadata
│   ├── checkout/
│   │   └── smoke.robot
│   ├── identity/
│   │   └── smoke.robot
│   └── catalog/
│       └── smoke.robot
└── tasks/
    ├── __init__.robot          # Name=Synthetic Operations Tasks
    └── nightly_maintenance.robot

Give each smoke test a smoke tag rather than creating a second duplicate “smoke-only” hierarchy. Put component ownership at the narrowest stable suite level that actually has distinct ownership. Keep the task root separate because its outcome has operational meaning rather than release assertion meaning.

11. Decision table for code review

12. Knowledge check

13. Summary and next step

Suite architecture is a maintainability and operations decision. Use focused files, meaningful directory suites, concise names, explanatory documentation, safe metadata, governed tags, and sparse initialization boundaries. Treat reorganization as an observable identity migration.

Lesson 4 intentionally breaks these assumptions—wrong roots, duplicate names, secret metadata, initialization misconceptions, and mixed responsibility—then diagnoses them from first-failure evidence.

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.