Subpackages

Submodules

robot.errors module

Exceptions and return codes.

Unless noted otherwise, external libraries should not use exceptions defined here.

exceptionrobot.errors.RobotError(message='',details='')[source]

Bases:Exception

Base class for Robot Framework errors.

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

propertymessage

exceptionrobot.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 frameworkcomponent is used incorrectly. This is pretty much same as‘Internal Error’ and should of course never happen.

exceptionrobot.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).

exceptionrobot.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).

exceptionrobot.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).

exceptionrobot.errors.TimeoutExceeded(message='',test_timeout=True)[source]

Bases:RobotError

Used when a test or keyword timeout occurs.

This exception cannot be caught be TRY/EXCEPT or by keywords runningother keywords such asWait Until Keyword Succeeds.

Library keywords can catch this exception to handle cleanup activities ifa timeout occurs. They should reraise it immediately when they are done.Attributestest_timeout andkeyword_timeout are not partof the public API and should not be used by libraries.

Prior to Robot Framework 7.3, this exception was namedTimeoutError.It was renamed to not conflict with Python’s standard exception withthe same name. The old name still exists as a backwards compatible alias.

propertykeyword_timeout

robot.errors.TimeoutError

alias ofTimeoutExceeded

exceptionrobot.errors.Information(message:str,status_rc:bool=True)[source]

Bases:RobotError

Used by argument parser with –help or –version.

exceptionrobot.errors.ExecutionStatus(message:str,test_timeout:bool=False,keyword_timeout:bool=False,syntax:bool=False,exit:bool=False,continue_on_failure:bool=False,skip:bool=False,return_value:object=None)[source]

Bases:RobotError

Base class for exceptions communicating status in test execution.

propertytimeout

propertydont_continue

propertycontinue_on_failure

can_continue(context,templated=False)[source]

get_errors()[source]

propertystatus

exceptionrobot.errors.ExecutionFailed(message:str,test_timeout:bool=False,keyword_timeout:bool=False,syntax:bool=False,exit:bool=False,continue_on_failure:bool=False,skip:bool=False,return_value:object=None)[source]

Bases:ExecutionStatus

Used for communicating failures in test execution.

exceptionrobot.errors.HandlerExecutionFailed(details)[source]

Bases:ExecutionFailed

exceptionrobot.errors.ExecutionFailures(errors,message=None)[source]

Bases:ExecutionFailed

get_errors()[source]

exceptionrobot.errors.UserKeywordExecutionFailed(run_errors=None,teardown_errors=None)[source]

Bases:ExecutionFailures

exceptionrobot.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]

propertyearlier_failures

propertystatus

exceptionrobot.errors.PassExecution(message)[source]

Bases:ExecutionPassed

Used by ‘Pass Execution’ keyword.

exceptionrobot.errors.ContinueLoop[source]

Bases:ExecutionPassed

Used by CONTINUE statement.

exceptionrobot.errors.BreakLoop[source]

Bases:ExecutionPassed

Used by BREAK statement.

exceptionrobot.errors.ReturnFromKeyword(return_value=None,failures=None)[source]

Bases:ExecutionPassed

Used by ‘RETURN’ statement.

exceptionrobot.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 followingapproaches:

python-mrobot.libdocpythonpath/to/robot/libdoc.py

This module also exposes the following public API:

• libdoc_cli() function for simple command line tools.

• libdoc() function as a high level programmatic API.

• LibraryDocumentation() as the API to generateLibraryDoc instances.

Libdoc itself is implemented in thelibdocpkg package.

classrobot.libdoc.LibDoc[source]

Bases:Application

validate(options,arguments)[source]

