robot.running package

Implements the core test execution logic.

The public API of this module consists of the following objects:

TestSuite and TestSuiteBuilder can be imported also via the robot.api package.

Note

Prior to Robot Framework 6.1, only some classes in robot.running.model were exposed via robot.running. Keyword implementation related classes are new in Robot Framework 7.0.

Examples

First, let’s assume we have the following test suite in file activate_skynet.robot:

*** Settings ***
Library    OperatingSystem

*** Test Cases ***
Should Activate Skynet
    [Tags]    smoke
    [Setup]    Set Environment Variable    SKYNET    activated
    Environment Variable Should Be Set    SKYNET

We can easily create an executable test suite based on the above file:

from robot.api import TestSuite

suite = TestSuite.from_file_system('path/to/activate_skynet.robot')

That was easy. Let’s next generate the same test suite from scratch:

from robot.api import TestSuite

suite = TestSuite('Activate Skynet')
suite.resource.imports.library('OperatingSystem')
test = suite.tests.create('Should Activate Skynet', tags=['smoke'])
test.setup.config(name='Set Environment Variable', args=['SKYNET', 'activated'])
test.body.create_keyword('Environment Variable Should Be Set', args=['SKYNET'])

Not that complicated either, especially considering the flexibility. Notice that the suite created based on the file could also be edited further using the same API.

Now that we have a test suite ready, let’s execute it and verify that the returned Result object contains correct information:

result = suite.run(output='skynet.xml')

assert result.return_code == 0
assert result.suite.name == 'Activate Skynet'
test = result.suite.tests[0]
assert test.name == 'Should Activate Skynet'
assert test.passed
stats = result.suite.statistics
assert stats.total == 1 and stats.passed == 1 and stats.failed == 0

Running the suite generates a normal output XML file, unless it is disabled by using output=None. Generating log, report, and xUnit files based on the results is possible using the ResultWriter class:

from robot.api import ResultWriter

# Report and xUnit files can be generated based on the result object.
ResultWriter(result).write_results(report='skynet.html', log=None)
# Generating log files requires processing the earlier generated output XML.
ResultWriter('skynet.xml').write_results()

Subpackages

Submodules

robot.running.bodyrunner module

class robot.running.bodyrunner.BodyRunner(context, run=True, templated=False)[source]

Bases: object

run(data, result)[source]
class robot.running.bodyrunner.KeywordRunner(context, run=True)[source]

Bases: object

run(data, result, name=None)[source]
robot.running.bodyrunner.ForRunner(context, flavor='IN', run=True, templated=False)[source]
class robot.running.bodyrunner.ForInRunner(context, run=True, templated=False)[source]

Bases: object

flavor = 'IN'
run(data, result)[source]
class robot.running.bodyrunner.ForInRangeRunner(context, run=True, templated=False)[source]

Bases: ForInRunner

flavor = 'IN RANGE'
class robot.running.bodyrunner.ForInZipRunner(context, run=True, templated=False)[source]

Bases: ForInRunner

flavor = 'IN ZIP'
class robot.running.bodyrunner.ForInEnumerateRunner(context, run=True, templated=False)[source]

Bases: ForInRunner

flavor = 'IN ENUMERATE'
class robot.running.bodyrunner.WhileRunner(context, run=True, templated=False)[source]

Bases: object

run(data, result)[source]
class robot.running.bodyrunner.IfRunner(context, run=True, templated=False)[source]

Bases: object

run(data, result)[source]
class robot.running.bodyrunner.TryRunner(context, run=True, templated=False)[source]

Bases: object

run(data, result)[source]
class robot.running.bodyrunner.WhileLimit(on_limit=None, on_limit_message=None)[source]

Bases: object

classmethod create(limit, on_limit, on_limit_message, variables)[source]
limit_exceeded()[source]
class robot.running.bodyrunner.DurationLimit(max_time, on_limit, on_limit_message)[source]

Bases: WhileLimit

class robot.running.bodyrunner.IterationCountLimit(max_iterations, on_limit, on_limit_message)[source]

Bases: WhileLimit

class robot.running.bodyrunner.NoLimit(on_limit=None, on_limit_message=None)[source]

Bases: WhileLimit

exception robot.running.bodyrunner.LimitExceeded(on_limit_pass, message)[source]

Bases: ExecutionFailed

robot.running.context module

class robot.running.context.Asynchronous[source]

Bases: object

property event_loop
close_loop()[source]
run_until_complete(coroutine)[source]
is_loop_required(obj)[source]
class robot.running.context.ExecutionContexts[source]

Bases: object

property current
property top
property namespaces
start_suite(suite, namespace, output, dry_run=False)[source]
end_suite()[source]

robot.running.dynamicmethods module

robot.running.dynamicmethods.no_dynamic_method(*args)[source]
class robot.running.dynamicmethods.DynamicMethod(instance)[source]

Bases: object

property name
class robot.running.dynamicmethods.GetKeywordNames(instance)[source]

Bases: DynamicMethod

class robot.running.dynamicmethods.RunKeyword(instance, keyword_name: str | None = None, supports_named_args: bool | None = None)[source]

Bases: DynamicMethod

property supports_named_args: bool
class robot.running.dynamicmethods.GetKeywordDocumentation(instance)[source]

Bases: DynamicMethod

class robot.running.dynamicmethods.GetKeywordArguments(instance, supports_named_args: bool | None = None)[source]

