Robot Framework Documentation Release 4.1.1.dev1 Robot Framework developers Jul 19, 2021 Contents 1 Entry points 3 2 Java entry points 5 3 Public API 7 4 All packages 9 4.1 robot package...............................................9 5 Indices 449 Python Module Index 451 Index 455 i ii Robot Framework Documentation, Release 4.1.1.dev1 This documentation describes the public API of Robot Framework. Installation, basic usage and wealth of other topics are covered by the Robot Framework User Guide. Main API entry points are documented here, but the lower level implementation details are not always that well documented. If the documentation is insufficient, it is possible to view the source code by clicking [source] link in the documentation. In case viewing the source is not helpful either, questions may be sent to the robotframework-users mailing list. Contents 1 Robot Framework Documentation, Release 4.1.1.dev1 2 Contents CHAPTER 1 Entry points Command line entry points are implemented as Python modules and they also provide programmatic APIs. Following entry points exist: • robot.run entry point for executing tests. • robot.rebot entry point for post-processing outputs (Rebot). • robot.libdoc entry point for Libdoc tool. • robot.testdoc entry point for Testdoc tool. • robot.tidy entry point for Tidy tool. See built-in tool documentation for more details about Rebot, Libdoc, Testdoc, and Tidy tools. 3 Robot Framework Documentation, Release 4.1.1.dev1 4 Chapter 1. Entry points CHAPTER 2 Java entry points The Robot Framework Jar distribution contains also a Java API, in the form of the org.robotframework.RobotFramework class. 5 Robot Framework Documentation, Release 4.1.1.dev1 6 Chapter 2. Java entry points CHAPTER 3 Public API robot.api package exposes the public APIs of Robot Framework. Unless stated otherwise, the APIs exposed in this package are considered stable, and thus safe to use when building external tools on top of Robot Framework. Notice that all parsing APIs were rewritten in Robot Framework 3.2. Currently exposed APIs are: • logger module for libraries’ logging purposes. • deco module with decorators libraries can utilize. • exceptions module containing exceptions that libraries can utilize for reporting failures and other events. These exceptions can be imported also directly via robot.api like from robot.api import SkipExecution. • parsing module exposing the parsing APIs. This module is new in Robot Framework 4.0. Various parsing related functions and classes were exposed directly via robot.api already in Robot Framework 3.2, but they are effectively deprecated and will be removed in the future. • TestSuite class for creating executable test suites programmatically and TestSuiteBuilder class for creating such suites based on existing test data on the file system. • SuiteVisitor abstract class for processing testdata before execution. This can be used as a base for imple- menting a pre-run modifier that is taken into use with --prerunmodifier commandline option. • ExecutionResult() factory method for reading execution results from XML output files and ResultVisitor abstract class to ease further processing the results. ResultVisitor can also be used as a base for pre-Rebot modifier that is taken into use with --prerebotmodifier commandline option. • ResultWriter class for writing reports, logs, XML outputs, and XUnit files. Can write results based on XML outputs on the file system, as well as based on the result objects returned by the ExecutionResult() or an executed TestSuite. All of the above names can be imported like: from robot.api import ApiName 7 Robot Framework Documentation, Release 4.1.1.dev1 See documentations of the individual APIs for more details. Tip: APIs related to the command line entry points are exposed directly via the robot root package. 8 Chapter 3. Public API CHAPTER 4 All packages All robot packages are listed below. Typically you should not need to import anything from them directly, but the above public APIs may return objects implemented in them. 4.1 robot package The root of the Robot Framework package. The command line entry points provided by the framework are exposed for programmatic usage as follows: • run(): Function to run tests. • run_cli(): Function to run tests with command line argument processing. • rebot(): Function to post-process outputs. • rebot_cli(): Function to post-process outputs with command line argument processing. • libdoc: Module for library documentation generation. • testdoc: Module for test case documentation generation. • tidy: Module for test data clean-up and format change. All the functions above can be imported like from robot import run. Functions and classes provided by the modules need to be imported like from robot.libdoc import libdoc_cli. The functions and modules listed above are considered stable. Other modules in this package are for for internal usage and may change without prior notice. Tip: More public APIs are exposed by the robot.api package. robot.run(*tests, **options) Programmatic entry point for running tests. Parameters 9 Robot Framework Documentation, Release 4.1.1.dev1 • tests – Paths to test case files/directories to be executed similarly as when running the robot command on the command line. • options – Options to configure and control execution. Accepted options are mostly same as normal command line options to the robot command. Option names match command line option long names without hyphens so that, for example, --name becomes name. Most options that can be given from the command line work. An exception is that options --pythonpath, --argumentfile, --help and --version are not supported. Options that can be given on the command line multiple times can be passed as lists. For example, include=['tag1', 'tag2'] is equivalent to --include tag1 --include tag2. If such op- tions are used only once, they can be given also as a single string like include='tag'. Options that accept no value can be given as Booleans. For example, dryrun=True is same as using the --dryrun option. Options that accept string NONE as a special value can also be used with Python None. For example, using log=None is equivalent to --log NONE. listener, prerunmodifier and prerebotmodifier options allow passing values as Python ob- jects in addition to module names these command line options support. For example, run('tests', listener=MyListener()). To capture the standard output and error streams, pass an open file or file-like object as special keyword argu- ments stdout and stderr, respectively. A return code is returned similarly as when running on the command line. Zero means that tests were executed and no critical test failed, values up to 250 denote the number of failed critical tests, and values between 251-255 are for other statuses documented in the Robot Framework User Guide. Example: from robot import run run('path/to/tests.robot') run('tests.robot', include=['tag1','tag2'], splitlog= True) with open('stdout.txt','w') as stdout: run('t1.robot','t2.robot', name='Example', log= None, stdout=stdout) Equivalent command line usage: robot path/to/tests.robot robot--include tag1--include tag2--splitlog tests.robot robot--name Example--log NONE t1.robot t2.robot> stdout.txt robot.run_cli(arguments=None, exit=True) Command line execution entry point for running tests. Parameters • arguments – Command line options and arguments as a list of strings. Starting from RF 3.1, defaults to sys.argv[1:] if not given. • exit – If True, call sys.exit with the return code denoting execution status, otherwise just return the rc. Entry point used when running tests from the command line, but can also be used by custom scripts that execute tests. Especially useful if the script itself needs to accept same arguments as accepted by Robot Framework, because the script can just pass them forward directly along with the possible default values it sets itself. Example: 10 Chapter 4. All packages Robot Framework Documentation, Release 4.1.1.dev1 from robot import run_cli # Run tests and return the return code. rc= run_cli(['--name','Example','tests.robot'], exit= False) # Run tests and exit to the system automatically. run_cli(['--name','Example','tests.robot']) See also the run() function that allows setting options as keyword arguments like name="Example" and generally has a richer API for programmatic test execution. robot.rebot(*outputs, **options) Programmatic entry point for post-processing outputs. Parameters • outputs – Paths to Robot Framework output files similarly as when running the rebot command on the command line. • options – Options to configure processing outputs. Accepted options are mostly same as normal command line options to the rebot command. Option names match command line option long names without hyphens so that, for example, --name becomes name. The semantics related to passing options are exactly the same as with the run() function. See its documentation for more details. Examples: from robot import rebot rebot('path/to/output.xml') with open('stdout.txt','w') as stdout: rebot('o1.xml','o2.xml', name='Example', log= None, stdout=stdout) Equivalent command line usage: rebot path/to/output.xml rebot--name Example--log NONE o1.xml o2.xml> stdout.txt robot.rebot_cli(arguments=None, exit=True) Command line execution entry point for post-processing outputs. Parameters • arguments – Command line options and arguments as a list of strings. Starting from RF 3.1, defaults to sys.argv[1:] if not given. • exit – If True, call sys.exit with the return code denoting execution status, otherwise just return the rc. Entry point used when post-processing outputs from the command line, but can also be used by custom scripts. Especially useful if the script itself needs to accept same arguments as accepted by Rebot, because the script can just pass them forward directly along with the possible default values it sets itself. Example: from robot import rebot_cli rebot_cli(['--name','Example','--log','NONE','o1.xml','o2.xml']) 4.1.