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
```