Bases: DynamicMethod

class robot.running.dynamicmethods.GetKeywordTypes(instance)[source]

Bases: DynamicMethod

class robot.running.dynamicmethods.GetKeywordTags(instance)[source]

Bases: DynamicMethod

class robot.running.dynamicmethods.GetKeywordSource(instance)[source]

Bases: DynamicMethod

robot.running.importer module

class robot.running.importer.Importer[source]

Bases: object

reset()[source]
close_global_library_listeners()[source]
import_library(name, args, alias, variables)[source]
import_resource(path, lang=None)[source]
class robot.running.importer.ImportCache[source]

Bases: object

Keeps track on and optionally caches imported items.

Handles paths in keys case-insensitively on case-insensitive OSes. Unlike dicts, this storage accepts mutable values in keys.

add(key, item=None)[source]
values()[source]

robot.running.invalidkeyword module

class robot.running.invalidkeyword.InvalidKeyword(name: str = '', args: ArgumentSpec | None = None, doc: str = '', tags: Tags | Sequence[str] = (), lineno: int | None = None, owner: ResourceFile | TestLibrary | None = None, parent: BodyItemParent | None = None, error: str | None = None)[source]

Bases: KeywordImplementation

Represents an invalid keyword call.

Keyword may not have been found, there could have been multiple matches, or the keyword call itself could have been invalid.

type: Literal['USER KEYWORD', 'LIBRARY KEYWORD', 'INVALID KEYWORD'] = 'INVALID KEYWORD'
create_runner(name, languages=None)[source]
bind(data: Keyword) InvalidKeyword[source]
embedded
owner
parent
error
class robot.running.invalidkeyword.InvalidKeywordRunner(keyword: InvalidKeyword, name: str | None = None)[source]

Bases: object

run(data: Keyword, result: Keyword, context, run=True)[source]
dry_run(data: Keyword, result: Keyword, context, run=True)

robot.running.keywordfinder module

class robot.running.keywordfinder.KeywordFinder(owner: TestLibrary | ResourceFile)[source]

Bases: Generic[K]

find(name: str, count: Literal[1]) K[source]
find(name: str, count: int | None = None) list[K]

Find keywords based on the given name.

With normal keywords matching is a case, space and underscore insensitive string comparison and there cannot be more than one match. With keywords accepting embedded arguments, matching is done against the name and there can be multiple matches.

Returns matching keywords as a list, possibly as an empty list, without any validation by default. If the optional count is used, raises a ValueError if the number of found keywords does not match. If count is 1 and exactly one keyword is found, returns that keyword directly and not as a list.

invalidate_cache()[source]
class robot.running.keywordfinder.KeywordCache(keywords: list[K])[source]

Bases: Generic[K]

find(name: str, count: int | None = None) list[K] | K[source]

robot.running.keywordimplementation module

class robot.running.keywordimplementation.KeywordImplementation(name: str = '', args: ArgumentSpec | None = None, doc: str = '', tags: Tags | Sequence[str] = (), lineno: int | None = None, owner: ResourceFile | TestLibrary | None = None, parent: BodyItemParent | None = None, error: str | None = None)[source]

Bases: ModelObject

Base class for different keyword implementations.

USER_KEYWORD = 'USER KEYWORD'
LIBRARY_KEYWORD = 'LIBRARY KEYWORD'
INVALID_KEYWORD = 'INVALID KEYWORD'
repr_args = ('name', 'args')
type: Literal['USER KEYWORD', 'LIBRARY KEYWORD', 'INVALID KEYWORD']
embedded
owner
parent
error
property name: str
property full_name: str
args

Information about accepted arguments.

It would be more correct to use term parameter instead of argument in this context, and this attribute may be renamed accordingly in the future. A forward compatible params attribute exists already now.

property params: ArgumentSpec

Keyword parameter information.

This is a forward compatible alias for args.

property doc: str
property short_doc: str
tags
property lineno: int | None
property private: bool
property source: Path | None
matches(name: str) bool[source]

Returns true if name matches the keyword name.

With normal keywords matching is a case, space and underscore insensitive string comparison. With keywords accepting embedded arguments, matching is done against the name.

resolve_arguments(args: Sequence[str], variables=None, languages=None) tuple[list, list][source]
create_runner(name: str | None, languages=None) LibraryKeywordRunner | UserKeywordRunner[source]
bind(data: Keyword) KeywordImplementation[source]

robot.running.librarykeyword module

class robot.running.librarykeyword.LibraryKeyword(owner: TestLibrary, name: str = '', args: ArgumentSpec | None = None, doc: str = '', tags: Tags | Sequence[str] = (), resolve_args_until: int | None = None, parent: BodyItemParent | None = None, error: str | None = None)[source]

Bases: KeywordImplementation

Base class for different library keywords.

type: Literal['USER KEYWORD', 'LIBRARY KEYWORD', 'INVALID KEYWORD'] = 'LIBRARY KEYWORD'
property method: Callable[[...], Any]
property lineno: int | None
create_runner(name: str | None, languages=None) LibraryKeywordRunner[source]
resolve_arguments(args: Sequence[str], variables=None, languages=None) tuple[list, list][source]
bind(data: Keyword) Self[source]
copy(**attributes) Self[source]

Return a shallow copy of this object.

Parameters:

