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

Executes given Robot Framework data sources with given options.

Data sources are paths to files and directories, similarly as when running robot command from the command line. Options are given as keyword arguments and their names are same as long command line options except without hyphens.

Options that can be given on the command line multiple times can be passed as lists like include=[‘tag1’, ‘tag2’]. If such option is used only once, it can be given also as a single string like include=’tag’.

Additionally listener, prerunmodifier and prerebotmodifier options support passing values as instances in addition to module names. For example, run(‘tests.robot’, listener=Listener(), prerunmodifier=Modifier()).

To capture stdout and/or stderr streams, pass open file objects in as special keyword arguments stdout and stderr, respectively.

A return code is returned similarly as when running on the command line.

Example:

from robot import run

run('path/to/tests.html', include=['tag1', 'tag2'])
with open('stdout.txt', 'w') as stdout:
    run('t1.txt', 't2.txt', report='r.html', log='NONE', stdout=stdout)

Equivalent command line usage:

robot --include tag1 --include tag2 path/to/tests.html
robot --report r.html --log NONE t1.txt t2.txt > stdout.txt
robot.run_cli(arguments)[source]

Command line execution entry point for running tests.

Parameters:arguments – Command line arguments as a list of strings.

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

Example:

from robot import run_cli

run_cli(['--include', 'tag', 'path/to/tests.html'])
robot.rebot(*datasources, **options)[source]

Creates reports/logs from given Robot output files with given options.

Given input files are paths to Robot output files similarly as when running rebot from the command line. Options are given as keywords arguments and their names are same as long command line options without hyphens.

Options that can be given on the command line multiple times can be passed as lists like include=[‘tag1’, ‘tag2’]. If such option is used only once, it can be given also as a single string like include=’tag’.

To capture stdout and/or stderr streams, pass open file objects in as special keyword arguments stdout and stderr, respectively.

A return code is returned similarly as when running on the command line.

Examples:

from robot import rebot

rebot('path/to/output.xml')
with open('stdout.txt', 'w') as stdout:
    rebot('o1.xml', 'o2.xml', report='r.html', log='NONE', stdout=stdout)

Equivalent command line usage:

rebot path/to/output.xml
rebot --report r.html --log NONE o1.xml o2.xml > stdout.txt
robot.rebot_cli(arguments)[source]

Command line execution entry point for running rebot.

Parameters:arguments – Command line arguments as a list of strings.

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

Example:

from robot import rebot_cli

rebot_cli(['--report', 'r.html', '--log', 'NONE', 'o1.xml', 'o2.xml'])

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: exceptions.Exception

Base class for Robot Framework errors.

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

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

Bases: robot.errors.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.

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

Bases: robot.errors.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).

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

Bases: robot.errors.DataError

Used when variable does not exist.

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

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

Bases: robot.errors.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).

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

Bases: robot.errors.RobotError

Used by argument parser with –help or –version.

args
message
exception robot.errors.ExecutionFailed(message, timeout=False, syntax=False, exit=False, continue_on_failure=False, return_value=None)[source]

Bases: robot.errors.RobotError

Used for communicating failures in test execution.

message
dont_continue
continue_on_failure
can_continue(teardown=False, templated=False, dry_run=False)[source]
get_errors()[source]
status
args
exception robot.errors.HandlerExecutionFailed(details)[source]

Bases: robot.errors.ExecutionFailed

continue_on_failure
args
can_continue(teardown=False, templated=False, dry_run=False)
dont_continue
get_errors()
message
status
exception robot.errors.ExecutionFailures(errors, message=None)[source]

Bases: robot.errors.ExecutionFailed

message
get_errors()[source]
args
can_continue(teardown=False, templated=False, dry_run=False)
continue_on_failure
dont_continue
status
exception robot.errors.UserKeywordExecutionFailed(run_errors=None, teardown_errors=None)[source]

Bases: robot.errors.ExecutionFailures

message
args
can_continue(teardown=False, templated=False, dry_run=False)
continue_on_failure
dont_continue
get_errors()
status
exception robot.errors.ExecutionPassed(message=None, **kwargs)[source]

Bases: robot.errors.ExecutionFailed

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]
earlier_failures
status
args
can_continue(teardown=False, templated=False, dry_run=False)
continue_on_failure
dont_continue
get_errors()
message
exception robot.errors.PassExecution(message)[source]

Bases: robot.errors.ExecutionPassed

Used by ‘Pass Execution’ keyword.