main(args,name='',version='',format=None,docformat=None,specdocformat=None,theme=None,language=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.Defaults tosys.argv[1:] if not given.

• exit – IfTrue, callsys.exit automatically.

Thelibdoc() function may work better in programmatic usage.

Example:

fromrobot.libdocimportlibdoc_clilibdoc_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 resourcefile 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 ofthe output file. Possible values are'HTML','XML','JSON'and'LIBSPEC'.

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

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

• quiet – When true, the path of the generated output file is notprinted the console.

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

Example:

fromrobot.libdocimportlibdoclibdoc('MyLibrary.py','MyLibrary.html',version='1.0')

robot.pythonpathsetter module

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

When, for example,robot/run.py orrobot/libdoc.py is executed as a script,therobot directory is insys.path but its parent directory is not.Importing this module adds the parent directory tosys.path to make itpossible to import therobot module. Therobot directory itself is removedto prevent importing internal modules directly.

Does nothing if therobot module is already imported.

robot.pythonpathsetter.set_pythonpath()[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 followingapproaches:

python-mrobot.rebotpythonpath/to/robot/rebot.py

Instead ofpython it is possible to use also other Python interpreters.This module is also used by the installedrebot start-up script.

This module also providesrebot() andrebot_cli() functionsthat can be used programmatically. Other code is for internal usage.

classrobot.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 tosys.argv[1:] if not given.

• exit – IfTrue, callsys.exit with the return code denotingexecution status, otherwise just return the rc.

Entry point used when post-processing outputs from the command line, butcan also be used by custom scripts. Especially useful if the script itselfneeds to accept same arguments as accepted by Rebot, because the script canjust pass them forward directly along with the possible default values itsets itself.

Example:

fromrobotimportrebot_clirebot_cli(['--name','Example','--log','NONE','o1.xml','o2.xml'])

See also therebot() function that allows setting options as keywordarguments likename="Example" and generally has a richer API forprogrammatic Rebot execution.

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

Programmatic entry point for post-processing outputs.

Parameters:

• outputs – Paths to Robot Framework output files similarlyas when running therebot command on the command line.

• options – Options to configure processing outputs. Acceptedoptions are mostly same as normal command line options to therebotcommand. Option names match command line option long names withouthyphens so that, for example,--name becomesname.

The semantics related to passing options are exactly the same as with therun() function. See its documentation for more details.

Examples:

fromrobotimportrebotrebot('path/to/output.xml')withopen('stdout.txt','w')asstdout:rebot('o1.xml','o2.xml',name='Example',log=None,stdout=stdout)

Equivalent command line usage:

rebotpath/to/output.xmlrebot--nameExample--logNONEo1.xmlo2.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 followingapproaches:

python-mrobot.runpythonpath/to/robot/run.py

Instead ofpython it is possible to use also other Python interpreters.This module is also used by the installedrobot start-up script.

This module also providesrun() andrun_cli() functionsthat can be used programmatically. Other code is for internal usage.

classrobot.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 tosys.argv[1:] if not given.

• exit – IfTrue, callsys.exit with the return code denotingexecution status, otherwise just return the rc.

Entry point used when running tests from the command line, but can alsobe used by custom scripts that execute tests. Especially useful if thescript itself needs to accept same arguments as accepted by Robot Framework,because the script can just pass them forward directly along with thepossible default values it sets itself.

Example:

fromrobotimportrun_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 therun() function that allows setting options as keywordarguments likename="Example" and generally has a richer API forprogrammatic 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 similarlyas when running therobot command on the command line.

• options – Options to configure and control execution. Acceptedoptions are mostly same as normal command line options to therobotcommand. Option names match command line option long names withouthyphens so that, for example,--name becomesname.

Most options that can be given from the command line work. An exceptionis that options--pythonpath,--argumentfile,--help and--version are not supported.

Options that can be given on the command line multiple times can bepassed as lists. For example,include=['tag1','tag2'] is equivalentto--includetag1--includetag2. If such options are used only once,they can be given also as a single string likeinclude='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 stringNONE as a special value can also be usedwith PythonNone. For example, usinglog=None is equivalent to--logNONE.

listener,prerunmodifier andprerebotmodifier options allowpassing values as Python objects in addition to module names these commandline options support. For example,run('tests',listener=MyListener()).

To capture the standard output and error streams, pass an open file orfile-like object as special keyword argumentsstdout andstderr,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 250denote the number of failed tests, and values between 251-255 are for otherstatuses documented in the Robot Framework User Guide.

Example:

fromrobotimportrunrun('path/to/tests.robot')run('tests.robot',include=['tag1','tag2'],splitlog=True)withopen('stdout.txt','w')asstdout:run('t1.robot','t2.robot',name='Example',log=None,stdout=stdout)

Equivalent command line usage:

robotpath/to/tests.robotrobot--includetag1--includetag2--splitlogtests.robotrobot--nameExample--logNONEt1.robott2.robot>stdout.txt

robot.testdoc module

Module implementing the command line entry point for theTestdoc tool.

This module can be executed from the command line using the followingapproaches:

python-mrobot.testdocpythonpath/to/robot/testdoc.py

Instead ofpython it is possible to use also other Python interpreters.

This module also providestestdoc() andtestdoc_cli() functionsthat can be used programmatically. Other code is for internal usage.

classrobot.testdoc.TestDoc[source]

Bases:Application

main(datasources,title=None,**options)[source]

robot.testdoc.TestSuiteFactory(datasources,**options)[source]

classrobot.testdoc.TestdocModelWriter(output,suite,title=None)[source]

Bases:ModelWriter

write(line)[source]

write_data()[source]

classrobot.testdoc.JsonConverter(output_path=None)[source]

Bases:object

convert(suite)[source]

robot.testdoc.testdoc_cli(arguments)[source]

ExecutesTestdoc similarly as from the command line.

Parameters:

arguments – command line arguments as a list of strings.

For programmatic usage thetestdoc() function is typically better. Ithas a better API for that and does not callsys.exit() likethis function.

Example:

fromrobot.testdocimporttestdoc_clitestdoc_cli(['--title','Test Plan','mytests','plan.html'])

robot.testdoc.testdoc(*arguments,**options)[source]

ExecutesTestdoc programmatically.

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

Example:

fromrobot.testdocimporttestdoctestdoc('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]