0
# Robot Framework
1
2
Robot Framework is a comprehensive automation framework designed for acceptance testing, acceptance test-driven development (ATDD), and robotic process automation (RPA). It features a plain text syntax that makes test creation accessible to both technical and non-technical users, while supporting extensive customization through generic and custom libraries.
3
4
## Package Information
5
6
- **Package Name**: robotframework
7
- **Language**: Python
8
- **Installation**: `pip install robotframework`
9
- **Python Compatibility**: 3.8+
10
- **License**: Apache License 2.0
11
12
## Core Imports
13
14
Main programmatic APIs:
15
16
```python
17
from robot import run, run_cli, rebot, rebot_cli
18
```
19
20
Public API classes and functions:
21
22
```python
23
from robot.api import (
24
TestSuite, TestSuiteBuilder, ResultWriter, ExecutionResult, ResultVisitor,
25
SuiteVisitor, TypeInfo, Languages, Language
26
)
27
```
28
29
Library development APIs:
30
31
```python
32
from robot.api import keyword, library, not_keyword
33
from robot.api import Failure, ContinuableFailure, Error, FatalError, SkipExecution
34
from robot.api import logger
35
from robot.api.interfaces import DynamicLibrary, HybridLibrary, ListenerV2, ListenerV3, Parser
36
```
37
38
Parsing APIs:
39
40
```python
41
from robot.api.parsing import get_model, get_tokens, Token, ModelVisitor, ModelTransformer
42
```
43
44
## Basic Usage
45
46
### Running Tests Programmatically
47
48
```python
49
from robot import run
50
51
# Run tests from a directory
52
result = run('tests/')
53
54
# Run specific test files with options
55
result = run('tests/example.robot', outputdir='results', loglevel='DEBUG')
56
57
# Run with custom settings
58
result = run(
59
'tests/',
60
outputdir='results',
61
report='custom_report.html',
62
log='custom_log.html',
63
include=['smoke', 'critical'],
64
exclude=['slow']
65
)
66
67
print(f"Tests run: {result.return_code}")
68
```
69
70
### Creating Test Suites Programmatically
71
72
```python
73
from robot.api import TestSuite
74
75
# Create a test suite
76
suite = TestSuite('Example Suite')
77
78
# Add a test case
79
test = suite.tests.create('Example Test')
80
test.keywords.create('Log', args=['Hello, Robot Framework!'])
81
test.keywords.create('Should Be Equal', args=['${GREETING}', 'Hello'])
82
83
# Run the suite
84
result = suite.run(outputdir='results')
85
```
86
87
### Processing Test Results
88
89
```python
90
from robot.api import ExecutionResult
91
92
# Read execution results from XML
93
result = ExecutionResult('output.xml')
94
95
# Access test statistics
96
print(f"Total tests: {result.suite.test_count}")
97
print(f"Passed: {result.suite.statistics.passed}")
98
print(f"Failed: {result.suite.statistics.failed}")
99
100
# Iterate through test cases
101
for test in result.suite.tests:
102
print(f"Test: {test.name} - Status: {test.status}")
103
```
104
105
## Architecture
106
107
Robot Framework follows a layered architecture that separates concerns and enables extensibility:
108
109
### Core Components
110
111
- **Test Execution Engine**: Orchestrates test execution, keyword resolution, and result collection
112
- **Test Data Parser**: Converts test files into executable test suite objects
113
- **Keyword Library System**: Manages built-in and custom test libraries with their keywords
114
- **Variable System**: Handles variable resolution, scoping, and evaluation
115
- **Result Processing**: Generates reports, logs, and output files from execution results
116
117
### Extensibility Points
118
119
- **Test Libraries**: Custom keyword implementations using static, dynamic, or hybrid APIs
120
- **Listeners**: Event-driven extensions that monitor and react to test execution events
121
- **Parsers**: Custom parsers for non-standard test data formats
122
- **Pre-run/Pre-rebot Modifiers**: Suite and result processing extensions
123
- **Remote Libraries**: Network-accessible keyword implementations
124
125
This architecture enables Robot Framework to support diverse testing scenarios while maintaining simplicity for end users and providing powerful extension points for advanced use cases.
126
127
## Capabilities
128
129
### Core Execution
130
131
Test execution, result processing, and programmatic control of Robot Framework's main functionality. Includes running tests, processing outputs, and accessing execution results.
132
133
```python { .api }
134
def run(*tests, **options): ...
135
def run_cli(arguments=None, exit=True): ...
136
def rebot(*outputs, **options): ...
137
def rebot_cli(arguments=None, exit=True): ...
138
139
class TestSuite: ...
140
class TestSuiteBuilder: ...
141
class ExecutionResult: ...
142
class ResultWriter: ...
143
```
144
145
[Core Execution](./core-execution.md)
146
147
### Library Development
148
149
APIs for creating custom test libraries, including decorators, exceptions, logging, and base classes for different library types.
150
151
```python { .api }
152
@keyword(name=None, tags=(), types=())
153
@library(scope=None, version=None, auto_keywords=False)
154
@not_keyword
155
156
class Failure(AssertionError): ...
157
class Error(RuntimeError): ...
158
class SkipExecution(Exception): ...
159
160
def info(msg: str, html: bool = False, also_console: bool = False): ...
161
def warn(msg: str, html: bool = False): ...
162
def error(msg: str, html: bool = False): ...
163
```
164
165
[Library Development](./library-development.md)
166
167
### Parsing and Model
168
169
Test data parsing, AST model manipulation, and programmatic access to Robot Framework's internal data structures.
170
171
```python { .api }
172
def get_model(source, **options): ...
173
def get_tokens(source, **options): ...
174
175
class Token: ...
176
class ModelVisitor: ...
177
class ModelTransformer: ...
178
class SuiteVisitor: ...
179
```
180
181
[Parsing and Model](./parsing-model.md)
182
183
### Built-in Libraries
184
185
Standard test libraries that provide essential keywords for common testing tasks including system operations, data manipulation, and test control flow.
186
187
```python { .api }
188
class BuiltIn: ...
189
class Collections: ...
190
class String: ...
191
class OperatingSystem: ...
192
class Process: ...
193
class DateTime: ...
194
```
195
196
[Built-in Libraries](./builtin-libraries.md)
197
198
### Configuration and Variables
199
200
Settings, language support, type conversion, and variable handling systems for customizing Robot Framework behavior.
201
202
```python { .api }
203
class TypeInfo: ...
204
class Languages: ...
205
class Language: ...
206
207
def contains_variable(string): ...
208
def is_variable(string): ...
209
def evaluate_expression(expression, variables): ...
210
```
211
212
[Configuration and Variables](./configuration-variables.md)
213
214
## Documentation Tools
215
216
Robot Framework includes tools for generating documentation from test libraries and test suites:
217
218
### Library Documentation (Libdoc)
219
220
```python { .api }
221
def libdoc_cli(arguments=None, exit=True): ...
222
def libdoc(library_or_resource, outfile, **options): ...
223
```
224
225
Generate HTML documentation for test libraries showing available keywords, their arguments, and documentation.
226
227
### Test Documentation (Testdoc)
228
229
```python { .api }
230
def testdoc_cli(arguments): ...
231
def testdoc(*arguments, **options): ...
232
```
233
234
Generate HTML documentation from test suites showing test cases, keywords, and test data structure.
235
236
## Command Line Tools
237
238
Robot Framework provides three main command line tools:
239
240
- **`robot`** - Execute tests and generate results
241
- **`rebot`** - Post-process existing result files
242
- **`libdoc`** - Generate library documentation
243
244
These tools can also be invoked programmatically through their corresponding CLI functions.
245
246
## Types
247
248
Core type definitions used throughout the Robot Framework API:
249
250
```python { .api }
251
# Execution types
252
TestResult = int # Return code: 0 for success, non-zero for failures/errors
253
254
# Library interface types
255
Name = str
256
Arguments = Sequence[Union[str, Tuple[str], Tuple[str, Any]]]
257
Documentation = str
258
Tags = Sequence[str]
259
TypeHints = Union[Mapping[str, TypeHint], Sequence[TypeHint]]
260
261
# Parsing types
262
Token = Union[str, Tuple[str, str], Tuple[str, str, int, int]]
263
264
# Logging types
265
LOGLEVEL = Literal["TRACE", "DEBUG", "INFO", "WARN", "ERROR"]
266
267
# Decorator types
268
Scope = Literal["GLOBAL", "SUITE", "TEST", "TASK"]
269
DocFormat = Literal["ROBOT", "HTML", "TEXT", "REST"]
270
```