attributes – Attributes to be set to the returned copy. For example, obj.copy(name='New name').

See also deepcopy(). The difference between copy and deepcopy is the same as with the methods having same names in the copy module.

class robot.running.librarykeyword.StaticKeyword(method_name: str, owner: TestLibrary, name: str = '', args: ArgumentSpec | None = None, doc: str = '', tags: Tags | Sequence[str] = (), resolve_args_until: int | None = None, parent: BodyItemParent | None = None, error: str | None = None)[source]

Bases: LibraryKeyword

Represents a keyword in a static library.

method_name
property method: Callable[[...], Any]

Keyword method.

property source: Path | None
classmethod from_name(name: str, owner: TestLibrary) StaticKeyword[source]
copy(**attributes) StaticKeyword[source]

Return a shallow copy of this object.

Parameters:

attributes – Attributes to be set to the returned copy. For example, obj.copy(name='New name').

See also deepcopy(). The difference between copy and deepcopy is the same as with the methods having same names in the copy module.

class robot.running.librarykeyword.DynamicKeyword(owner: DynamicLibrary, name: str = '', args: ArgumentSpec | None = None, doc: str = '', tags: Tags | Sequence[str] = (), resolve_args_until: int | None = None, parent: BodyItemParent | None = None, error: str | None = None)[source]

Bases: LibraryKeyword

Represents a keyword in a dynamic library.

property method: Callable[[...], Any]

Dynamic run_keyword method.

property source: Path | None
property lineno: int | None
classmethod from_name(name: str, owner: DynamicLibrary) DynamicKeyword[source]
resolve_arguments(arguments, variables=None, languages=None) tuple[list, list][source]
copy(**attributes) DynamicKeyword[source]

Return a shallow copy of this object.

Parameters:

attributes – Attributes to be set to the returned copy. For example, obj.copy(name='New name').

See also deepcopy(). The difference between copy and deepcopy is the same as with the methods having same names in the copy module.

run_keyword
class robot.running.librarykeyword.LibraryInit(owner: TestLibrary, name: str = '', args: ArgumentSpec | None = None, doc: str = '', tags: Tags | Sequence[str] = (), positional: list | None = None, named: dict | None = None)[source]

Bases: LibraryKeyword

Represents a library initializer.

positional and named contain arguments used for initializing the library.

property doc: str
property method: Callable[[...], None] | None

Initializer method.

None with module based libraries and when class based libraries do not have __init__.

classmethod from_class(klass) LibraryInit[source]
classmethod null() LibraryInit[source]
copy(**attributes) LibraryInit[source]

Return a shallow copy of this object.

Parameters:

attributes – Attributes to be set to the returned copy. For example, obj.copy(name='New name').

See also deepcopy(). The difference between copy and deepcopy is the same as with the methods having same names in the copy module.

class robot.running.librarykeyword.KeywordCreator(name: str, library: TestLibrary | None = None)[source]

Bases: Generic[K]

keyword_class: type[K]
property instance: Any
create(**extra) K[source]
get_name() str[source]
get_args() ArgumentSpec[source]
get_doc() str[source]
get_tags() list[str][source]
class robot.running.librarykeyword.StaticKeywordCreator(name: str, library: TestLibrary)[source]

Bases: KeywordCreator[StaticKeyword]

keyword_class

alias of StaticKeyword

get_name() str[source]
get_args() ArgumentSpec[source]
get_doc() str[source]
get_tags() list[str][source]
class robot.running.librarykeyword.DynamicKeywordCreator(name: str, library: TestLibrary | None = None)[source]

Bases: KeywordCreator[DynamicKeyword]

keyword_class

alias of DynamicKeyword

library: DynamicLibrary
get_name() str[source]
get_args() ArgumentSpec[source]
get_doc() str[source]
get_tags() list[str][source]
class robot.running.librarykeyword.LibraryInitCreator(method: Callable[[...], None] | None)[source]

Bases: KeywordCreator[LibraryInit]

keyword_class

alias of LibraryInit

create(**extra) LibraryInit[source]
get_name() str[source]
get_args() ArgumentSpec[source]
get_doc() str[source]
get_tags() list[str][source]

robot.running.librarykeywordrunner module

class robot.running.librarykeywordrunner.LibraryKeywordRunner(keyword: LibraryKeyword, name: str | None = None, languages=None)[source]

Bases: object

run(data: Keyword, result: Keyword, context, run=True)[source]
dry_run(data: Keyword, result: Keyword, context)[source]
class robot.running.librarykeywordrunner.EmbeddedArgumentsRunner(keyword: LibraryKeyword, name: str)[source]

Bases: LibraryKeywordRunner

class robot.running.librarykeywordrunner.RunKeywordRunner(keyword: LibraryKeyword, execute_in_dry_run=False)[source]

Bases: LibraryKeywordRunner

robot.running.libraryscopes module

