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.

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 internal usage and may change without prior notice.

Tip

More public APIs are exposed by the robot.api package.

robot.run(*tests, **options)[source]

Programmatic entry point for running tests.

Parameters:

  • 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 options 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 objects 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 arguments 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 test failed, values up to 250 denote the number of failed 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)[source]

Command line execution entry point for running tests.

Parameters:

  • arguments – Command line options and arguments as a list of strings. 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:

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)[source]

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)[source]

Command line execution entry point for post-processing outputs.

Parameters:

  • arguments – Command line options and arguments as a list of strings. 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'])

See also the rebot() function that allows setting options as keyword arguments like name="Example" and generally has a richer API for programmatic Rebot execution.

Subpackages

Submodules

robot.errors module

Exceptions and return codes used internally.

External libraries should not used exceptions defined here.

exception robot.errors.RobotError(message='', details='')[source]

Bases: Exception

Base class for Robot Framework errors.

Do not raise this method but use more specific errors instead.

property message
exception robot.errors.FrameworkError(message='', details='')[source]

Bases: RobotError

Can be used when the core framework goes to unexpected state.

It is good to explicitly raise a FrameworkError if some framework component is used incorrectly. This is pretty much same as ‘Internal Error’ and should of course never happen.

exception robot.errors.DataError(message='', details='', syntax=False)[source]

Bases: RobotError

Used when the provided test data is invalid.

DataErrors are not caught by keywords that run other keywords (e.g. Run Keyword And Expect Error).

exception robot.errors.VariableError(message='', details='')[source]

Bases: DataError

Used when variable does not exist.

VariableErrors are caught by keywords that run other keywords (e.g. Run Keyword And Expect Error).

exception robot.errors.KeywordError(message='', details='')[source]

Bases: DataError

Used when no keyword is found or there is more than one match.

KeywordErrors are caught by keywords that run other keywords (e.g. Run Keyword And Expect Error).

exception robot.errors.TimeoutError(message='', test_timeout=True)[source]

Bases: RobotError

Used when a test or keyword timeout occurs.

This exception is handled specially so that execution of the current test is always stopped immediately and it is not caught by keywords executing other keywords (e.g. Run Keyword And Expect Error).

property keyword_timeout
exception robot.errors.Information(message='', details='')[source]

Bases: RobotError

Used by argument parser with –help or –version.

exception robot.errors.ExecutionStatus(message, test_timeout=False, keyword_timeout=False, syntax=False, exit=False, continue_on_failure=False, skip=False, return_value=None)[source]

Bases: RobotError

Base class for exceptions communicating status in test execution.

property timeout
property dont_continue
property continue_on_failure
can_continue(context, templated=False)[source]
get_errors()[source]
property status
exception robot.errors.ExecutionFailed(message, test_timeout=False, keyword_timeout=False, syntax=False, exit=False, continue_on_failure=False, skip=False, return_value=None)[source]

Bases: ExecutionStatus

Used for communicating failures in test execution.

exception robot.errors.HandlerExecutionFailed(details)[source]

Bases: ExecutionFailed

exception robot.errors.ExecutionFailures(errors, message=None)[source]

Bases: ExecutionFailed

get_errors()[source]
exception robot.errors.UserKeywordExecutionFailed(run_errors=None, teardown_errors=None)[source]

Bases: ExecutionFailures

exception robot.errors.ExecutionPassed(message=None, **kwargs)[source]

Bases: ExecutionStatus

Base class for all exceptions communicating that execution passed.

Should not be raised directly, but more detailed exceptions used instead.

set_earlier_failures(failures)[source]
property earlier_failures
property status
exception robot.errors.PassExecution(message)[source]

Bases: ExecutionPassed

Used by ‘Pass Execution’ keyword.

exception robot.errors.ContinueLoop[source]

Bases: ExecutionPassed

Used by CONTINUE statement.

exception robot.errors.BreakLoop[source]

Bases: ExecutionPassed

Used by BREAK statement.

exception robot.errors.ReturnFromKeyword(return_value=None, failures=None)[source]

Bases: ExecutionPassed

Used by ‘RETURN’ statement.

exception robot.errors.RemoteError(message='', details='', fatal=False, continuable=False)[source]

Bases: RobotError

Used by Remote library to report remote errors.

robot.libdoc module

Module implementing the command line entry point for the Libdoc tool.

This module can be executed from the command line using the following approaches:

python -m robot.libdoc
python path/to/robot/libdoc.py

This module also exposes the following public API:

Libdoc itself is implemented in the libdocpkg package.

class robot.libdoc.LibDoc[source]

Bases: Application

validate(options, arguments)[source]
main(args, name='', version='', format=None, docformat=None, specdocformat=None, theme=None, pythonpath=None, quiet=False)[source]
robot.libdoc.libdoc_cli(arguments=None, exit=True)[source]

Executes Libdoc similarly as from the command line.

Parameters:

  • arguments – Command line options and arguments as a list of strings. Starting from RF 4.0, defaults to sys.argv[1:] if not given.

  • exit – If True, call sys.exit automatically. New in RF 4.0.

The libdoc() function may work better in programmatic usage.

Example:

from robot.libdoc import libdoc_cli

