How to Use Robot Framework for Test Automation

Robot Framework is a Python-based, open-source automation framework that lets you describe tests as readable sequences of keywords. To automate a real application, install Robot Framework in a Python virtual environment, create a .robot suite, add a library that can interact with your target, run the suite with robot, and inspect the generated report and log.

Robot Framework is the framework and test-data syntax; a library supplies the technology-specific actions. Choose a web, API, or RPA library to match what you are testing. The official guide currently documents Robot Framework 7.5 and requires Python 3.8 or newer for that version. Check the version-specific User Guide and your chosen library’s compatibility notes before upgrading.

1. Install Robot Framework in an isolated environment

A virtual environment keeps this project’s Python packages separate from other projects and from the system Python. These commands assume Python and pip are installed. Use python3 instead of python on systems where that is the available command.

Linux and macOS

mkdir robot-demo
cd robot-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install robotframework
robot --version

Windows PowerShell

mkdir robot-demo
cd robot-demo
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install robotframework
robot --version

On Windows Command Prompt, activate with .venv\Scripts\activate.bat. If PowerShell blocks activation, use an allowed shell or invoke the environment interpreter directly as .venv\Scripts\python.exe -m pip install robotframework and .venv\Scripts\robot.exe --version.

Pin the Robot Framework and library versions for repeatable team or CI runs. For example, after choosing a version compatible with your Python and libraries, record it in a requirements file and install from that file:

# requirements.txt
robotframework==7.5

# install in the active environment
python -m pip install -r requirements.txt

Use the version number that your project has validated; the example pin is not a recommendation to upgrade blindly. The current installation guide says Python 3.8 or newer is required by its documented current version, and Robot Framework 6.1.1 is the latest release supporting Python 3.6 and 3.7.

2. Write and run a first suite

Create tests/first_test.robot (make the tests directory first) with this minimal suite. It uses only Robot Framework’s built-in BuiltIn library, so it has no browser or external service dependency.

*** Settings ***
Documentation    A small example suite.

*** Test Cases ***
Addition returns the expected result
    ${total}=    Evaluate    2 + 3
    Should Be Equal As Integers    ${total}    5

Run it from the project directory with the virtual environment active:

robot --outputdir results tests/first_test.robot

The command exits with a status indicating whether the run succeeded. By default Robot Framework creates machine-readable output.xml plus human-readable log.html and report.html; --outputdir results puts these artifacts in the results directory. Open results/report.html for a summary, then use results/log.html to inspect the keyword sequence and failure details.

Common execution options

Need	Example
Run one suite file	`robot tests/first_test.robot`
Run a directory of suites	`robot tests/`
Choose an output folder	`robot --outputdir results tests/`
Set output and report names	`robot --output output.xml --log log.html --report report.html tests/`
Run tests with a tag	`robot --include smoke tests/`
Skip a tag	`robot --exclude slow tests/`
Run a named test	`robot --test "Addition returns the expected result" tests/`
Run with a variable	`robot --variable BASE_URL:https://example.com tests/`
See command options	`robot --help`

Options go before the suite or directory path. Use --help for the full option list supported by the installed version. Avoid putting passwords or tokens directly in shell history; pass secrets through your CI secret mechanism and have the suite or library read them appropriately.

3. Choose a library for the system under test

Robot Framework’s keywords can be low-level library keywords or reusable user keywords you define. The suite should describe the test intent; the library should handle the target technology.

Target	Library direction	Selection checks
Web application	Browser Library or SeleniumLibrary	Supported browsers and drivers, framework/Python compatibility, interaction model, maintenance, documentation.
HTTP API	Requests Library	Authentication support, request/response behavior, supported Robot Framework and Python versions, keyword clarity.
RPA workflow	Relevant RPA Framework libraries	Supported desktop, browser, file, or business-system interfaces and their platform constraints.

These are examples from the Robot Framework ecosystem, not a universal ranking. Read each candidate library’s current documentation and compatibility information before choosing. For a test that only calculates values or checks data structures, built-in keywords may be enough.

Import a library

Install the chosen integration in the same virtual environment as Robot Framework, following that library’s official install instructions. Then import it in the suite’s settings section. The following illustrates the syntax with SeleniumLibrary; the library itself must be separately installed and configured for a browser.

*** Settings ***
Library    SeleniumLibrary

Do not copy browser keywords into a suite unless they belong to an installed library. An “unknown keyword” error often means the import is missing, the package was installed into another Python environment, or the keyword name does not match that library’s current API.

4. Organize suites as they grow

Start with a small suite. Once multiple suites need the same setup or actions, move reusable user keywords into a resource file and import it with a Resource setting. Keep technology-specific details in the library or shared keywords, and name test cases in terms of expected behavior.

*** Settings ***
Resource    resources/common.resource

*** Test Cases ***
A registered user can sign in
    Open Application Login Page
    Submit Valid Credentials
    User Should See Account Page

The example names are placeholders: define those user keywords in resources/common.resource and connect them to the application through your selected library. Keep credentials and environment-specific URLs configurable rather than hard-coded in test data.

