Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 36 ยท Syntax and Test Cases

The Settings Section, Documentation and Metadata

Learn every common entry of the Settings section: Documentation, Metadata, Library, Resource, Suite and Test Setup, Test Tags and Timeout, plus doc formatting.

The *** Settings *** section configures the file: which libraries it imports, what it is about, what runs before and after, and which tags and timeouts apply. It is usually the first section, and it gives a reader a quick overview. This lesson lists the common settings and shows how documentation is written and formatted.

The settings at a glance

ROBOTFRAMEWORK
*** Settings ***
Documentation     Checks for the shopping cart.
...               Covers adding, removing and totals.
Metadata          Owner    Team Checkout
Metadata          Version  1.4
Library           Collections
Library           String
Resource          resources/cart.resource
Variables         config/staging.py
Suite Setup       Open Test Shop
Suite Teardown    Close Test Shop
Test Setup        Empty The Cart
Test Teardown     Log    Test finished
Test Tags         cart    regression
Keyword Tags      cart-internal
Test Timeout      30 seconds
Setting Meaning
Documentation Text describing the suite; shown in the log and report
Metadata Name and value pairs shown in the report header
Library Imports a keyword library (see Libraries)
Resource Imports keywords and variables from a resource file
Variables Imports variables from a Python or YAML file
Suite Setup / Suite Teardown A keyword that runs once before the first test and after the last
Test Setup / Test Teardown A keyword that runs before and after every test
Test Tags Tags added to every test in this file
Keyword Tags Tags added to every user keyword in this file
Test Timeout Maximum time for each test
Test Template Makes every test a data row for one template keyword (see the data-driven chapter)
Name Overrides the suite name (Robot 6.1 and later)

Older files may use Force Tags and Default Tags. Force Tags was replaced by Test Tags in Robot 6.0 and Default Tags is deprecated; new files should use Test Tags and put a [Tags] setting in tests that need different tags.

Settings names are case-insensitive, may be written with or without spaces, and can be in any order. Each setting except Library, Resource, Variables and Metadata may appear only once.

Documentation

Documentation can be long. Use ... to continue it:

ROBOTFRAMEWORK
*** Settings ***
Documentation
...    *Cart tests.*
...
...    These tests use the _fake_ payment gateway, so no real card is charged.
...    See https://example.org/docs for the setup guide.

Robot formats documentation text in the log and report with a light markup:

Markup Result
*bold* bold
_italic_ italic
Text in double backticks Monospace
https://example.org A clickable link
[https://example.org|label] A link with a label
- item lines A bullet list
A line starting with | a | b | A table
--- on its own line A horizontal rule

Each test and each user keyword can have its own [Documentation], which appears in the log next to the test name. Good documentation says why the test exists or what business rule it protects, not what each step does.

ROBOTFRAMEWORK
*** Test Cases ***
Discount applies to orders over 100
    [Documentation]    Orders of 100 or more get a 10 percent discount.
    ...                Rule BR-17 in the pricing policy.
    Given the cart total is    120
    Then the discount is    12

Metadata

Metadata adds a name and a value (the value may continue over lines). They are shown at the top of the log and report, which is handy for build numbers and environment names. From the command line you can add or override them: robot --metadata Build:1432 --metadata Env:staging tests/.

Setup and teardown at suite and test level

A setup is a keyword that runs before; a teardown is a keyword that runs after, even if the test failed. At suite level, Suite Setup fails all tests if it fails. At test level, a failed Test Setup fails that test. The full story is in Tags, Setup and Teardown.

Directory-level settings

A folder can have an __init__.robot file with its own Settings section. Its Setup, Teardown, Tags, Documentation and Metadata apply to the whole directory as a suite. An __init__.robot file cannot contain tests.

Stand-in 1: reading a Settings section

The blocks below are not Robot Framework. The first parses a Settings section into a dictionary, collecting the repeatable settings (Library, Resource, Metadata) as lists and handling ... continuation.

Python Stand-in: parse Settings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: documentation markup

Robot turns *bold*, _italic_ and bare URLs into HTML. The stand-in does the same with regular expressions (the real formatter is more careful about word boundaries).

Python Stand-in: documentation formatting

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Style tips

  • Put Settings first, then Variables, Test Cases, Keywords. Readers expect that order.
  • Align the second column; it makes the section scannable.
  • Import only what a file needs. Every library import adds keywords that can clash in name.
  • Write documentation for suites and for non-obvious tests; skip it where the test name already says everything.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which setting adds tags to every test in a file?

    Test Tags applies to all tests in the file. Keyword Tags applies to user keywords instead.
  2. 2. Which settings may appear several times in one Settings section?

    You can import many libraries, resources and variable files and add many metadata entries; the other settings may appear only once.
  3. 3. What happens if Suite Setup fails?

    A failing suite setup fails all tests of the suite; the suite teardown still runs.
  4. 4. How do you add a clickable link in documentation?

    Bare URLs become links, and [url|label] gives a link with a label.

Summary

  • The Settings section imports libraries and resources and holds documentation, metadata, setup, teardown, tags and timeout.
  • Documentation supports light markup (bold, italic, code, links, lists, tables) and ... continuation.
  • Test Tags replaces the older Force Tags; Keyword Tags tags user keywords.
  • Only imports and Metadata can repeat; a directory can have its own settings in __init__.robot.

Next: Tags, Setup and Teardown