class robot.running.libraryscopes.Scope(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

GLOBAL = 1
SUITE = 2
TEST = 3
class robot.running.libraryscopes.ScopeManager(library: TestLibrary)[source]

Bases: object

classmethod for_library(library)[source]
start_suite()[source]
end_suite()[source]
start_test()[source]
end_test()[source]
close_global_listeners()[source]
register_listeners()[source]
unregister_listeners(close=False)[source]
class robot.running.libraryscopes.GlobalScopeManager(library: TestLibrary)[source]

Bases: ScopeManager

start_suite()[source]
end_suite()[source]
close_global_listeners()[source]
class robot.running.libraryscopes.SuiteScopeManager(library)[source]

Bases: ScopeManager

start_suite()[source]
end_suite()[source]
class robot.running.libraryscopes.TestScopeManager(library)[source]

Bases: SuiteScopeManager

start_test()[source]
end_test()[source]

robot.running.model module

Module implementing test execution related model objects.

When tests are executed by Robot Framework, a TestSuite structure using classes defined in this module is created by TestSuiteBuilder based on data on a file system. In addition to that, external tools can create executable suite structures programmatically.

Regardless the approach to construct it, a TestSuite object is executed by calling its run() method as shown in the example in the robot.running package level documentation. When a suite is run, test, keywords, and other objects it contains can be inspected and modified by using pre-run modifiers and listeners.

The TestSuite class is exposed via the robot.api package. If other classes are needed, they can be imported from robot.running.

class robot.running.model.Body(parent: TestSuite | TestCase | UserKeyword | For | ForIteration | If | IfBranch | Try | TryBranch | While | WhileIteration | Keyword | Var | Return | Continue | Break | Error | None = None, items: Iterable[BodyItem | DataDict] = ())[source]

Bases: BaseBody[Keyword, For, While, If, Try, Var, Return, Continue, Break, model.Message, Error]

break_class

alias of Break

continue_class

alias of Continue

error_class

alias of Error

for_class

alias of For

if_class

alias of If

keyword_class

alias of Keyword

return_class

alias of Return

try_class

alias of Try

var_class

alias of Var

while_class

alias of While

class robot.running.model.Branches(branch_class: Type[IT], parent: TestSuite | TestCase | UserKeyword | For | ForIteration | If | IfBranch | Try | TryBranch | While | WhileIteration | Keyword | Var | Return | Continue | Break | Error | None = None, items: Iterable[IT | DataDict] = ())[source]

Bases: BaseBranches[Keyword, For, While, If, Try, Var, Return, Continue, Break, model.Message, Error, IT]

class robot.running.model.WithSource[source]

Bases: object

parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None
property source: Path | None
class robot.running.model.Keyword(name: str = '', args: Sequence[Any | Tuple[Any] | Tuple[str, Any]] | Tuple[List[Any], Dict[str, Any]] = (), assign: Sequence[str] = (), type: str = 'KEYWORD', parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None)[source]

Bases: Keyword, WithSource

Represents an executable keyword call.

A keyword call consists only of a keyword name, arguments and possible assignment in the data:

Keyword    arg
${result} =    Another Keyword    arg1    arg2

The actual keyword that is executed depends on the context where this model is executed.

Arguments originating from normal Robot Framework data are stored as list of strings in the exact same format as in the data. This means that arguments can have variables and escape characters, and that named arguments are specified using the name=value syntax.

If arguments are set programmatically, it is possible to use also other types than strings. To support non-string values with named arguments, it is possible to use two-item tuples like ('name', 'value'). To avoid ambiguity if an argument contains a literal = character, positional arguments can also be given using one-item tuples like ('value',). In all these cases strings can contain variables, and they must follow the escaping rules used in normal data.

Arguments can also be given directly as a tuple containing list of positional arguments and a dictionary of named arguments. In this case arguments are used as-is without replacing variables or handling escapes. Argument conversion and validation is done even in this case, though.

Support for specifying arguments using tuples and giving them directly as positional and named arguments are new in Robot Framework 7.0.

lineno
classmethod from_json(source) Keyword[source]

Create this object based on JSON data.

The data is given as the source parameter. It can be:

  • a string (or bytes) containing the data directly,

  • an open file object where to read the data from, or

  • a path (pathlib.Path or string) to a UTF-8 encoded file to read.

The JSON data is first converted to a Python dictionary and the object created using the from_dict() method.

Notice that the source is considered to be JSON data if it is a string and contains {. If you need to use { in a file system path, pass it in as a pathlib.Path instance.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

run(result, context, run=True, templated=None)[source]
class robot.running.model.ForIteration(assign: Mapping[str, str] | None = None, parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: ForIteration, WithSource

body_class

alias of Body

lineno
error
class robot.running.model.For(assign: Sequence[str] = (), flavor: Literal['IN', 'IN RANGE', 'IN ENUMERATE', 'IN ZIP'] = 'IN', values: Sequence[str] = (), start: str | None = None, mode: str | None = None, fill: str | None = None, parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: For, WithSource

body_class

alias of Body

lineno
error
classmethod from_dict(data: Dict[str, Any]) For[source]

Create this object based on data in a dictionary.

Data can be got from the to_dict() method or created externally.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

run(result, context, run=True, templated=False)[source]
get_iteration(assign: Mapping[str, str] | None = None) ForIteration[source]
class robot.running.model.WhileIteration(parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: WhileIteration, WithSource

body_class

alias of Body

lineno
error
class robot.running.model.While(condition: str | None = None, limit: str | None = None, on_limit: str | None = None, on_limit_message: str | None = None, parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: While, WithSource

body_class

alias of Body

lineno
error
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

run(result, context, run=True, templated=False)[source]
get_iteration() WhileIteration[source]
class robot.running.model.IfBranch(type: str = 'IF', condition: str | None = None, parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None)[source]

Bases: IfBranch, WithSource

body_class

alias of Body

lineno
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.model.If(parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: If, WithSource

branch_class

alias of IfBranch

branches_class

alias of Branches[IfBranch]

lineno
error
run(result, context, run=True, templated=False)[source]
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.model.TryBranch(type: str = 'TRY', patterns: Sequence[str] = (), pattern_type: str | None = None, assign: str | None = None, parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None)[source]

Bases: TryBranch, WithSource

body_class

alias of Body

lineno
classmethod from_dict(data: Dict[str, Any]) TryBranch[source]

Create this object based on data in a dictionary.

Data can be got from the to_dict() method or created externally.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.model.Try(parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: Try, WithSource

branch_class

alias of TryBranch

branches_class

alias of Branches[TryBranch]

lineno
error
run(result, context, run=True, templated=False)[source]
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.model.Var(name: str = '', value: str | Sequence[str] = (), scope: str | None = None, separator: str | None = None, parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: Var, WithSource

lineno
error
run(result, context, run=True, templated=False)[source]
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.model.Return(values: Sequence[str] = (), parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: Return, WithSource

lineno
error
run(result, context, run=True, templated=False)[source]
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.model.Continue(parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: Continue, WithSource

lineno
error
run(result, context, run=True, templated=False)[source]
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.model.Break(parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: Break, WithSource

lineno
error
run(result, context, run=True, templated=False)[source]
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.model.Error(values: Sequence[str] = (), parent: TestSuite | TestCase | UserKeyword | For | If | IfBranch | Try | TryBranch | While | None = None, lineno: int | None = None, error: str = '')[source]

Bases: Error, WithSource

lineno
error
run(result, context, run=True, templated=False)[source]
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.model.TestCase(name: str = '', doc: str = '', tags: Sequence[str] = (), timeout: str | None = None, lineno: int | None = None, parent: TestSuite | None = None, template: str | None = None, error: str | None = None)[source]

Bases: TestCase[Keyword]

Represents a single executable test case.

See the base class for documentation of attributes not documented here.

body_class

Internal usage only.

alias of Body

fixture_class

Internal usage only.

alias of Keyword

template
error
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

body

Test body as a Body object.

class robot.running.model.TestSuite(name: str = '', doc: str = '', metadata: Mapping[str, str] | None = None, source: Path | str | None = None, rpa: bool | None = False, parent: TestSuite | None = None)[source]

Bases: TestSuite[Keyword, TestCase]

Represents a single executable test suite.

See the base class for documentation of attributes not documented here.

test_class

Internal usage only.

alias of TestCase

fixture_class

Internal usage only.

alias of Keyword

resource

ResourceFile instance containing imports, variables and keywords the suite owns. When data is parsed from the file system, this data comes from the same test case file that creates the suite.

classmethod from_file_system(*paths: Path | str, **config) TestSuite[source]

Create a TestSuite object based on the given paths.

Parameters:
  • paths – File or directory paths where to read the data from.

  • config – Configuration parameters for TestSuiteBuilder class that is used internally for building the suite.

See also from_model() and from_string().

classmethod from_model(model: File, name: str | None = None, *, defaults: TestDefaults | None = None) TestSuite[source]

Create a TestSuite object based on the given model.

Parameters:
  • model – Model to create the suite from.

  • name – Deprecated since Robot Framework 6.1.

  • defaults – Possible test specific defaults from suite initialization files. New in Robot Framework 6.1.

The model can be created by using the get_model() function and possibly modified by other tooling in the robot.parsing module.

Giving suite name is deprecated and users should set it and possible other attributes to the returned suite separately. One easy way is using the config() method like this:

suite = TestSuite.from_model(model).config(name='X', doc='Example')

See also from_file_system() and from_string().

classmethod from_string(string: str, *, defaults: TestDefaults | None = None, **config) TestSuite[source]

Create a TestSuite object based on the given string.

Parameters:
  • string – String to create the suite from.

  • defaults – Possible test specific defaults from suite initialization files.

  • config – Configuration parameters for get_model() used internally.

If suite name or other attributes need to be set, an easy way is using the config() method like this:

suite = TestSuite.from_string(string).config(name='X', doc='Example')

New in Robot Framework 6.1. See also from_model() and from_file_system().

configure(randomize_suites: bool = False, randomize_tests: bool = False, randomize_seed: int | None = None, **options)[source]

A shortcut to configure a suite using one method call.

Can only be used with the root test suite.

Parameters:
  • randomize_xxx – Passed to randomize().

  • options – Passed to SuiteConfigurer that will then set suite attributes, call filter(), etc. as needed.

Example:

suite.configure(include_tags=['smoke'],
                doc='Smoke test results.')

Not to be confused with config() method that suites, tests, and keywords have to make it possible to set multiple attributes in one call.

randomize(suites: bool = True, tests: bool = True, seed: int | None = None)[source]

Randomizes the order of suites and/or tests, recursively.

Parameters:
  • suites – Boolean controlling should suites be randomized.

  • tests – Boolean controlling should tests be randomized.

  • seed – Random seed. Can be given if previous random order needs to be re-created. Seed value is always shown in logs and reports.

suites
run(settings=None, **options)[source]

Executes the suite based on the given settings or options.

Parameters:
  • settingsRobotSettings object to configure test execution.

  • options – Used to construct new RobotSettings object if settings are not given.

Returns:

Result object with information about executed suites and tests.

If options are used, their names are the same as long command line options except without hyphens. Some options are ignored (see below), but otherwise they have the same semantics as on the command line. Options that can be given on the command line multiple times can be passed as lists like variable=['VAR1:value1', 'VAR2:value2']. If such an option is used only once, it can be given also as a single string like variable='VAR:value'.

Additionally, listener option allows passing object directly instead of listener name, e.g. run('tests.robot', listener=Listener()).

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

Only options related to the actual test execution have an effect. For example, options related to selecting or modifying test cases or suites (e.g. --include, --name, --prerunmodifier) or creating logs and reports are silently ignored. The output XML generated as part of the execution can be configured, though. This includes disabling it with output=None.

Example:

stdout = StringIO()
result = suite.run(variable='EXAMPLE:value',
                   output='example.xml',
                   exitonfailure=True,
                   stdout=stdout)
print(result.return_code)

To save memory, the returned Result object does not have any information about the executed keywords. If that information is needed, the created output XML file needs to be read using the ExecutionResult factory method.

See the package level documentation for more examples, including how to construct executable test suites and how to create logs and reports based on the execution results.

See the robot.run function for a higher-level API for executing tests in files or directories.

to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

robot.running.namespace module

class robot.running.namespace.Namespace(variables, suite, resource, languages)[source]

Bases: object

property libraries
handle_imports()[source]
import_resource(name, overwrite=True)[source]
import_variables(name, args, overwrite=False)[source]
import_library(name, args=(), alias=None, notify=True)[source]
set_search_order(new_order)[source]
start_test()[source]
end_test()[source]
start_suite()[source]
end_suite(suite)[source]
start_user_keyword()[source]
end_user_keyword()[source]
get_library_instance(name)[source]
get_library_instances()[source]
reload_library(name_or_instance)[source]
get_runner(name, recommend_on_failure=True)[source]
class robot.running.namespace.KeywordStore(suite_file, languages)[source]

Bases: object

get_library(name_or_instance)[source]
get_runner(name, recommend=True)[source]
class robot.running.namespace.KeywordRecommendationFinder(*owners)[source]

Bases: object

recommend_similar_keywords(name, message)[source]

Return keyword names similar to name.

static format_recommendations(message, recommendations)[source]

robot.running.outputcapture module

class robot.running.outputcapture.OutputCapturer(library_import=False)[source]

Bases: object

start()[source]
stop()[source]
class robot.running.outputcapture.StreamCapturer(stdout=True)[source]

Bases: object

release()[source]

robot.running.randomizer module

class robot.running.randomizer.Randomizer(randomize_suites=True, randomize_tests=True, seed=None)[source]

Bases: SuiteVisitor

start_suite(suite)[source]

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_test(test)[source]

Implements traversing through tests.

Can be overridden to allow modifying the passed in test without calling start_test() or end_test() nor visiting the body of the test.

visit_keyword(kw)[source]

Implements traversing through keywords.

Can be overridden to allow modifying the passed in kw without calling start_keyword() or end_keyword() nor visiting the body of the keyword

robot.running.resourcemodel module

class robot.running.resourcemodel.ResourceFile(source: Path | str | None = None, owner: TestSuite | None = None, doc: str = '')[source]

Bases: ModelObject

repr_args = ('source',)
owner
doc
keyword_finder
property source: Path | None
property name: str | None

Resource file name.

None if resource file is part of a suite or if it does not have source, name of the source file without the extension otherwise.

imports
variables
keywords
classmethod from_file_system(path: Path | str, **config) ResourceFile[source]

Create a ResourceFile object based on the give path.

Parameters:
  • path – File path where to read the data from.

  • config – Configuration parameters for ResourceFileBuilder class that is used internally for building the suite.

New in Robot Framework 6.1. See also from_string() and from_model().

classmethod from_string(string: str, **config) ResourceFile[source]

Create a ResourceFile object based on the given string.

Parameters:
  • string – String to create the resource file from.

  • config – Configuration parameters for get_resource_model() used internally.

New in Robot Framework 6.1. See also from_file_system() and from_model().

classmethod from_model(model: File) ResourceFile[source]

Create a ResourceFile object based on the given model.

Parameters:

model – Model to create the suite from.

The model can be created by using the get_resource_model() function and possibly modified by other tooling in the robot.parsing module.

New in Robot Framework 6.1. See also from_file_system() and from_string().

find_keywords(name: str, count: Literal[1]) UserKeyword[source]
find_keywords(name: str, count: int | None = None) list[UserKeyword]
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.resourcemodel.UserKeyword(name: str = '', args: ArgumentSpec | Sequence[str] | None = (), doc: str = '', tags: Tags | Sequence[str] = (), timeout: str | None = None, lineno: int | None = None, owner: ResourceFile | None = None, parent: BodyItemParent | None = None, error: str | None = None)[source]

Bases: KeywordImplementation

Represents a user keyword.

type: Literal['USER KEYWORD', 'LIBRARY KEYWORD', 'INVALID KEYWORD'] = 'USER KEYWORD'
fixture_class

alias of Keyword

timeout
args
body
property setup: Keyword

User keyword setup as a Keyword object.

New in Robot Framework 7.0.

property has_setup: bool

Check does a keyword have a setup without creating a setup object.

See has_teardown for more information. New in Robot Framework 7.0.

property teardown: Keyword

User keyword teardown as a Keyword object.

property has_teardown: bool

Check does a keyword have a teardown without creating a teardown object.

A difference between using if kw.has_teardown: and if kw.teardown: is that accessing the teardown attribute creates a Keyword object representing the teardown even when the user keyword actually does not have one. This can have an effect on memory usage.

New in Robot Framework 6.1.

create_runner(name: str | None, languages=None) UserKeywordRunner | EmbeddedArgumentsRunner[source]
bind(data: Keyword) UserKeyword[source]
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.resourcemodel.Variable(name: str = '', value: Sequence[str] = (), separator: str | None = None, owner: ResourceFile | None = None, lineno: int | None = None, error: str | None = None)[source]

Bases: ModelObject

repr_args = ('name', 'value', 'separator')
property source: Path | None
report_error(message: str, level: str = 'ERROR')[source]
to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.resourcemodel.Import(type: Literal['LIBRARY', 'RESOURCE', 'VARIABLES'], name: str, args: Sequence[str] = (), alias: str | None = None, owner: ResourceFile | None = None, lineno: int | None = None)[source]

Bases: ModelObject

repr_args = ('type', 'name', 'args', 'alias')
LIBRARY = 'LIBRARY'
RESOURCE = 'RESOURCE'
VARIABLES = 'VARIABLES'
property source: Path | None
property directory: Path | None
property setting_name: str
select(library: Any, resource: Any, variables: Any) Any[source]
report_error(message: str, level: str = 'ERROR')[source]
classmethod from_dict(data) Import[source]

Create this object based on data in a dictionary.

Data can be got from the to_dict() method or created externally.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

to_dict() Dict[str, Any][source]

Serialize this object into a dictionary.

The object can be later restored by using the from_dict() method.

With robot.running model objects new in Robot Framework 6.1, with robot.result new in Robot Framework 7.0.

class robot.running.resourcemodel.Imports(owner: ResourceFile, imports: Sequence[Import] = ())[source]

Bases: ItemList

library(name: str, args: Sequence[str] = (), alias: str | None = None, lineno: int | None = None) Import[source]

Create library import.

resource(name: str, lineno: int | None = None) Import[source]

Create resource import.

variables(name: str, args: Sequence[str] = (), lineno: int | None = None) Import[source]

Create variables import.

create(*args, **kwargs) Import[source]

Generic method for creating imports.

Import type specific methods library(), resource() and variables() are recommended over this method.

class robot.running.resourcemodel.Variables(owner: ResourceFile, variables: Sequence[Variable] = ())[source]

Bases: ItemList[Variable]

class robot.running.resourcemodel.UserKeywords(owner: ResourceFile, keywords: Sequence[UserKeyword] = ())[source]

Bases: ItemList[UserKeyword]

append(item: UserKeyword | Dict[str, Any]) UserKeyword[source]

S.append(value) – append value to the end of the sequence

extend(items: Iterable[UserKeyword | Dict[str, Any]])[source]

S.extend(iterable) – extend sequence by appending elements from the iterable

insert(index: int, item: UserKeyword | Dict[str, Any])[source]

S.insert(index, value) – insert value before index

clear() None -- remove all items from S[source]

robot.running.runkwregister module

robot.running.signalhandler module

robot.running.status module

class robot.running.status.Failure[source]

Bases: object

class robot.running.status.Exit(failure_mode=False, error_mode=False, skip_teardown_mode=False)[source]

Bases: object

failure_occurred(fatal=False)[source]
error_occurred()[source]
property teardown_allowed
class robot.running.status.SuiteStatus(parent=None, exit_on_failure=False, exit_on_error=False, skip_teardown_on_exit=False)[source]

Bases: _ExecutionStatus

class robot.running.status.TestStatus(parent, test, skip_on_failure=None, rpa=False)[source]

Bases: _ExecutionStatus

test_failed(message=None, error=None)[source]
test_skipped(message)[source]
property skip_on_failure_after_tag_changes
class robot.running.status.TestMessage(status)[source]

Bases: _Message

setup_message = 'Setup failed:\n%s'
teardown_message = 'Teardown failed:\n%s'
setup_skipped_message = '%s'
teardown_skipped_message = '%s'
also_teardown_message = '%s\n\nAlso teardown failed:\n%s'
also_teardown_skip_message = 'Skipped in teardown:\n%s\n\nEarlier message:\n%s'
exit_on_fatal_message = 'Test execution stopped due to a fatal error.'
exit_on_failure_message = 'Failure occurred and exit-on-failure mode is in use.'
exit_on_error_message = 'Error occurred and exit-on-error mode is in use.'
property message
class robot.running.status.SuiteMessage(status)[source]

Bases: _Message

setup_message = 'Suite setup failed:\n%s'
setup_skipped_message = 'Skipped in suite setup:\n%s'
teardown_skipped_message = 'Skipped in suite teardown:\n%s'
teardown_message = 'Suite teardown failed:\n%s'
also_teardown_message = '%s\n\nAlso suite teardown failed:\n%s'
also_teardown_skip_message = 'Skipped in suite teardown:\n%s\n\nEarlier message:\n%s'
class robot.running.status.ParentMessage(status)[source]

Bases: SuiteMessage

setup_message = 'Parent suite setup failed:\n%s'
setup_skipped_message = 'Skipped in parent suite setup:\n%s'
teardown_skipped_message = 'Skipped in parent suite teardown:\n%s'
teardown_message = 'Parent suite teardown failed:\n%s'
also_teardown_message = '%s\n\nAlso parent suite teardown failed:\n%s'

robot.running.statusreporter module

class robot.running.statusreporter.StatusReporter(data, result, context, run=True, suppress=False, implementation=None)[source]

Bases: object

robot.running.suiterunner module

class robot.running.suiterunner.SuiteRunner(output, settings)[source]

Bases: SuiteVisitor

property context
start_suite(data: TestSuite)[source]

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_suite(suite: TestSuite)[source]

Called when a suite ends. Default implementation does nothing.

visit_test(data: TestCase)[source]

Implements traversing through tests.

Can be overridden to allow modifying the passed in test without calling start_test() or end_test() nor visiting the body of the test.

robot.running.testlibraries module

class robot.running.testlibraries.TestLibrary(code: type | module, init: ~robot.running.librarykeyword.LibraryInit, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, logger=<robot.output.logger.Logger object>)[source]

Bases: object

Represents imported test library.

property instance: Any

Current library instance.

With module based libraries this is the module itself.

With class based libraries this is an instance of the class. Instances are cleared automatically during execution based on their scope. Accessing this property creates a new instance if needed.

code´ contains the original library code. With module based libraries it is the same as :attr:`instance. With class based libraries it is the library class.

property listeners: list[Any]
property converters: CustomArgumentConverters | None
property doc: str
property doc_format: str
property scope: Scope
source
property version: str
property lineno: int
classmethod from_name(name: str, real_name: str | None = None, args: ~typing.Sequence[str] | None = None, variables=None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) TestLibrary[source]
classmethod from_code(code: type | module, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, args: ~typing.Sequence[str] | None = None, variables=None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) TestLibrary[source]
classmethod from_module(module: module, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) TestLibrary[source]
classmethod from_class(klass: type, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, args: ~typing.Sequence[str] = (), variables=None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) TestLibrary[source]
create_keywords()[source]
find_keywords(name: str, count: Literal[1]) LibraryKeyword[source]
find_keywords(name: str, count: int | None = None) list[LibraryKeyword]
copy(name: str) Self[source]
report_error(message: str, details: str | None = None, level: str = 'ERROR', details_level: str = 'INFO')[source]
class robot.running.testlibraries.ModuleLibrary(code: type | module, init: ~robot.running.librarykeyword.LibraryInit, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, logger=<robot.output.logger.Logger object>)[source]

Bases: TestLibrary

property scope: Scope
classmethod from_module(module: module, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) ModuleLibrary[source]
classmethod from_class(*args, **kws) TestLibrary[source]
create_keywords()[source]
class robot.running.testlibraries.ClassLibrary(code: type | module, init: ~robot.running.librarykeyword.LibraryInit, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, logger=<robot.output.logger.Logger object>)[source]

Bases: TestLibrary

property instance: Any

Current library instance.

With module based libraries this is the module itself.

With class based libraries this is an instance of the class. Instances are cleared automatically during execution based on their scope. Accessing this property creates a new instance if needed.

code´ contains the original library code. With module based libraries it is the same as :attr:`instance. With class based libraries it is the library class.

property lineno: int
classmethod from_module(*args, **kws) TestLibrary[source]
classmethod from_class(klass: type, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, args: ~typing.Sequence[str] = (), variables=None, create_keywords: bool = True, logger=<robot.output.logger.Logger object>) ClassLibrary[source]
create_keywords()[source]
class robot.running.testlibraries.HybridLibrary(code: type | module, init: ~robot.running.librarykeyword.LibraryInit, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, logger=<robot.output.logger.Logger object>)[source]

Bases: ClassLibrary

create_keywords()[source]
class robot.running.testlibraries.DynamicLibrary(code: type | module, init: ~robot.running.librarykeyword.LibraryInit, name: str | None = None, real_name: str | None = None, source: ~pathlib.Path | None = None, logger=<robot.output.logger.Logger object>)[source]

Bases: ClassLibrary

property supports_named_args: bool
property doc: str
create_keywords()[source]
class robot.running.testlibraries.KeywordCreator(library: TestLibrary, getting_method_failed_level='INFO')[source]

Bases: object

get_keyword_names() list[str][source]
create_keywords(names: list[str] | None = None)[source]
class robot.running.testlibraries.StaticKeywordCreator(library: TestLibrary, getting_method_failed_level='INFO', excluded_names=None, avoid_properties=False)[source]

Bases: KeywordCreator

get_keyword_names() list[str][source]
class robot.running.testlibraries.DynamicKeywordCreator(library: DynamicLibrary | HybridLibrary)[source]

Bases: KeywordCreator

library: DynamicLibrary
get_keyword_names() list[str][source]

robot.running.userkeywordrunner module

class robot.running.userkeywordrunner.UserKeywordRunner(keyword: UserKeyword, name: str | None = None)[source]

Bases: object

run(data: Keyword, result: Keyword, context, run=True)[source]
dry_run(data: Keyword, result: Keyword, context)[source]
class robot.running.userkeywordrunner.EmbeddedArgumentsRunner(keyword: UserKeyword, name: str)[source]

Bases: UserKeywordRunner