0
# Core Execution
1

2
Robot Framework's core execution APIs provide programmatic control over test execution, result processing, and output generation. These APIs enable integration with other tools and automation systems.
3

4
## Capabilities
5

6
### Test Execution
7

8
Execute Robot Framework tests programmatically with full control over execution options and settings.
9

10
```python { .api }
11
def run(*tests, **options):
12
    """
13
    Execute Robot Framework tests programmatically.
14
    
15
    Args:
16
        *tests: Test data sources (files, directories, or suites)
17
        **options: Execution options (outputdir, loglevel, include, exclude, etc.)
18
        
19
    Returns:
20
        Result object with return_code attribute (0 for success)
21
    """
22

23
def run_cli(arguments=None, exit=True):
24
    """
25
    Execute tests with command line argument processing.
26
    
27
    Args:
28
        arguments: List of command line arguments, defaults to sys.argv[1:]
29
        exit: Whether to call sys.exit() with the result code
30
        
31
    Returns:
32
        Result object with return_code attribute
33
    """
34
```
35

36
**Usage Examples:**
37

38
```python
39
from robot import run
40

41
# Basic test execution
42
result = run('tests/acceptance.robot')
43

44
# Execute with options
45
result = run(
46
    'tests/',
47
    outputdir='results',
48
    loglevel='DEBUG',
49
    include=['smoke', 'critical'],
50
    exclude=['slow', 'manual'],
51
    variable=['ENV:production', 'VERSION:1.2.3'],
52
    listener='MyListener.py'
53
)
54

55
# Check execution result
56
if result.return_code == 0:
57
    print("All tests passed!")
58
else:
59
    print(f"Some tests failed (return code: {result.return_code})")
60
```
61

62
### Result Post-processing
63

64
Process existing Robot Framework output files to generate new reports and logs with different settings.
65

66
```python { .api }
67
def rebot(*outputs, **options):
68
    """
69
    Post-process Robot Framework output files.
70
    
71
    Args:
72
        *outputs: Output XML files to process
73
        **options: Processing options (outputdir, report, log, merge, etc.)
74
        
75
    Returns:
76
        Result object with return_code attribute
77
    """
78

79
def rebot_cli(arguments=None, exit=True):
80
    """
81
    Post-process outputs with command line argument processing.
82
    
83
    Args:
84
        arguments: List of command line arguments, defaults to sys.argv[1:]
85
        exit: Whether to call sys.exit() with the result code
86
        
87
    Returns:
88
        Result object with return_code attribute
89
    """
90
```
91

92
**Usage Examples:**
93

94
```python
95
from robot import rebot
96

97
# Merge multiple output files
98
result = rebot('output1.xml', 'output2.xml', 'output3.xml', 
99
               outputdir='merged_results',
100
               name='Combined Test Results')
101

102
# Generate new reports with filtering
103
result = rebot('output.xml',
104
               include=['critical'],
105
               exclude=['known_issue'],
106
               report='critical_report.html',
107
               log='critical_log.html')
108
```
109

110
### Programmatic Test Suite Creation
111

112
Create and execute test suites programmatically without external test files.
113

114
```python { .api }
115
class TestSuite:
116
    """
117
    Executable test suite that can be created and run programmatically.
118
    
119
    Attributes:
120
        name: Suite name
121
        doc: Suite documentation  
122
        metadata: Suite metadata dictionary
123
        tests: Collection of test cases
124
        keywords: Collection of suite keywords
125
        setup: Suite setup keyword
126
        teardown: Suite teardown keyword
127
    """
128
    
129
    def __init__(self, name='', doc='', metadata=None, source=''): ...
130
    
131
    def run(self, **options):
132
        """
133
        Execute the test suite.
134
        
135
        Args:
136
            **options: Execution options (same as run() function)
137
            
138
        Returns:
139
            Result object with execution results
140
        """
141

142
class TestSuiteBuilder:
143
    """
144
    Builder for creating test suites from file system.
145
    """
146
    
147
    def __init__(self, include_extensions=('.robot', '.txt'), **options): ...
148
    
149
    def build(self, *sources):
150
        """
151
        Build test suite(s) from given sources.
152
        
153
        Args:
154
            *sources: File or directory paths
155
            
156
        Returns:
157
            TestSuite object or collection of suites
158
        """
159
```
160

161
**Usage Examples:**
162

163
```python
164
from robot.api import TestSuite
165

166
# Create a test suite programmatically
167
suite = TestSuite('My Test Suite', doc='Example test suite')
168

169
# Add metadata
170
suite.metadata['Version'] = '1.0'
171
suite.metadata['Environment'] = 'Test'
172

173
# Create test case
174
test = suite.tests.create('Verify Greeting')
175
test.keywords.create('Set Variable', args=['${greeting}', 'Hello World'])
176
test.keywords.create('Should Contain', args=['${greeting}', 'Hello'])
177
test.keywords.create('Log', args=['Test completed successfully'])
178

179
# Add suite setup and teardown
180
suite.setup.config(name='Log', args=['Starting test suite'])
181
suite.teardown.config(name='Log', args=['Test suite completed'])
182

183
# Run the suite
184
result = suite.run(outputdir='results', loglevel='INFO')
185
```
186

187
### Result Analysis
188

189
Read and analyze Robot Framework execution results from XML output files.
190

