Skip to content

Working With Robot Framework#
Author Alena Galysheva
Last Updated 19.03.2025

This guide focuses on setting up an optimal environment for working with Robot Framework.

Project Setup#

Use Git connected to a remote repository (GitLab, GitHub, etc.). Create a repository or use an existing one and clone it to your machine with the following command:

git clone <repository_url>

Open it in your IDE of choice. My preference is Visual Studio Code (VSCode), which I will use throughout this guide.

Virtual Environments#

Using virtual environments is highly recommended to avoid dependency conflicts that typically happen when working on multiple Python-based projects that use different versions of the same packages.

From the VSCode documentation:

An "environment" in Python is the context in which a Python program runs that consists of an interpreter and any number of installed packages.

Setting up virtual environments can be tricky when working with the Browser library due to its dependency on NodeJS. One solution is to use Node.js virtual environment and link it to the Python virtual environment.

See Creating Virtual Environments in VSCode guide for detailed and illustrated step-by-step instructions on how to create a Python virtual environment in VSCode.

Project Structure#

Robot Framework has an official guide on how to organize the project files.

requirements.txt or pyproject.toml#

These files are used to manage dependencies. pip package manager can use these files to install the dependencies on a new system, including containerized environments.

The requirements.txt file stores dependencies as package==version pairs. While specifying the version is optional, it is strongly recommended to lock in package versions. This helps to ensure the consistency of the environment and prevents unexpected issues caused by dependency version updates.

Example requirements.txt:

robotframework==7.2.1
robotframework-browser==19.3.1

Dependencies can be installed from the file with the following command:

pip install -r requirements.txt

More info on how to write requirements.txt: Requirements File Format.

If you want to explore the topic more in-depth, then I'd recommend reading the Robot Framework dependency management by Robot Framework article.

pyproject.toml is a modern approach to managing project dependencies and build system configurations. It provides a standardized way to define dependencies, tools, and metadata in one place, making it easier to manage Python projects. For more details on setting it up, refer to the official guide: Writing pyproject.toml.

.gitignore#

.gitignore is used to prevent unnecessary files from being committed. Examples of files and directories that should be ignored include the virtual environment directory, Visual Studio Code settings directory, __pycache__, and the output files generated by Robot Framework.

Tip: You can configure Robot Framework to write all of its output files to a specific directory using the --outputdir option.

Example .gitignore file (results is the output directory for RF tests):

.venv
.vscode
**/__pycache__/**
results

README.md#

Use this file to document your project, including installation, setup, and configuration instructions.

Visual Studio Code#

RobotCode is the only actively maintained LSP extension for Robot Framework. It provides autocompletion, linting, and other useful features that can improve your development experience.

In .vscode/settings.json, you can configure RobotCode to pass command-line options automatically.

Example:

{
    "robotcode.robot.variables": {
        "RF_USERNAME": "robot",
        "RF_PASSWORD": "framework",
    },
    "robotcode.robot.outputDir": "${workspaceFolder}/results"
}

Note: Robot Framework options set in settings.json will apply only when running the tests in VSCode using the RobotCode extension. These configurations will not be automatically applied when running the tests from the command line, or when running them in a containerized environment.

Add .vscode to .gitignore to prevent secrets from being stored in the repository. Document the required configurations in README.md to simplify the setup process for other developers working on the project.

Specifying Library Search Paths#

If your project is structured like this:

my_project
├── tests
│   └── test_001.robot
└── resources
    └── general.resource

By default, resource imports in test_001.robot look like this:

*** Settings ***
Resource        ../resources/general.resource

To make imports cleaner, you can specify the resources directory as a path where Robot Framework should search for files:

{
    "robotcode.robot.pythonPath": [
        "${workspaceFolder}/resources"
    ]
}

Then, you can simply use:

*** Settings ***
Resource        general.resource

Note: PYTHONPATH needs to be passed to robot when running tests from the command line or in a containerized environment. Refer to Telling Robot Framework where to search libraries, resource and variable files guide for more information on how to configure PYTHONPATH in other contexts.

Robot Framework Extended Universe#

Managing Arguments#

As mentioned, settings.json is a VSCode configuration file which shouldn't be used to configure test execution in other contexts/environments. Use an argument file when running tests in CI/CD. Example argument file arguments.txt:

--include regression
--pythonpath ./resources
--pythonpath ./data

Pass the file when running the tests:

robot --argumentfile arguments.txt tests/

Environment Variables in CI/CD#

It's recommended to use secret variables to manage sensitive data when executing tests in CI/CD. See GitLab CI/CD Variables guide for instructions on how to define secret variables in GitLab. You can access the value of the variable in the .yml file using the $VAR_NAME syntax.

Example GitLab pipeline configuration:

robot:
  stage: test
  image: python:3.8
  script:
    - pip install -r requirements.txt
    - robot --variable PASSWORD:$RF_PASSWORD tests/

Robocop (Linting)#

Robocop is a linter for Robot Framework.

Install it with the following command:

pip install robotframework-robocop

This tool checks your code and gives suggestions on best development practices established by the community. See Robocop - Getting Started on more details about running the tool and rules, options, configurations available.

Tip: You can create a .robocop file at the root of your project and set the options for robocop from there.

TestDoc and LibDoc#

TestDoc and LibDoc are built-in tools that come with Robot Framework used to generate test documentation and library documentation respectively for your Robot Framework code base.

Listeners and PreRun Modifiers#

Robot Framework allows extending test execution using Listeners and PreRunModifiers.

  • Listeners track test execution events.
  • PreRunModifiers modify test data before execution.

Enable them with:

robot --listener my_listener.py tests/
robot --prerunmodifier my_modifier.py tests/

More info: Listeners and PreRun API.

Robot Framework API#

Robot Frameworks's API can be utilized in several ways. This API can be used for parsing, inspecting and modifying test data by parsing it to tokens or model. To simplify the process of parsing and modifying the data, ModelVisitor and ModelTransformer classes are provided. This interface is used by internal features like PreRun Modifier and external tools like Robocop, which makes the API documentation a useful source of information when implementing functionalities with the mentioned tools.

More info: Exposed API - Robot Framework Documentation

List of available objects: Robot API Objects