libdoc_cli(['--version', '1.0', 'MyLibrary.py', 'MyLibrary.html'])
robot.libdoc.libdoc(library_or_resource, outfile, name='', version='', format=None, docformat=None, specdocformat=None, quiet=False)[source]

Executes Libdoc.

Parameters:

  • library_or_resource – Name or path of the library or resource file to be documented.

  • outfile – Path to the file where to write outputs.

  • name – Custom name to give to the documented library or resource.

  • version – Version to give to the documented library or resource.

  • format – Specifies whether to generate HTML, XML or JSON output. If this options is not used, the format is got from the extension of the output file. Possible values are 'HTML', 'XML', 'JSON' and 'LIBSPEC'.

  • docformat – Documentation source format. Possible values are 'ROBOT', 'reST', 'HTML' and 'TEXT'. The default value can be specified in library source code and the initial default is 'ROBOT'.

  • specdocformat – Specifies whether the keyword documentation in spec files is converted to HTML regardless of the original documentation format. Possible values are 'HTML' (convert to HTML) and 'RAW' (use original format). The default depends on the output format. New in Robot Framework 4.0.

  • quiet – When true, the path of the generated output file is not printed the console. New in Robot Framework 4.0.

Arguments have same semantics as Libdoc command line options with same names. Run libdoc --help or consult the Libdoc section in the Robot Framework User Guide for more details.

Example:

from robot.libdoc import libdoc

libdoc('MyLibrary.py', 'MyLibrary.html', version='1.0')

robot.pythonpathsetter module

Modifies sys.path if Robot Framework’s entry points are run as scripts.

When, for example, robot/run.py or robot/libdoc.py is executed as a script, the robot directory is in sys.path but its parent directory is not. Importing this module adds the parent directory to sys.path to make it possible to import the robot module. The robot directory itself is removed to prevent importing internal modules directly.

Does nothing if the robot module is already imported.

robot.rebot module

Module implementing the command line entry point for post-processing outputs.

This module can be executed from the command line using the following approaches:

python -m robot.rebot
python path/to/robot/rebot.py

Instead of python it is possible to use also other Python interpreters. This module is also used by the installed rebot start-up script.

This module also provides rebot() and rebot_cli() functions that can be used programmatically. Other code is for internal usage.

class robot.rebot.Rebot[source]

Bases: RobotFramework

main(datasources, **options)[source]
robot.rebot.rebot_cli(arguments=None, exit=True)[source]

Command line execution entry point for post-processing outputs.

Parameters:

  • arguments – Command line options and arguments as a list of strings. 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'])

See also the rebot() function that allows setting options as keyword arguments like name="Example" and generally has a richer API for programmatic Rebot execution.

robot.rebot.rebot(*outputs, **options)[source]

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.run module

Module implementing the command line entry point for executing tests.

This module can be executed from the command line using the following approaches:

python -m robot.run
python path/to/robot/run.py

Instead of python it is possible to use also other Python interpreters. This module is also used by the installed robot start-up script.

This module also provides run() and run_cli() functions that can be used programmatically. Other code is for internal usage.

class robot.run.RobotFramework[source]

Bases: Application

main(datasources, **options)[source]
validate(options, arguments)[source]
robot.run.run_cli(arguments=None, exit=True)[source]

Command line execution entry point for running tests.

Parameters:

  • arguments – Command line options and arguments as a list of strings. 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:

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.run.run(*tests, **options)[source]

Programmatic entry point for running tests.

Parameters:

  • 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 options 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 objects 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 arguments 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 test failed, values up to 250 denote the number of failed 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.testdoc module

Module implementing the command line entry point for the Testdoc tool.

This module can be executed from the command line using the following approaches:

python -m robot.testdoc
python path/to/robot/testdoc.py

Instead of python it is possible to use also other Python interpreters.

This module also provides testdoc() and testdoc_cli() functions that can be used programmatically. Other code is for internal usage.

class robot.testdoc.TestDoc[source]

Bases: Application

main(datasources, title=None, **options)[source]
robot.testdoc.TestSuiteFactory(datasources, **options)[source]
class robot.testdoc.TestdocModelWriter(output, suite, title=None)[source]

Bases: ModelWriter

write(line)[source]
write_data()[source]
class robot.testdoc.JsonConverter(output_path=None)[source]

Bases: object

convert(suite)[source]
robot.testdoc.testdoc_cli(arguments)[source]

Executes Testdoc similarly as from the command line.

Parameters:

arguments – command line arguments as a list of strings.

For programmatic usage the testdoc() function is typically better. It has a better API for that and does not call sys.exit() like this function.

Example:

from robot.testdoc import testdoc_cli

testdoc_cli(['--title', 'Test Plan', 'mytests', 'plan.html'])
robot.testdoc.testdoc(*arguments, **options)[source]

Executes Testdoc programmatically.

Arguments and options have same semantics, and options have same names, as arguments and options to Testdoc.

Example:

from robot.testdoc import testdoc

testdoc('mytests', 'plan.html', title='Test Plan')

robot.version module

robot.version.get_version(naked=False)[source]
robot.version.get_full_version(program=None, naked=False)[source]
robot.version.get_interpreter()[source]