args
can_continue(teardown=False, templated=False, dry_run=False)
continue_on_failure
dont_continue
earlier_failures
get_errors()
message
set_earlier_failures(failures)
status
exception robot.errors.ContinueForLoop(message=None, **kwargs)[source]

Bases: robot.errors.ExecutionPassed

Used by ‘Continue For Loop’ keyword.

args
can_continue(teardown=False, templated=False, dry_run=False)
continue_on_failure
dont_continue
earlier_failures
get_errors()
message
set_earlier_failures(failures)
status
exception robot.errors.ExitForLoop(message=None, **kwargs)[source]

Bases: robot.errors.ExecutionPassed

Used by ‘Exit For Loop’ keyword.

args
can_continue(teardown=False, templated=False, dry_run=False)
continue_on_failure
dont_continue
earlier_failures
get_errors()
message
set_earlier_failures(failures)
status
exception robot.errors.ReturnFromKeyword(return_value)[source]

Bases: robot.errors.ExecutionPassed

Used by ‘Return From Keyword’ keyword.

args
can_continue(teardown=False, templated=False, dry_run=False)
continue_on_failure
dont_continue
earlier_failures
get_errors()
message
set_earlier_failures(failures)
status
exception robot.errors.RemoteError(message='', details='', fatal=False, continuable=False)[source]

Bases: robot.errors.RobotError

Used by Remote library to report remote errors.

args
message

robot.jarrunner module

class robot.jarrunner.JarRunner[source]

Bases: sphinx.ext.autodoc.RobotPythonRunner

Used for Java-Jython interop when RF is executed from .jar file.

run(args)[source]

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

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

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

Libdoc itself is implemented in the libdocpkg package.

class robot.libdoc.LibDoc[source]

Bases: robot.utils.application.Application

validate(options, arguments)[source]
main(args, name='', version='', format=None, docformat=None)[source]
console(msg)
execute(*arguments, **options)
execute_cli(cli_arguments)
parse_arguments(cli_args)

Public interface for parsing command line arguments.

Parameters:cli_args – Command line arguments as a list
Returns:options (dict), arguments (list)
Raises:Information when –help or –version used
Raises:DataError when parsing fails
robot.libdoc.libdoc_cli(arguments)[source]

Executes Libdoc similarly as from the command line.

Parameters:arguments – Command line arguments as a list of strings.

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

Example:

from robot.libdoc import libdoc_cli

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

Executes libdoc.

Arguments have same semantics as Libdoc command line options with same names.

Example:

from robot.libdoc import libdoc

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

robot.pythonpathsetter module

Module that adds directories needed by Robot to sys.path when imported.

robot.pythonpathsetter.add_path(path, end=False)[source]
robot.pythonpathsetter.remove_path(path)[source]

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, jyrebot and ipyrebot start-up scripts.

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: robot.run.RobotFramework

main(datasources, **options)[source]
console(msg)
execute(*arguments, **options)
execute_cli(cli_arguments)
parse_arguments(cli_args)

Public interface for parsing command line arguments.

Parameters:cli_args – Command line arguments as a list
Returns:options (dict), arguments (list)
Raises:Information when –help or –version used
Raises:DataError when parsing fails
validate(options, arguments)
robot.rebot.rebot_cli(arguments)[source]

Command line execution entry point for running rebot.

Parameters:arguments – Command line arguments as a list of strings.

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

Example:

from robot import rebot_cli

rebot_cli(['--report', 'r.html', '--log', 'NONE', 'o1.xml', 'o2.xml'])
robot.rebot.rebot(*datasources, **options)[source]

Creates reports/logs from given Robot output files with given options.

Given input files are paths to Robot output files similarly as when running rebot from the command line. Options are given as keywords arguments and their names are same as long command line options without hyphens.

Options that can be given on the command line multiple times can be passed as lists like include=[‘tag1’, ‘tag2’]. If such option is used only once, it can be given also as a single string like include=’tag’.

To capture stdout and/or stderr streams, pass open file objects in as special keyword arguments stdout and stderr, respectively.

A return code is returned similarly as when running on the command line.

Examples:

from robot import rebot

rebot('path/to/output.xml')
with open('stdout.txt', 'w') as stdout:
    rebot('o1.xml', 'o2.xml', report='r.html', log='NONE', stdout=stdout)

Equivalent command line usage:

rebot path/to/output.xml
rebot --report r.html --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: robot.utils.application.Application