For a larger suite, keep related tests in separate files and use tags for practical groups such as smoke or slow tests. Establish a predictable output directory and preserve the XML and HTML artifacts your team needs to review or process.

5. Interpret results and investigate failures

Check the terminal summary and process exit status to see whether the run passed.
Open report.html for suite-level and test-level totals.
Open log.html, expand the failed test, and find the first failed keyword or exception. Later failures can be consequences of that first error.
Check the library’s message, arguments, and returned values to distinguish an application defect from an incorrect locator, unavailable service, timeout, or test setup problem.
When tests pass locally but fail elsewhere, compare Python, Robot Framework, library, browser/driver, environment variables, network access, and application state.

Robot Framework’s rebot command can combine or post-process output files. For example, after separate runs have produced XML files, consult rebot --help and the User Guide for the supported merge and report options for your installed version. Treat output.xml as a result artifact; do not assume it is interchangeable with a library-specific report format.

6. Use Robot Framework for website checks and screenshots

A browser automation suite can navigate to a page, exercise behavior, and assert the result. For a visual artifact, the browser setup and capture step are part of the test environment: choose a browser library, install its dependencies, and make the test wait for the page state you need before capturing. Screenshots can help diagnose failures, but they do not replace assertions about application behavior.

ScreenshotNeo is a website screenshot API and MCP server made by Yorker Media. Its API can be called from a Robot Framework suite using an HTTP library, or used separately when you need a screenshot without managing browser automation. See the ScreenshotNeo site and API documentation.

Or skip the browser setup

For a one-call screenshot, use the ScreenshotNeo API. Create an API key and replace YOUR_API_KEY below. This cURL example saves an image response as WebP:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

For Python, install requests in the active environment, then run:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

For Node.js with a runtime that provides fetch:

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const bytes = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

ScreenshotNeo accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. See the docs for options and setup, then sign up for 1,000 free screenshots a month with no card.

7. Troubleshooting

Symptom	Likely cause	What to do
`robot: command not found` or not recognized	Virtual environment is inactive or its scripts directory is not on PATH.	Activate `.venv`; check `python -m pip show robotframework`. Invoke the environment’s robot executable directly if needed.
`No module named robot`	Robot Framework was installed using a different Python interpreter.	Activate the intended environment and run `python -m pip install robotframework` with that interpreter.
Unsupported Python version during install	The selected Robot Framework release does not support that Python version.	Use a supported Python version for the current release or select a compatible older release based on the version guide.
Unknown keyword	Missing library/resource import, wrong keyword spelling, or package installed in another environment.	Verify the import, package installation, active environment, and current library documentation.
Library import fails	Missing dependency, incompatible versions, or initialization/configuration error.	Read the complete import traceback in the log or terminal; install the library in the active environment and check its compatibility and setup guide.
Test fails at a locator or page action	Wrong/stale locator, page not ready, changed application, or incorrect test data.	Inspect the first failing keyword and current page state; use the library’s documented wait behavior and verify the locator and test account.
Tests pass locally but fail in CI	Environment, timing, browser, credentials, network, or application state differs.	Compare pinned dependencies and configuration; preserve logs and reports; make setup explicit and avoid relying on local state.
HTML report or log is missing	Output path differs, report/log generation was disabled, or the command wrote files elsewhere.	Check the terminal output and `--outputdir`, `--log`, and `--report` options; regenerate from XML with `rebot` when appropriate.

8. Performance, reliability, and cost

Robot Framework itself is open-source software. The framework does not dictate the cost of your browser infrastructure, test environment, external services, or any separately selected library. A project’s runtime is usually driven by the operations performed by its libraries and system under test. Reduce unnecessary waits, run only relevant tagged tests during fast feedback, and keep a fuller suite for the appropriate validation stage.

Reliability depends on stable setup and meaningful synchronization. Pin compatible dependencies, isolate test data, make environment configuration explicit, wait for the condition the test actually needs, and retain XML and HTML artifacts for failed runs. A timeout should be long enough for real environmental variation but bounded so a genuine failure does not stall a suite indefinitely.

For visual capture, consider whether you need browser interaction or just an image/PDF of a URL. A browser library is appropriate when the test must perform user actions and assert behavior. ScreenshotNeo is a separate usage-based option with a free allowance and published plan quotas; only clean shots are billed, according to its supplied product details. Review current plan details before adopting it.

Frequently asked questions

Is Robot Framework only for browser testing?

No. The framework can be paired with libraries for web applications, APIs, RPA, and other interfaces. The integration library determines how the suite reaches the system under test.

Do I need to write Python to use it?

Basic suites are written in Robot Framework’s keyword-driven test-data syntax. Python is the runtime foundation and can be used for custom libraries or extensions when needed, but it is not required for the simple suite in this guide.

Can I generate reports again without rerunning the tests?

Yes. Robot Framework’s Rebot tool can process existing output files; check the installed version’s User Guide and rebot --help for the exact options.

Where should I begin when a test fails?

Start with the first failure in the detailed log, then verify the keyword, library, inputs, and application state before changing the test.