191
```python { .api }
192
def ExecutionResult(source, include_keywords=True, flattened=True):
193
    """
194
    Factory function for creating execution result objects.
195
    
196
    Args:
197
        source: Path to output.xml file or file-like object
198
        include_keywords: Whether to include keyword-level results
199
        flattened: Whether to flatten structure
200
        
201
    Returns:
202
        Result object containing execution results
203
    """
204

205
class Result:
206
    """
207
    Execution results read from output.xml file.
208
    
209
    Attributes:
210
        suite: Root test suite with all results
211
        statistics: Test execution statistics
212
        errors: Execution errors and messages
213
    """
214
    
215
    @property
216
    def suite(self): ...
217
    @property  
218
    def statistics(self): ...
219
    @property
220
    def errors(self): ...
221

222
class ResultVisitor:
223
    """
224
    Abstract base class for processing execution results.
225
    Implement visit_* methods to process different result elements.
226
    """
227
    
228
    def visit_result(self, result): ...
229
    def visit_suite(self, suite): ...
230
    def visit_test(self, test): ...
231
    def visit_keyword(self, keyword): ...
232
    def visit_message(self, message): ...
233
```
234

235
**Usage Examples:**
236

237
```python
238
from robot.api import ExecutionResult, ResultVisitor
239

240
# Read execution results
241
result = ExecutionResult('output.xml')
242

243
# Access basic statistics
244
print(f"Test suite: {result.suite.name}")
245
print(f"Total tests: {result.suite.test_count}")
246
print(f"Passed: {result.suite.statistics.passed}")
247
print(f"Failed: {result.suite.statistics.failed}")
248

249
# Iterate through test results
250
for test in result.suite.tests:
251
    print(f"Test: {test.name}")
252
    print(f"Status: {test.status}")
253
    print(f"Message: {test.message}")
254
    print(f"Start time: {test.start_time}")
255
    print(f"End time: {test.end_time}")
256
    print(f"Elapsed time: {test.elapsed_time}")
257

258
# Custom result processor
259
class TestReportGenerator(ResultVisitor):
260
    def __init__(self):
261
        self.failed_tests = []
262
        
263
    def visit_test(self, test):
264
        if not test.passed:
265
            self.failed_tests.append({
266
                'name': test.name,
267
                'message': test.message,
268
                'tags': list(test.tags)
269
            })
270

271
# Process results with custom visitor
272
reporter = TestReportGenerator()
273
result.visit(reporter)
274
print(f"Failed tests: {len(reporter.failed_tests)}")
275
```
276

277
### Report and Log Generation
278

279
Generate HTML reports and logs from execution results with customizable formatting and content.
280

281
```python { .api }
282
class ResultWriter:
283
    """
284
    Writes reports, logs, and other output files from execution results.
285
    """
286
    
287
    def __init__(self, *sources): ...
288
    
289
    def write_results(self, **options):
290
        """
291
        Write result files (report, log, output XML, XUnit).
292
        
293
        Args:
294
            **options: Output options (report, log, output, xunit, etc.)
295
        """
296
```
297

298
**Usage Examples:**
299

300
```python
301
from robot.api import ResultWriter
302

303
# Generate reports from result object
304
writer = ResultWriter(result)
305
writer.write_results(
306
    report='custom_report.html',
307
    log='custom_log.html',
308
    outputdir='custom_results',
309
    title='Custom Test Report'
310
)
311

312
# Generate reports from XML files
313
writer = ResultWriter('output1.xml', 'output2.xml')
314
writer.write_results(
315
    report='merged_report.html',
316
    log='merged_log.html',
317
    merge=True,
318
    name='Merged Test Results'
319
)
320
```
321

322
### Suite Processing and Modification
323

324
Process and modify test suites before execution using visitor pattern.
325

326
```python { .api }
327
class SuiteVisitor:
328
    """
329
    Abstract base class for processing test suites before execution.
330
    Can be used with --prerunmodifier option.
331
    """
332
    
333
    def start_suite(self, suite): ...
334
    def end_suite(self, suite): ...
335
    def start_test(self, test): ...  
336
    def end_test(self, test): ...
337
    def start_keyword(self, keyword): ...
338
    def end_keyword(self, keyword): ...
339
    def visit_suite(self, suite): ...
340
    def visit_test(self, test): ...
341
    def visit_keyword(self, keyword): ...
342
```
343

344
**Usage Examples:**
345

346
```python
347
from robot.api import SuiteVisitor
348

349
class TagBasedFilter(SuiteVisitor):
350
    """Remove tests that don't have required tags."""
351
    
352
    def __init__(self, required_tags):
353
        self.required_tags = set(required_tags)
354
    
355
    def start_suite(self, suite):
356
        # Filter tests based on tags
357
        suite.tests = [test for test in suite.tests 
358
                      if self.required_tags.intersection(test.tags)]
359
    
360
    def start_test(self, test):
361
        # Add execution timestamp
362
        test.tags.add(f"executed:{datetime.now().isoformat()}")
363

364
# Use with programmatic execution
365
modifier = TagBasedFilter(['smoke', 'critical'])
366
suite.visit(modifier)
367
result = suite.run()
368
```
369

370
## Types
371

372
```python { .api }
373
# Return codes
374
TestResult = int  # 0 = success, >0 = failure/error count
375

376
# Execution statistics
377
class Statistics:
378
    passed: int
379
    failed: int
380
    skipped: int
381
    total: int
382

383
# Test status
384
TestStatus = Literal["PASS", "FAIL", "SKIP", "NOT RUN"]
385

386
# Time representation
387
TimeString = str  # Format: "20240101 12:00:00.000"
388
TimeDelta = str   # Format: "00:01:23.456"
389
```