main(datasources, **options)[source]
validate(options, arguments)[source]
console(msg)
execute(*arguments, **options)
execute_cli(cli_arguments)
parse_arguments(cli_args)

Public interface for parsing command line arguments.

Parameters:cli_args – Command line arguments as a list
Returns:options (dict), arguments (list)
Raises:Information when –help or –version used
Raises:DataError when parsing fails
robot.run.run_cli(arguments)[source]

Command line execution entry point for running tests.

Parameters:arguments – Command line arguments as a list of strings.

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

Example:

from robot import run_cli

run_cli(['--include', 'tag', 'path/to/tests.html'])
robot.run.run(*datasources, **options)[source]

Executes given Robot Framework data sources with given options.

Data sources are paths to files and directories, similarly as when running robot command from the command line. Options are given as keyword arguments and their names are same as long command line options except without hyphens.

Options that can be given on the command line multiple times can be passed as lists like include=[‘tag1’, ‘tag2’]. If such option is used only once, it can be given also as a single string like include=’tag’.

Additionally listener, prerunmodifier and prerebotmodifier options support passing values as instances in addition to module names. For example, run(‘tests.robot’, listener=Listener(), prerunmodifier=Modifier()).

To capture stdout and/or stderr streams, pass open file objects in as special keyword arguments stdout and stderr, respectively.

A return code is returned similarly as when running on the command line.

Example:

from robot import run

run('path/to/tests.html', include=['tag1', 'tag2'])
with open('stdout.txt', 'w') as stdout:
    run('t1.txt', 't2.txt', report='r.html', log='NONE', stdout=stdout)

Equivalent command line usage:

robot --include tag1 --include tag2 path/to/tests.html
robot --report r.html --log NONE t1.txt t2.txt > 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: robot.utils.application.Application

main(datasources, title=None, **options)[source]
console(msg)
execute(*arguments, **options)
execute_cli(cli_arguments)
parse_arguments(cli_args)

Public interface for parsing command line arguments.

Parameters:cli_args – Command line arguments as a list
Returns:options (dict), arguments (list)
Raises:Information when –help or –version used
Raises:DataError when parsing fails
validate(options, arguments)
class robot.testdoc.TestdocModelWriter(output, suite, title=None)[source]

Bases: robot.htmldata.htmlfilewriter.ModelWriter

write(line)[source]
write_data()[source]
handles(line)
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.tidy module

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

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

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

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

This module also provides Tidy class and tidy_cli() function that can be used programmatically. Other code is for internal usage.

class robot.tidy.Tidy(format='txt', use_pipes=False, space_count=4, line_separator='n')[source]

Bases: object

Programmatic API for the Tidy tool.

Arguments accepted when creating an instance have same semantics as Tidy command line options with same names.

file(path, output=None)[source]

Tidy a file.

Parameters:
  • path – Path of the input file.
  • output – Path of the output file. If not given, output is returned.

Use inplace() to tidy files in-place.

inplace(*paths)[source]

Tidy file(s) in-place.

Parameters:paths – Paths of the files to to process.
directory(path)[source]

Tidy a directory.

Parameters:path – Path of the directory to process.

All files in a directory, recursively, are processed in-place.

class robot.tidy.TidyCommandLine[source]

Bases: robot.utils.application.Application

Command line interface for the Tidy tool.

Typically tidy_cli() is a better suited for command line style usage and Tidy for other programmatic usage.

main(arguments, recursive=False, inplace=False, format='txt', usepipes=False, spacecount=4, lineseparator='\n')[source]
validate(opts, args)[source]
console(msg)
execute(*arguments, **options)
execute_cli(cli_arguments)
parse_arguments(cli_args)

Public interface for parsing command line arguments.

Parameters:cli_args – Command line arguments as a list
Returns:options (dict), arguments (list)
Raises:Information when –help or –version used
Raises:DataError when parsing fails
class robot.tidy.ArgumentValidator[source]

Bases: object

mode_and_arguments(args, recursive, inplace, **others)[source]
format(args, format, inplace, recursive, **others)[source]
line_sep(lineseparator, **others)[source]
spacecount(spacecount)[source]
robot.tidy.tidy_cli(arguments)[source]

Executes Tidy similarly as from the command line.

Parameters:arguments – Command line arguments as a list of strings.

Example:

from robot.tidy import tidy_cli

tidy_cli(['--format', 'txt', 'tests.html'])

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]