robot.model package

Package with generic, reusable and extensible model classes.

This package contains, for example, TestSuite, TestCase, Keyword and SuiteVisitor base classes. These classes are extended both by execution and result related model objects and used also elsewhere.

This package is considered stable.

Submodules

robot.model.body module

class robot.model.body.BodyItem[source]

Bases: robot.model.modelobject.ModelObject

KEYWORD = 'KEYWORD'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
FOR = 'FOR'
ITERATION = 'ITERATION'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
IF = 'IF'
ELSE_IF = 'ELSE IF'
ELSE = 'ELSE'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
TRY = 'TRY'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
WHILE = 'WHILE'
RETURN = 'RETURN'
CONTINUE = 'CONTINUE'
BREAK = 'BREAK'
ERROR = 'ERROR'
MESSAGE = 'MESSAGE'
type = None
id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

id is None only in these special cases:

  • Keyword uses a placeholder for setup or teardown when a setup or teardown is not actually used.
  • With If and Try instances representing IF/TRY structure roots.
to_dict() → Dict[str, Any][source]

Serialize this object into a dictionary.

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

config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

parent
repr_args = ()
to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

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

Bases: robot.model.itemlist.ItemList, typing.Generic

Base class for Body and Branches objects.

keyword_class

alias of builtins.type

for_class

alias of builtins.type

while_class

alias of builtins.type

if_class

alias of builtins.type

try_class

alias of builtins.type

return_class

alias of builtins.type

continue_class

alias of builtins.type

break_class

alias of builtins.type

message_class

alias of builtins.type

error_class

alias of builtins.type

classmethod register(item_class: Type[BI]) → Type[BI][source]

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

create

Create a new item using the provided arguments.

create_keyword(*args, **kwargs) → type[source]
create_for(*args, **kwargs) → type[source]
create_if(*args, **kwargs) → type[source]
create_try(*args, **kwargs) → type[source]
create_while(*args, **kwargs) → type[source]
create_return(*args, **kwargs) → type[source]
create_continue(*args, **kwargs) → type[source]
create_break(*args, **kwargs) → type[source]
create_message(*args, **kwargs) → type[source]
create_error(*args, **kwargs) → type[source]
filter(keywords: bool | None[bool, None] = None, messages: bool | None[bool, None] = None, predicate: Optional[Callable[[T], bool], None] = None)[source]

Filter body items based on type and/or custom predicate.

To include or exclude items based on types, give matching arguments True or False values. For example, to include only keywords, use body.filter(keywords=True) and to exclude messages use body.filter(messages=False). Including and excluding by types at the same time is not supported and filtering my messages is supported only if the Body object actually supports messages.

Custom predicate is a callable getting each body item as an argument that must return True/False depending on should the item be included or not.

Selected items are returned as a list and the original body is not modified.

It was earlier possible to filter also based on FOR and IF types. That support was removed in RF 5.0 because it was not considered useful in general and because adding support for all new control structures would have required extra work. To exclude all control structures, use body.filter(keywords=True, messages=True) and to only include them use body.filter(keywords=False, messages=False)``. For more detailed filtering it is possible to use predicate.

flatten() → list[source]

Return steps so that IF and TRY structures are flattened.

Basically the IF/ELSE and TRY/EXCEPT root elements are replaced with their branches. This is how they are shown in log files.

append(item: Union[T, Dict[str, Any]]) → T

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

clear() → None -- remove all items from S
count(value) → integer -- return number of occurrences of value
extend(items: Iterable[Union[T, Dict[str, Any]]])

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

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index: int, item: Union[T, Dict[str, Any]])

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

item_type

alias of builtins.type

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(**config)
to_dicts() → list

Return list of items converted to dictionaries.

Items are converted to dictionaries using the to_dict method, if they have it, or the built-in vars().

New in Robot Framework 6.1.

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

Bases: robot.model.body.BaseBody

A list-like object representing a body of a test, keyword, etc.

Body contains the keywords and other structures such as FOR loops.

append(item: Union[T, Dict[str, Any]]) → T

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

break_class

alias of robot.model.control.Break

clear() → None -- remove all items from S
continue_class

alias of robot.model.control.Continue

count(value) → integer -- return number of occurrences of value
create

Create a new item using the provided arguments.

create_break(*args, **kwargs) → type
create_continue(*args, **kwargs) → type
create_error(*args, **kwargs) → type
create_for(*args, **kwargs) → type
create_if(*args, **kwargs) → type
create_keyword(*args, **kwargs) → type
create_message(*args, **kwargs) → type
create_return(*args, **kwargs) → type
create_try(*args, **kwargs) → type
create_while(*args, **kwargs) → type
error_class

alias of robot.model.control.Error

extend(items: Iterable[Union[T, Dict[str, Any]]])

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

filter(keywords: bool | None[bool, None] = None, messages: bool | None[bool, None] = None, predicate: Optional[Callable[[T], bool], None] = None)

Filter body items based on type and/or custom predicate.

To include or exclude items based on types, give matching arguments True or False values. For example, to include only keywords, use body.filter(keywords=True) and to exclude messages use body.filter(messages=False). Including and excluding by types at the same time is not supported and filtering my messages is supported only if the Body object actually supports messages.

Custom predicate is a callable getting each body item as an argument that must return True/False depending on should the item be included or not.

Selected items are returned as a list and the original body is not modified.

It was earlier possible to filter also based on FOR and IF types. That support was removed in RF 5.0 because it was not considered useful in general and because adding support for all new control structures would have required extra work. To exclude all control structures, use body.filter(keywords=True, messages=True) and to only include them use body.filter(keywords=False, messages=False)``. For more detailed filtering it is possible to use predicate.

flatten() → list

Return steps so that IF and TRY structures are flattened.

Basically the IF/ELSE and TRY/EXCEPT root elements are replaced with their branches. This is how they are shown in log files.

for_class

alias of robot.model.control.For

if_class

alias of robot.model.control.If

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index: int, item: Union[T, Dict[str, Any]])

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

item_type

alias of builtins.type

keyword_class

alias of robot.model.keyword.Keyword

message_class

alias of builtins.type

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

classmethod register(item_class: Type[BI]) → Type[BI]

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

return_class

alias of robot.model.control.Return

reverse()

S.reverse() – reverse IN PLACE

sort(**config)
to_dicts() → list

Return list of items converted to dictionaries.

Items are converted to dictionaries using the to_dict method, if they have it, or the built-in vars().

New in Robot Framework 6.1.

try_class

alias of robot.model.control.Try

visit(visitor: SuiteVisitor)
while_class

alias of robot.model.control.While

class robot.model.body.BranchType[source]

Bases: typing.Generic

Class that wrapps Generic as python doesn’t allow multple generic inheritance

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

Bases: robot.model.body.BaseBody, robot.model.body.BranchType

A list-like object representing IF and TRY branches.

branch_type

alias of builtins.type

branch_class
create_branch(*args, **kwargs) → IT[source]
append(item: Union[T, Dict[str, Any]]) → T

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

break_class

alias of builtins.type

clear() → None -- remove all items from S
continue_class

alias of builtins.type

count(value) → integer -- return number of occurrences of value
create

Create a new item using the provided arguments.

create_break(*args, **kwargs) → type
create_continue(*args, **kwargs) → type
create_error(*args, **kwargs) → type
create_for(*args, **kwargs) → type
create_if(*args, **kwargs) → type
create_keyword(*args, **kwargs) → type
create_message(*args, **kwargs) → type
create_return(*args, **kwargs) → type
create_try(*args, **kwargs) → type
create_while(*args, **kwargs) → type
error_class

alias of builtins.type

extend(items: Iterable[Union[T, Dict[str, Any]]])

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

filter(keywords: bool | None[bool, None] = None, messages: bool | None[bool, None] = None, predicate: Optional[Callable[[T], bool], None] = None)

Filter body items based on type and/or custom predicate.

To include or exclude items based on types, give matching arguments True or False values. For example, to include only keywords, use body.filter(keywords=True) and to exclude messages use body.filter(messages=False). Including and excluding by types at the same time is not supported and filtering my messages is supported only if the Body object actually supports messages.

Custom predicate is a callable getting each body item as an argument that must return True/False depending on should the item be included or not.

Selected items are returned as a list and the original body is not modified.

It was earlier possible to filter also based on FOR and IF types. That support was removed in RF 5.0 because it was not considered useful in general and because adding support for all new control structures would have required extra work. To exclude all control structures, use body.filter(keywords=True, messages=True) and to only include them use body.filter(keywords=False, messages=False)``. For more detailed filtering it is possible to use predicate.

flatten() → list

Return steps so that IF and TRY structures are flattened.

Basically the IF/ELSE and TRY/EXCEPT root elements are replaced with their branches. This is how they are shown in log files.

for_class

alias of builtins.type

if_class

alias of builtins.type

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index: int, item: Union[T, Dict[str, Any]])

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

item_type

alias of builtins.type

keyword_class

alias of builtins.type

message_class

alias of builtins.type

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

classmethod register(item_class: Type[BI]) → Type[BI]

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

return_class

alias of builtins.type

reverse()

S.reverse() – reverse IN PLACE

sort(**config)
to_dicts() → list

Return list of items converted to dictionaries.

Items are converted to dictionaries using the to_dict method, if they have it, or the built-in vars().

New in Robot Framework 6.1.

try_class

alias of builtins.type

visit(visitor: SuiteVisitor)
while_class

alias of builtins.type

robot.model.configurer module

class robot.model.configurer.SuiteConfigurer(name=None, doc=None, metadata=None, set_tags=None, include_tags=None, exclude_tags=None, include_suites=None, include_tests=None, empty_suite_ok=False)[source]

Bases: robot.model.visitor.SuiteVisitor

add_tags
remove_tags
visit_suite(suite)[source]

Implements traversing through suites.

Can be overridden to allow modifying the passed in suite without calling start_suite() or end_suite() nor visiting child suites, tests or setup and teardown at all.

end_body_item(item: BodyItem)

Called, by default, when keywords, messages or control structures end.

More specific end_keyword(), end_message(), :meth:`end_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Default implementation does nothing.

end_break(break_: Break)

Called when a BREAK element ends.

By default, calls end_body_item() which, by default, does nothing.

end_continue(continue_: Continue)

Called when a CONTINUE element ends.

By default, calls end_body_item() which, by default, does nothing.

end_error(error: Error)

Called when a ERROR element ends.

By default, calls end_body_item() which, by default, does nothing.

end_for(for_: For)

Called when a FOR loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_for_iteration(iteration: ForIteration)

Called when a FOR loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

end_if(if_: If)

Called when an IF/ELSE structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_if_branch(branch: IfBranch)

Called when an IF/ELSE branch ends.

By default, calls end_body_item() which, by default, does nothing.

end_keyword(keyword: Keyword)

Called when a keyword ends.

By default, calls end_body_item() which, by default, does nothing.

end_message(message: Message)

Called when a message ends.

By default, calls end_body_item() which, by default, does nothing.

end_return(return_: Return)

Called when a RETURN element ends.

By default, calls end_body_item() which, by default, does nothing.

end_suite(suite: TestSuite)

Called when a suite ends. Default implementation does nothing.

end_test(test: TestCase)

Called when a test ends. Default implementation does nothing.

end_try(try_: Try)

Called when a TRY/EXCEPT structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_try_branch(branch: TryBranch)

Called when TRY, EXCEPT, ELSE and FINALLY branches end.

By default, calls end_body_item() which, by default, does nothing.

end_while(while_: While)

Called when a WHILE loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_while_iteration(iteration: WhileIteration)

Called when a WHILE loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

start_body_item(item: BodyItem) → bool|None

Called, by default, when keywords, messages or control structures start.

More specific start_keyword(), start_message(), :meth:`start_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Can return explicit False to stop visiting. Default implementation does nothing.

start_break(break_: Break) → bool|None

Called when a BREAK element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_continue(continue_: Continue) → bool|None

Called when a CONTINUE element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_error(error: Error) → bool|None

Called when a ERROR element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for(for_: For) → bool|None

Called when a FOR loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration: ForIteration) → bool|None

Called when a FOR loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if(if_: If) → bool|None

Called when an IF/ELSE structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch: IfBranch) → bool|None

Called when an IF/ELSE branch starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword: Keyword) → bool|None

Called when a keyword starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_message(message: Message) → bool|None

Called when a message starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_return(return_: Return) → bool|None

Called when a RETURN element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_suite(suite: TestSuite) → bool|None

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test: TestCase) → bool|None

Called when a test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_try(try_: Try) → bool|None

Called when a TRY/EXCEPT structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_try_branch(branch: TryBranch) → bool|None

Called when TRY, EXCEPT, ELSE or FINALLY branches start.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while(while_: While) → bool|None

Called when a WHILE loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while_iteration(iteration: WhileIteration) → bool|None

Called when a WHILE loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

visit_break(break_: Break)

Visits BREAK elements.

visit_continue(continue_: Continue)

Visits CONTINUE elements.

visit_error(error: Error)

Visits body items resulting from invalid syntax.

Examples include syntax like END or ELSE in wrong place and invalid setting like [Invalid].

visit_for(for_: For)

Implements traversing through FOR loops.

Can be overridden to allow modifying the passed in for_ without calling start_for() or end_for() nor visiting body.

visit_for_iteration(iteration: ForIteration)

Implements traversing through single FOR loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_for_iteration() or end_for_iteration() nor visiting body.

visit_if(if_: If)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and they are visited separately using visit_if_branch().

Can be overridden to allow modifying the passed in if_ without calling start_if() or end_if() nor visiting branches.

visit_if_branch(branch: IfBranch)

Implements traversing through single IF/ELSE branch.

Can be overridden to allow modifying the passed in branch without calling start_if_branch() or end_if_branch() nor visiting body.

visit_keyword(keyword: Keyword)

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

visit_message(message: Message)

Implements visiting messages.

Can be overridden to allow modifying the passed in msg without calling start_message() or end_message().

visit_return(return_: Return)

Visits a RETURN elements.

visit_test(test: TestCase)

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_try(try_: Try)

Implements traversing through TRY/EXCEPT structures.

This method is used with the TRY/EXCEPT root element. Actual TRY, EXCEPT, ELSE and FINALLY branches are visited separately using visit_try_branch().

visit_try_branch(branch: TryBranch)

Visits individual TRY, EXCEPT, ELSE and FINALLY branches.

visit_while(while_: While)

Implements traversing through WHILE loops.

Can be overridden to allow modifying the passed in while_ without calling start_while() or end_while() nor visiting body.

visit_while_iteration(iteration: WhileIteration)

Implements traversing through single WHILE loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_while_iteration() or end_while_iteration() nor visiting body.

robot.model.control module

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

Bases: robot.model.body.BaseBranches

append(item: Union[T, Dict[str, Any]]) → T

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

branch_class
branch_type

alias of builtins.type

break_class

alias of builtins.type

clear() → None -- remove all items from S
continue_class

alias of builtins.type

count(value) → integer -- return number of occurrences of value
create

Create a new item using the provided arguments.

create_branch(*args, **kwargs) → IT
create_break(*args, **kwargs) → type
create_continue(*args, **kwargs) → type
create_error(*args, **kwargs) → type
create_for(*args, **kwargs) → type
create_if(*args, **kwargs) → type
create_keyword(*args, **kwargs) → type
create_message(*args, **kwargs) → type
create_return(*args, **kwargs) → type
create_try(*args, **kwargs) → type
create_while(*args, **kwargs) → type
error_class

alias of builtins.type

extend(items: Iterable[Union[T, Dict[str, Any]]])

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

filter(keywords: bool | None[bool, None] = None, messages: bool | None[bool, None] = None, predicate: Optional[Callable[[T], bool], None] = None)

Filter body items based on type and/or custom predicate.

To include or exclude items based on types, give matching arguments True or False values. For example, to include only keywords, use body.filter(keywords=True) and to exclude messages use body.filter(messages=False). Including and excluding by types at the same time is not supported and filtering my messages is supported only if the Body object actually supports messages.

Custom predicate is a callable getting each body item as an argument that must return True/False depending on should the item be included or not.

Selected items are returned as a list and the original body is not modified.

It was earlier possible to filter also based on FOR and IF types. That support was removed in RF 5.0 because it was not considered useful in general and because adding support for all new control structures would have required extra work. To exclude all control structures, use body.filter(keywords=True, messages=True) and to only include them use body.filter(keywords=False, messages=False)``. For more detailed filtering it is possible to use predicate.

flatten() → list

Return steps so that IF and TRY structures are flattened.

Basically the IF/ELSE and TRY/EXCEPT root elements are replaced with their branches. This is how they are shown in log files.

for_class

alias of builtins.type

if_class

alias of builtins.type

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index: int, item: Union[T, Dict[str, Any]])

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

item_type

alias of builtins.type

keyword_class

alias of builtins.type

message_class

alias of builtins.type

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

classmethod register(item_class: Type[BI]) → Type[BI]

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

return_class

alias of builtins.type

reverse()

S.reverse() – reverse IN PLACE

sort(**config)
to_dicts() → list

Return list of items converted to dictionaries.

Items are converted to dictionaries using the to_dict method, if they have it, or the built-in vars().

New in Robot Framework 6.1.

try_class

alias of builtins.type

visit(visitor: SuiteVisitor)
while_class

alias of builtins.type

class robot.model.control.For(variables: 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: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

Represents FOR loops.

flavor specifies the flavor, and it can be IN, IN RANGE, IN ENUMERATE or IN ZIP.

type = 'FOR'
body_class

alias of robot.model.body.Body

repr_args = ('variables', 'flavor', 'values', 'start', 'mode', 'fill')
variables
flavor
values
start
mode
fill
parent
body
keywords

Deprecated since Robot Framework 4.0. Use body instead.

visit(visitor: robot.model.visitor.SuiteVisitor)[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.

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

id is None only in these special cases:

  • Keyword uses a placeholder for setup or teardown when a setup or teardown is not actually used.
  • With If and Try instances representing IF/TRY structure roots.
to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.control.While(condition: str|None = None, limit: str|None = None, on_limit: str|None = None, on_limit_message: str|None = None, parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

Represents WHILE loops.

type = 'WHILE'
body_class

alias of robot.model.body.Body

repr_args = ('condition', 'limit', 'on_limit', 'on_limit_message')
condition
on_limit
limit
on_limit_message
parent
body
visit(visitor: robot.model.visitor.SuiteVisitor)[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.

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

id is None only in these special cases:

  • Keyword uses a placeholder for setup or teardown when a setup or teardown is not actually used.
  • With If and Try instances representing IF/TRY structure roots.
to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.control.IfBranch(type: str = 'IF', condition: str|None = None, parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

Represents individual IF, ELSE IF or ELSE branch.

body_class

alias of robot.model.body.Body

repr_args = ('type', 'condition')
type
condition
parent
body
id

Branch id omits IF/ELSE root from the parent id part.

visit(visitor: robot.model.visitor.SuiteVisitor)[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.

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.control.If(parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

IF/ELSE structure root. Branches are stored in body.

type = 'IF/ELSE ROOT'
branch_class

alias of IfBranch

branches_class = robot.model.control.Branches[robot.model.control.IfBranch]
parent
body
id

Root IF/ELSE id is always None.

visit(visitor: robot.model.visitor.SuiteVisitor)[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.

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

repr_args = ()
to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.control.TryBranch(type: str = 'TRY', patterns: Sequence[str] = (), pattern_type: str|None = None, variable: str|None = None, parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

Represents individual TRY, EXCEPT, ELSE or FINALLY branch.

body_class

alias of robot.model.body.Body

repr_args = ('type', 'patterns', 'pattern_type', 'variable')
type
patterns
pattern_type
variable
parent
body
id

Branch id omits TRY/EXCEPT root from the parent id part.

visit(visitor: robot.model.visitor.SuiteVisitor)[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.

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.control.Try(parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

TRY/EXCEPT structure root. Branches are stored in body.

type = 'TRY/EXCEPT ROOT'
branch_class

alias of TryBranch

branches_class = robot.model.control.Branches[robot.model.control.TryBranch]
parent
body
try_branch
except_branches
else_branch
finally_branch
id

Root TRY/EXCEPT id is always None.

visit(visitor: robot.model.visitor.SuiteVisitor)[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.

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

repr_args = ()
to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.control.Return(values: Sequence[str] = (), parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

Represents RETURN.

type = 'RETURN'
repr_args = ('values',)
values
parent
visit(visitor: robot.model.visitor.SuiteVisitor)[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.

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

id is None only in these special cases:

  • Keyword uses a placeholder for setup or teardown when a setup or teardown is not actually used.
  • With If and Try instances representing IF/TRY structure roots.
to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.control.Continue(parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

Represents CONTINUE.

type = 'CONTINUE'
parent
visit(visitor: robot.model.visitor.SuiteVisitor)[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.

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

id is None only in these special cases:

  • Keyword uses a placeholder for setup or teardown when a setup or teardown is not actually used.
  • With If and Try instances representing IF/TRY structure roots.
repr_args = ()
to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.control.Break(parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

Represents BREAK.

type = 'BREAK'
parent
visit(visitor: robot.model.visitor.SuiteVisitor)[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.

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

id is None only in these special cases:

  • Keyword uses a placeholder for setup or teardown when a setup or teardown is not actually used.
  • With If and Try instances representing IF/TRY structure roots.
repr_args = ()
to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.control.Error(values: Sequence[str] = (), parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

Represents syntax error in data.

For example, an invalid setting like [Setpu] or END in wrong place.

type = 'ERROR'
BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

id is None only in these special cases:

  • Keyword uses a placeholder for setup or teardown when a setup or teardown is not actually used.
  • With If and Try instances representing IF/TRY structure roots.
repr_args = ('values',)
to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

values
parent
visit(visitor: robot.model.visitor.SuiteVisitor)[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.

robot.model.filter module

class robot.model.filter.EmptySuiteRemover(preserve_direct_children: bool = False)[source]

Bases: robot.model.visitor.SuiteVisitor

end_suite(suite: TestSuite)[source]

Called when a suite ends. Default implementation does nothing.

visit_test(test: 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.

visit_keyword(keyword: Keyword)[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

end_body_item(item: BodyItem)

Called, by default, when keywords, messages or control structures end.

More specific end_keyword(), end_message(), :meth:`end_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Default implementation does nothing.

end_break(break_: Break)

Called when a BREAK element ends.

By default, calls end_body_item() which, by default, does nothing.

end_continue(continue_: Continue)

Called when a CONTINUE element ends.

By default, calls end_body_item() which, by default, does nothing.

end_error(error: Error)

Called when a ERROR element ends.

By default, calls end_body_item() which, by default, does nothing.

end_for(for_: For)

Called when a FOR loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_for_iteration(iteration: ForIteration)

Called when a FOR loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

end_if(if_: If)

Called when an IF/ELSE structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_if_branch(branch: IfBranch)

Called when an IF/ELSE branch ends.

By default, calls end_body_item() which, by default, does nothing.

end_keyword(keyword: Keyword)

Called when a keyword ends.

By default, calls end_body_item() which, by default, does nothing.

end_message(message: Message)

Called when a message ends.

By default, calls end_body_item() which, by default, does nothing.

end_return(return_: Return)

Called when a RETURN element ends.

By default, calls end_body_item() which, by default, does nothing.

end_test(test: TestCase)

Called when a test ends. Default implementation does nothing.

end_try(try_: Try)

Called when a TRY/EXCEPT structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_try_branch(branch: TryBranch)

Called when TRY, EXCEPT, ELSE and FINALLY branches end.

By default, calls end_body_item() which, by default, does nothing.

end_while(while_: While)

Called when a WHILE loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_while_iteration(iteration: WhileIteration)

Called when a WHILE loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

start_body_item(item: BodyItem) → bool|None

Called, by default, when keywords, messages or control structures start.

More specific start_keyword(), start_message(), :meth:`start_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Can return explicit False to stop visiting. Default implementation does nothing.

start_break(break_: Break) → bool|None

Called when a BREAK element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_continue(continue_: Continue) → bool|None

Called when a CONTINUE element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_error(error: Error) → bool|None

Called when a ERROR element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for(for_: For) → bool|None

Called when a FOR loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration: ForIteration) → bool|None

Called when a FOR loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if(if_: If) → bool|None

Called when an IF/ELSE structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch: IfBranch) → bool|None

Called when an IF/ELSE branch starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword: Keyword) → bool|None

Called when a keyword starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_message(message: Message) → bool|None

Called when a message starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_return(return_: Return) → bool|None

Called when a RETURN element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_suite(suite: TestSuite) → bool|None

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test: TestCase) → bool|None

Called when a test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_try(try_: Try) → bool|None

Called when a TRY/EXCEPT structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_try_branch(branch: TryBranch) → bool|None

Called when TRY, EXCEPT, ELSE or FINALLY branches start.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while(while_: While) → bool|None

Called when a WHILE loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while_iteration(iteration: WhileIteration) → bool|None

Called when a WHILE loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

visit_break(break_: Break)

Visits BREAK elements.

visit_continue(continue_: Continue)

Visits CONTINUE elements.

visit_error(error: Error)

Visits body items resulting from invalid syntax.

Examples include syntax like END or ELSE in wrong place and invalid setting like [Invalid].

visit_for(for_: For)

Implements traversing through FOR loops.

Can be overridden to allow modifying the passed in for_ without calling start_for() or end_for() nor visiting body.

visit_for_iteration(iteration: ForIteration)

Implements traversing through single FOR loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_for_iteration() or end_for_iteration() nor visiting body.

visit_if(if_: If)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and they are visited separately using visit_if_branch().

Can be overridden to allow modifying the passed in if_ without calling start_if() or end_if() nor visiting branches.

visit_if_branch(branch: IfBranch)

Implements traversing through single IF/ELSE branch.

Can be overridden to allow modifying the passed in branch without calling start_if_branch() or end_if_branch() nor visiting body.

visit_message(message: Message)

Implements visiting messages.

Can be overridden to allow modifying the passed in msg without calling start_message() or end_message().

visit_return(return_: Return)

Visits a RETURN elements.

visit_suite(suite: TestSuite)

Implements traversing through suites.

Can be overridden to allow modifying the passed in suite without calling start_suite() or end_suite() nor visiting child suites, tests or setup and teardown at all.

visit_try(try_: Try)

Implements traversing through TRY/EXCEPT structures.

This method is used with the TRY/EXCEPT root element. Actual TRY, EXCEPT, ELSE and FINALLY branches are visited separately using visit_try_branch().

visit_try_branch(branch: TryBranch)

Visits individual TRY, EXCEPT, ELSE and FINALLY branches.

visit_while(while_: While)

Implements traversing through WHILE loops.

Can be overridden to allow modifying the passed in while_ without calling start_while() or end_while() nor visiting body.

visit_while_iteration(iteration: WhileIteration)

Implements traversing through single WHILE loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_while_iteration() or end_while_iteration() nor visiting body.

class robot.model.filter.Filter(include_suites: Union[robot.model.namepatterns.SuiteNamePatterns, Sequence[str], None] = None, include_tests: Union[robot.model.namepatterns.TestNamePatterns, Sequence[str], None] = None, include_tags: Union[robot.model.tags.TagPatterns, Sequence[str], None] = None, exclude_tags: Union[robot.model.tags.TagPatterns, Sequence[str], None] = None)[source]

Bases: robot.model.filter.EmptySuiteRemover

include_suites
include_tests
include_tags
end_body_item(item: BodyItem)

Called, by default, when keywords, messages or control structures end.

More specific end_keyword(), end_message(), :meth:`end_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Default implementation does nothing.

end_break(break_: Break)

Called when a BREAK element ends.

By default, calls end_body_item() which, by default, does nothing.

end_continue(continue_: Continue)

Called when a CONTINUE element ends.

By default, calls end_body_item() which, by default, does nothing.

end_error(error: Error)

Called when a ERROR element ends.

By default, calls end_body_item() which, by default, does nothing.

end_for(for_: For)

Called when a FOR loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_for_iteration(iteration: ForIteration)

Called when a FOR loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

end_if(if_: If)

Called when an IF/ELSE structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_if_branch(branch: IfBranch)

Called when an IF/ELSE branch ends.

By default, calls end_body_item() which, by default, does nothing.

end_keyword(keyword: Keyword)

Called when a keyword ends.

By default, calls end_body_item() which, by default, does nothing.

end_message(message: Message)

Called when a message ends.

By default, calls end_body_item() which, by default, does nothing.

end_return(return_: Return)

Called when a RETURN element ends.

By default, calls end_body_item() which, by default, does nothing.

end_suite(suite: TestSuite)

Called when a suite ends. Default implementation does nothing.

end_test(test: TestCase)

Called when a test ends. Default implementation does nothing.

end_try(try_: Try)

Called when a TRY/EXCEPT structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_try_branch(branch: TryBranch)

Called when TRY, EXCEPT, ELSE and FINALLY branches end.

By default, calls end_body_item() which, by default, does nothing.

end_while(while_: While)

Called when a WHILE loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_while_iteration(iteration: WhileIteration)

Called when a WHILE loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

exclude_tags
start_body_item(item: BodyItem) → bool|None

Called, by default, when keywords, messages or control structures start.

More specific start_keyword(), start_message(), :meth:`start_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Can return explicit False to stop visiting. Default implementation does nothing.

start_break(break_: Break) → bool|None

Called when a BREAK element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_continue(continue_: Continue) → bool|None

Called when a CONTINUE element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_error(error: Error) → bool|None

Called when a ERROR element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for(for_: For) → bool|None

Called when a FOR loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration: ForIteration) → bool|None

Called when a FOR loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if(if_: If) → bool|None

Called when an IF/ELSE structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch: IfBranch) → bool|None

Called when an IF/ELSE branch starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword: Keyword) → bool|None

Called when a keyword starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_message(message: Message) → bool|None

Called when a message starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_return(return_: Return) → bool|None

Called when a RETURN element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_test(test: TestCase) → bool|None

Called when a test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_try(try_: Try) → bool|None

Called when a TRY/EXCEPT structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_try_branch(branch: TryBranch) → bool|None

Called when TRY, EXCEPT, ELSE or FINALLY branches start.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while(while_: While) → bool|None

Called when a WHILE loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while_iteration(iteration: WhileIteration) → bool|None

Called when a WHILE loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

visit_break(break_: Break)

Visits BREAK elements.

visit_continue(continue_: Continue)

Visits CONTINUE elements.

visit_error(error: Error)

Visits body items resulting from invalid syntax.

Examples include syntax like END or ELSE in wrong place and invalid setting like [Invalid].

visit_for(for_: For)

Implements traversing through FOR loops.

Can be overridden to allow modifying the passed in for_ without calling start_for() or end_for() nor visiting body.

visit_for_iteration(iteration: ForIteration)

Implements traversing through single FOR loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_for_iteration() or end_for_iteration() nor visiting body.

visit_if(if_: If)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and they are visited separately using visit_if_branch().

Can be overridden to allow modifying the passed in if_ without calling start_if() or end_if() nor visiting branches.

visit_if_branch(branch: IfBranch)

Implements traversing through single IF/ELSE branch.

Can be overridden to allow modifying the passed in branch without calling start_if_branch() or end_if_branch() nor visiting body.

visit_keyword(keyword: Keyword)

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

visit_message(message: Message)

Implements visiting messages.

Can be overridden to allow modifying the passed in msg without calling start_message() or end_message().

visit_return(return_: Return)

Visits a RETURN elements.

visit_suite(suite: TestSuite)

Implements traversing through suites.

Can be overridden to allow modifying the passed in suite without calling start_suite() or end_suite() nor visiting child suites, tests or setup and teardown at all.

visit_test(test: TestCase)

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_try(try_: Try)

Implements traversing through TRY/EXCEPT structures.

This method is used with the TRY/EXCEPT root element. Actual TRY, EXCEPT, ELSE and FINALLY branches are visited separately using visit_try_branch().

visit_try_branch(branch: TryBranch)

Visits individual TRY, EXCEPT, ELSE and FINALLY branches.

visit_while(while_: While)

Implements traversing through WHILE loops.

Can be overridden to allow modifying the passed in while_ without calling start_while() or end_while() nor visiting body.

visit_while_iteration(iteration: WhileIteration)

Implements traversing through single WHILE loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_while_iteration() or end_while_iteration() nor visiting body.

start_suite(suite: TestSuite)[source]

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

robot.model.fixture module

robot.model.fixture.create_fixture(fixture_class: Type[T], fixture: T|DataDict|None, parent: TestCase|TestSuite|Keyword|UserKeyword, fixture_type: str) → T[source]

Create or configure a fixture_class instance.

robot.model.itemlist module

class robot.model.itemlist.ItemList(item_class: Type[T], common_attrs: dict[str, typing.Any] | None[dict, None] = None, items: Iterable[Union[T, Dict[str, Any]]] = ())[source]

Bases: collections.abc.MutableSequence, typing.Generic

List of items of a certain enforced type.

New items can be created using the create() method and existing items added using the common list methods like append() or insert(). In addition to the common type, items can have certain common and automatically assigned attributes.

Starting from Robot Framework 6.1, items can be added as dictionaries and actual items are generated based on them automatically. If the type has a from_dict class method, it is used, and otherwise dictionary data is passed to the type as keyword arguments.

item_type

alias of builtins.type

create(*args, **kwargs) → T[source]

Create a new item using the provided arguments.

append(item: Union[T, Dict[str, Any]]) → T[source]

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

extend(items: Iterable[Union[T, Dict[str, Any]]])[source]

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

insert(index: int, item: Union[T, Dict[str, Any]])[source]

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

index(value[, start[, stop]]) → integer -- return first index of value.[source]

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

clear() → None -- remove all items from S[source]
visit(visitor: SuiteVisitor)[source]
count(value) → integer -- return number of occurrences of value[source]
sort(**config)[source]
reverse()[source]

S.reverse() – reverse IN PLACE

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

to_dicts() → list[source]

Return list of items converted to dictionaries.

Items are converted to dictionaries using the to_dict method, if they have it, or the built-in vars().

New in Robot Framework 6.1.

robot.model.keyword module

class robot.model.keyword.Keyword(name: str|None = '', args: Sequence[str] = (), assign: Sequence[str] = (), type: str = 'KEYWORD', parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None)[source]

Bases: robot.model.body.BodyItem

Base model for a single keyword.

Extended by robot.running.model.Keyword and robot.result.model.Keyword.

repr_args = ('name', 'args', 'assign')
args
assign
type
parent
name
id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

id is None only in these special cases:

  • Keyword uses a placeholder for setup or teardown when a setup or teardown is not actually used.
  • With If and Try instances representing IF/TRY structure roots.
visit(visitor: SuiteVisitor)[source]

Visitor interface entry-point.

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

Serialize this object into a dictionary.

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

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.keyword.Keywords(parent: Union[TestSuite, TestCase, UserKeyword, For, ForIteration, If, IfBranch, Try, TryBranch, While, WhileIteration, Keyword, Return, Continue, Break, Error, None] = None, keywords: Sequence[robot.model.body.BodyItem] = ())[source]

Bases: robot.model.itemlist.ItemList

A list-like object representing keywords in a suite, a test or a keyword.

Read-only and deprecated since Robot Framework 4.0.

deprecation_message = "'keywords' attribute is read-only and deprecated since Robot Framework 4.0. Use 'body', 'setup' or 'teardown' instead."
setup
create_setup(*args, **kwargs)[source]
teardown
create_teardown(*args, **kwargs)[source]
all

Iterates over all keywords, including setup and teardown.

normal

Iterates over normal keywords, omitting setup and teardown.

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

Create a new item using the provided arguments.

append(item: robot.model.keyword.Keyword)[source]

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

extend(items: Sequence[robot.model.keyword.Keyword])[source]

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

insert(index: int, item: robot.model.keyword.Keyword)[source]

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

pop([index]) → item -- remove and return item at index (default last).[source]

Raise IndexError if list is empty or index is out of range.

remove(item: robot.model.keyword.Keyword)[source]

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

clear() → None -- remove all items from S[source]
count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

item_type

alias of builtins.type

to_dicts() → list

Return list of items converted to dictionaries.

Items are converted to dictionaries using the to_dict method, if they have it, or the built-in vars().

New in Robot Framework 6.1.

visit(visitor: SuiteVisitor)
sort()[source]
reverse()[source]

S.reverse() – reverse IN PLACE

classmethod raise_deprecation_error()[source]

robot.model.message module

class robot.model.message.Message(message='', level='INFO', html=False, timestamp=None, parent=None)[source]

Bases: robot.model.body.BodyItem

A message created during the test execution.

Can be a log message triggered by a keyword, or a warning or an error that occurred during parsing or test execution.

type = 'MESSAGE'
repr_args = ('message', 'level')
message

The message content as a string.

level

Severity of the message. Either TRACE, DEBUG, INFO, WARN, ERROR, FAIL or ``SKIP`. The last two are only used with keyword failure messages.

html

True if the content is in HTML, False otherwise.

timestamp

Timestamp in format %Y%m%d %H:%M:%S.%f.

parent

The object this message was triggered by.

html_message

Returns the message content as HTML.

id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

id is None only in these special cases:

  • Keyword uses a placeholder for setup or teardown when a setup or teardown is not actually used.
  • With If and Try instances representing IF/TRY structure roots.
visit(visitor)[source]

Visitor interface entry-point.

BREAK = 'BREAK'
CONTINUE = 'CONTINUE'
ELSE = 'ELSE'
ELSE_IF = 'ELSE IF'
ERROR = 'ERROR'
EXCEPT = 'EXCEPT'
FINALLY = 'FINALLY'
FOR = 'FOR'
IF = 'IF'
IF_ELSE_ROOT = 'IF/ELSE ROOT'
ITERATION = 'ITERATION'
KEYWORD = 'KEYWORD'
MESSAGE = 'MESSAGE'
RETURN = 'RETURN'
SETUP = 'SETUP'
TEARDOWN = 'TEARDOWN'
TRY = 'TRY'
TRY_EXCEPT_ROOT = 'TRY/EXCEPT ROOT'
WHILE = 'WHILE'
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

to_dict() → Dict[str, Any]

Serialize this object into a dictionary.

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

to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.message.Messages(message_class=<class 'robot.model.message.Message'>, parent=None, messages=None)[source]

Bases: robot.model.itemlist.ItemList

append(item: Union[T, Dict[str, Any]]) → T

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

clear() → None -- remove all items from S
count(value) → integer -- return number of occurrences of value
create(*args, **kwargs) → T

Create a new item using the provided arguments.

extend(items: Iterable[Union[T, Dict[str, Any]]])

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

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index: int, item: Union[T, Dict[str, Any]])

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

item_type

alias of builtins.type

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(**config)
to_dicts() → list

Return list of items converted to dictionaries.

Items are converted to dictionaries using the to_dict method, if they have it, or the built-in vars().

New in Robot Framework 6.1.

visit(visitor: SuiteVisitor)

robot.model.metadata module

class robot.model.metadata.Metadata(initial: collections.abc.Mapping[str, str] | collections.abc.Iterable[tuple[str, str]] | None[collections.abc.Mapping[str, str], collections.abc.Iterable[tuple], None] = None)[source]

Bases: robot.utils.normalizing.NormalizedDict

Free suite metadata as a mapping.

Keys are case, space, and underscore insensitive.

clear() → None. Remove all items from D.
copy() → Self
get(k[, d]) → D[k] if k in D, else d. d defaults to None.
items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
normalized_keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

robot.model.modelobject module

class robot.model.modelobject.ModelObject[source]

Bases: object

repr_args = ()
classmethod from_dict(data: Dict[str, Any]) → T[source]

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T[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, 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.

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

Serialize this object into a dictionary.

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

to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str][source]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

config(**attributes) → T[source]

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T[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.

deepcopy(**attributes) → T[source]

Return a deep copy of this object.

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

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

robot.model.modelobject.full_name(obj_or_cls)[source]
class robot.model.modelobject.JsonLoader[source]

Bases: object

load(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → Dict[str, Any][source]
class robot.model.modelobject.JsonDumper(**config)[source]

Bases: object

dump(data: Dict[str, Any], output: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None) → None | str[None, str][source]

robot.model.modifier module

class robot.model.modifier.ModelModifier(visitors, empty_suite_ok, logger)[source]

Bases: robot.model.visitor.SuiteVisitor

visit_suite(suite)[source]

Implements traversing through suites.

Can be overridden to allow modifying the passed in suite without calling start_suite() or end_suite() nor visiting child suites, tests or setup and teardown at all.

end_body_item(item: BodyItem)

Called, by default, when keywords, messages or control structures end.

More specific end_keyword(), end_message(), :meth:`end_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Default implementation does nothing.

end_break(break_: Break)

Called when a BREAK element ends.

By default, calls end_body_item() which, by default, does nothing.

end_continue(continue_: Continue)

Called when a CONTINUE element ends.

By default, calls end_body_item() which, by default, does nothing.

end_error(error: Error)

Called when a ERROR element ends.

By default, calls end_body_item() which, by default, does nothing.

end_for(for_: For)

Called when a FOR loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_for_iteration(iteration: ForIteration)

Called when a FOR loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

end_if(if_: If)

Called when an IF/ELSE structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_if_branch(branch: IfBranch)

Called when an IF/ELSE branch ends.

By default, calls end_body_item() which, by default, does nothing.

end_keyword(keyword: Keyword)

Called when a keyword ends.

By default, calls end_body_item() which, by default, does nothing.

end_message(message: Message)

Called when a message ends.

By default, calls end_body_item() which, by default, does nothing.

end_return(return_: Return)

Called when a RETURN element ends.

By default, calls end_body_item() which, by default, does nothing.

end_suite(suite: TestSuite)

Called when a suite ends. Default implementation does nothing.

end_test(test: TestCase)

Called when a test ends. Default implementation does nothing.

end_try(try_: Try)

Called when a TRY/EXCEPT structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_try_branch(branch: TryBranch)

Called when TRY, EXCEPT, ELSE and FINALLY branches end.

By default, calls end_body_item() which, by default, does nothing.

end_while(while_: While)

Called when a WHILE loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_while_iteration(iteration: WhileIteration)

Called when a WHILE loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

start_body_item(item: BodyItem) → bool|None

Called, by default, when keywords, messages or control structures start.

More specific start_keyword(), start_message(), :meth:`start_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Can return explicit False to stop visiting. Default implementation does nothing.

start_break(break_: Break) → bool|None

Called when a BREAK element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_continue(continue_: Continue) → bool|None

Called when a CONTINUE element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_error(error: Error) → bool|None

Called when a ERROR element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for(for_: For) → bool|None

Called when a FOR loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration: ForIteration) → bool|None

Called when a FOR loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if(if_: If) → bool|None

Called when an IF/ELSE structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch: IfBranch) → bool|None

Called when an IF/ELSE branch starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword: Keyword) → bool|None

Called when a keyword starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_message(message: Message) → bool|None

Called when a message starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_return(return_: Return) → bool|None

Called when a RETURN element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_suite(suite: TestSuite) → bool|None

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test: TestCase) → bool|None

Called when a test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_try(try_: Try) → bool|None

Called when a TRY/EXCEPT structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_try_branch(branch: TryBranch) → bool|None

Called when TRY, EXCEPT, ELSE or FINALLY branches start.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while(while_: While) → bool|None

Called when a WHILE loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while_iteration(iteration: WhileIteration) → bool|None

Called when a WHILE loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

visit_break(break_: Break)

Visits BREAK elements.

visit_continue(continue_: Continue)

Visits CONTINUE elements.

visit_error(error: Error)

Visits body items resulting from invalid syntax.

Examples include syntax like END or ELSE in wrong place and invalid setting like [Invalid].

visit_for(for_: For)

Implements traversing through FOR loops.

Can be overridden to allow modifying the passed in for_ without calling start_for() or end_for() nor visiting body.

visit_for_iteration(iteration: ForIteration)

Implements traversing through single FOR loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_for_iteration() or end_for_iteration() nor visiting body.

visit_if(if_: If)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and they are visited separately using visit_if_branch().

Can be overridden to allow modifying the passed in if_ without calling start_if() or end_if() nor visiting branches.

visit_if_branch(branch: IfBranch)

Implements traversing through single IF/ELSE branch.

Can be overridden to allow modifying the passed in branch without calling start_if_branch() or end_if_branch() nor visiting body.

visit_keyword(keyword: Keyword)

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

visit_message(message: Message)

Implements visiting messages.

Can be overridden to allow modifying the passed in msg without calling start_message() or end_message().

visit_return(return_: Return)

Visits a RETURN elements.

visit_test(test: TestCase)

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_try(try_: Try)

Implements traversing through TRY/EXCEPT structures.

This method is used with the TRY/EXCEPT root element. Actual TRY, EXCEPT, ELSE and FINALLY branches are visited separately using visit_try_branch().

visit_try_branch(branch: TryBranch)

Visits individual TRY, EXCEPT, ELSE and FINALLY branches.

visit_while(while_: While)

Implements traversing through WHILE loops.

Can be overridden to allow modifying the passed in while_ without calling start_while() or end_while() nor visiting body.

visit_while_iteration(iteration: WhileIteration)

Implements traversing through single WHILE loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_while_iteration() or end_while_iteration() nor visiting body.

robot.model.namepatterns module

class robot.model.namepatterns.NamePatterns(patterns: Sequence[str] = (), ignore: Sequence[str] = '_')[source]

Bases: collections.abc.Iterable, typing.Generic

match(name: str, longname: str | None[str, None] = None) → bool[source]
class robot.model.namepatterns.SuiteNamePatterns(patterns: Sequence[str] = (), ignore: Sequence[str] = '_')[source]

Bases: robot.model.namepatterns.NamePatterns

match(name: str, longname: str | None[str, None] = None) → bool
class robot.model.namepatterns.TestNamePatterns(patterns: Sequence[str] = (), ignore: Sequence[str] = '_')[source]

Bases: robot.model.namepatterns.NamePatterns

match(name: str, longname: str | None[str, None] = None) → bool

robot.model.statistics module

class robot.model.statistics.Statistics(suite, suite_stat_level=-1, tag_stat_include=None, tag_stat_exclude=None, tag_stat_combine=None, tag_doc=None, tag_stat_link=None, rpa=False)[source]

Bases: object

Container for total, suite and tag statistics.

Accepted parameters have the same semantics as the matching command line options.

total = None

Instance of TotalStatistics.

suite = None

Instance of SuiteStatistics.

tags = None

Instance of TagStatistics.

visit(visitor)[source]
class robot.model.statistics.StatisticsBuilder(total_builder, suite_builder, tag_builder)[source]

Bases: robot.model.visitor.SuiteVisitor

start_suite(suite)[source]

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_suite(suite)[source]

Called when a suite ends. Default implementation does nothing.

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

end_body_item(item: BodyItem)

Called, by default, when keywords, messages or control structures end.

More specific end_keyword(), end_message(), :meth:`end_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Default implementation does nothing.

end_break(break_: Break)

Called when a BREAK element ends.

By default, calls end_body_item() which, by default, does nothing.

end_continue(continue_: Continue)

Called when a CONTINUE element ends.

By default, calls end_body_item() which, by default, does nothing.

end_error(error: Error)

Called when a ERROR element ends.

By default, calls end_body_item() which, by default, does nothing.

end_for(for_: For)

Called when a FOR loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_for_iteration(iteration: ForIteration)

Called when a FOR loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

end_if(if_: If)

Called when an IF/ELSE structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_if_branch(branch: IfBranch)

Called when an IF/ELSE branch ends.

By default, calls end_body_item() which, by default, does nothing.

end_keyword(keyword: Keyword)

Called when a keyword ends.

By default, calls end_body_item() which, by default, does nothing.

end_message(message: Message)

Called when a message ends.

By default, calls end_body_item() which, by default, does nothing.

end_return(return_: Return)

Called when a RETURN element ends.

By default, calls end_body_item() which, by default, does nothing.

end_test(test: TestCase)

Called when a test ends. Default implementation does nothing.

end_try(try_: Try)

Called when a TRY/EXCEPT structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_try_branch(branch: TryBranch)

Called when TRY, EXCEPT, ELSE and FINALLY branches end.

By default, calls end_body_item() which, by default, does nothing.

end_while(while_: While)

Called when a WHILE loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_while_iteration(iteration: WhileIteration)

Called when a WHILE loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

start_body_item(item: BodyItem) → bool|None

Called, by default, when keywords, messages or control structures start.

More specific start_keyword(), start_message(), :meth:`start_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Can return explicit False to stop visiting. Default implementation does nothing.

start_break(break_: Break) → bool|None

Called when a BREAK element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_continue(continue_: Continue) → bool|None

Called when a CONTINUE element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_error(error: Error) → bool|None

Called when a ERROR element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for(for_: For) → bool|None

Called when a FOR loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration: ForIteration) → bool|None

Called when a FOR loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if(if_: If) → bool|None

Called when an IF/ELSE structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch: IfBranch) → bool|None

Called when an IF/ELSE branch starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword: Keyword) → bool|None

Called when a keyword starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_message(message: Message) → bool|None

Called when a message starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_return(return_: Return) → bool|None

Called when a RETURN element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_test(test: TestCase) → bool|None

Called when a test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_try(try_: Try) → bool|None

Called when a TRY/EXCEPT structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_try_branch(branch: TryBranch) → bool|None

Called when TRY, EXCEPT, ELSE or FINALLY branches start.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while(while_: While) → bool|None

Called when a WHILE loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while_iteration(iteration: WhileIteration) → bool|None

Called when a WHILE loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

visit_break(break_: Break)

Visits BREAK elements.

visit_continue(continue_: Continue)

Visits CONTINUE elements.

visit_error(error: Error)

Visits body items resulting from invalid syntax.

Examples include syntax like END or ELSE in wrong place and invalid setting like [Invalid].

visit_for(for_: For)

Implements traversing through FOR loops.

Can be overridden to allow modifying the passed in for_ without calling start_for() or end_for() nor visiting body.

visit_for_iteration(iteration: ForIteration)

Implements traversing through single FOR loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_for_iteration() or end_for_iteration() nor visiting body.

visit_if(if_: If)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and they are visited separately using visit_if_branch().

Can be overridden to allow modifying the passed in if_ without calling start_if() or end_if() nor visiting branches.

visit_if_branch(branch: IfBranch)

Implements traversing through single IF/ELSE branch.

Can be overridden to allow modifying the passed in branch without calling start_if_branch() or end_if_branch() nor visiting body.

visit_message(message: Message)

Implements visiting messages.

Can be overridden to allow modifying the passed in msg without calling start_message() or end_message().

visit_return(return_: Return)

Visits a RETURN elements.

visit_suite(suite: TestSuite)

Implements traversing through suites.

Can be overridden to allow modifying the passed in suite without calling start_suite() or end_suite() nor visiting child suites, tests or setup and teardown at all.

visit_try(try_: Try)

Implements traversing through TRY/EXCEPT structures.

This method is used with the TRY/EXCEPT root element. Actual TRY, EXCEPT, ELSE and FINALLY branches are visited separately using visit_try_branch().

visit_try_branch(branch: TryBranch)

Visits individual TRY, EXCEPT, ELSE and FINALLY branches.

visit_while(while_: While)

Implements traversing through WHILE loops.

Can be overridden to allow modifying the passed in while_ without calling start_while() or end_while() nor visiting body.

visit_while_iteration(iteration: WhileIteration)

Implements traversing through single WHILE loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_while_iteration() or end_while_iteration() nor visiting body.

robot.model.stats module

class robot.model.stats.Stat(name)[source]

Bases: robot.utils.sortable.Sortable

Generic statistic object used for storing all the statistic values.

name = None

Human readable identifier of the object these statistics belong to. All Tests for TotalStatistics, long name of the suite for SuiteStatistics or name of the tag for TagStatistics

passed = None

Number of passed tests.

failed = None

Number of failed tests.

skipped = None

Number of skipped tests.

elapsed = None

Number of milliseconds it took to execute.

get_attributes(include_label=False, include_elapsed=False, exclude_empty=True, values_as_strings=False, html_escape=False)[source]
total
add_test(test)[source]
visit(visitor)[source]
class robot.model.stats.TotalStat(name)[source]

Bases: robot.model.stats.Stat

Stores statistic values for a test run.

type = 'total'
add_test(test)
get_attributes(include_label=False, include_elapsed=False, exclude_empty=True, values_as_strings=False, html_escape=False)
total
visit(visitor)
class robot.model.stats.SuiteStat(suite)[source]

Bases: robot.model.stats.Stat

Stores statistics values for a single suite.

type = 'suite'
id = None

Identifier of the suite, e.g. s1-s2.

elapsed = None

Number of milliseconds it took to execute this suite, including sub-suites.

add_stat(other)[source]
add_test(test)
get_attributes(include_label=False, include_elapsed=False, exclude_empty=True, values_as_strings=False, html_escape=False)
total
visit(visitor)
class robot.model.stats.TagStat(name, doc='', links=None, combined=None)[source]

Bases: robot.model.stats.Stat

Stores statistic values for a single tag.

type = 'tag'
doc = None

Documentation of tag as a string.

List of tuples in which the first value is the link URL and the second is the link title. An empty list by default.

combined = None

Pattern as a string if the tag is combined, None otherwise.

info

Returns additional information of the tag statistics are about. Either combined or an empty string.

add_test(test)
get_attributes(include_label=False, include_elapsed=False, exclude_empty=True, values_as_strings=False, html_escape=False)
total
visit(visitor)
class robot.model.stats.CombinedTagStat(pattern, name=None, doc='', links=None)[source]

Bases: robot.model.stats.TagStat

match(tags)[source]
add_test(test)
get_attributes(include_label=False, include_elapsed=False, exclude_empty=True, values_as_strings=False, html_escape=False)
info

Returns additional information of the tag statistics are about. Either combined or an empty string.

total
type = 'tag'
visit(visitor)

robot.model.suitestatistics module

class robot.model.suitestatistics.SuiteStatistics(suite)[source]

Bases: object

Container for suite statistics.

stat = None

Instance of SuiteStat.

suites = None

List of TestSuite objects.

visit(visitor)[source]
class robot.model.suitestatistics.SuiteStatisticsBuilder(suite_stat_level)[source]

Bases: object

current
start_suite(suite)[source]
add_test(test)[source]
end_suite()[source]

robot.model.tags module

class robot.model.tags.Tags(tags: Iterable[str] = ())[source]

Bases: collections.abc.Sequence, typing.Generic

robot(name: str) → bool[source]

Check do tags contain a reserved tag in format robot:<name>.

This is same as ‘robot:<name>’ in tags but considerably faster.

add(tags: Iterable[str])[source]
remove(tags: Iterable[str])[source]
match(tags: Iterable[str]) → bool[source]
count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

class robot.model.tags.TagPatterns(patterns: Iterable[str])[source]

Bases: collections.abc.Sequence, typing.Generic

match(tags: Iterable[str]) → bool[source]
count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

class robot.model.tags.TagPattern[source]

Bases: abc.ABC

classmethod from_string(pattern: str) → robot.model.tags.TagPattern[source]
match(tags: Iterable[str]) → bool[source]
class robot.model.tags.SingleTagPattern(pattern: str)[source]

Bases: robot.model.tags.TagPattern

match(tags: Iterable[str]) → bool[source]
classmethod from_string(pattern: str) → robot.model.tags.TagPattern
class robot.model.tags.AndTagPattern(patterns: Iterable[str])[source]

Bases: robot.model.tags.TagPattern

match(tags: Iterable[str]) → bool[source]
classmethod from_string(pattern: str) → robot.model.tags.TagPattern
class robot.model.tags.OrTagPattern(patterns: Iterable[str])[source]

Bases: robot.model.tags.TagPattern

match(tags: Iterable[str]) → bool[source]
classmethod from_string(pattern: str) → robot.model.tags.TagPattern
class robot.model.tags.NotTagPattern(must_match: str, must_not_match: Iterable[str])[source]

Bases: robot.model.tags.TagPattern

match(tags: Iterable[str]) → bool[source]
classmethod from_string(pattern: str) → robot.model.tags.TagPattern
robot.model.tags.normalize_tags(tags: Iterable[str]) → Iterable[str][source]

Performance optimization to normalize tags only once.

class robot.model.tags.NormalizedTags[source]

Bases: list

append()

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count()

Return number of occurrences of value.

extend()

Extend list by appending elements from the iterable.

index()

Return first index of value.

Raises ValueError if the value is not present.

insert()

Insert object before index.

pop()

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort()

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

robot.model.tagsetter module

class robot.model.tagsetter.TagSetter(add: Union[Sequence[str], str] = (), remove: Union[Sequence[str], str] = ())[source]

Bases: robot.model.visitor.SuiteVisitor

start_suite(suite: TestSuite)[source]

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_test(test: 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.

visit_keyword(keyword: Keyword)[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

end_body_item(item: BodyItem)

Called, by default, when keywords, messages or control structures end.

More specific end_keyword(), end_message(), :meth:`end_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Default implementation does nothing.

end_break(break_: Break)

Called when a BREAK element ends.

By default, calls end_body_item() which, by default, does nothing.

end_continue(continue_: Continue)

Called when a CONTINUE element ends.

By default, calls end_body_item() which, by default, does nothing.

end_error(error: Error)

Called when a ERROR element ends.

By default, calls end_body_item() which, by default, does nothing.

end_for(for_: For)

Called when a FOR loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_for_iteration(iteration: ForIteration)

Called when a FOR loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

end_if(if_: If)

Called when an IF/ELSE structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_if_branch(branch: IfBranch)

Called when an IF/ELSE branch ends.

By default, calls end_body_item() which, by default, does nothing.

end_keyword(keyword: Keyword)

Called when a keyword ends.

By default, calls end_body_item() which, by default, does nothing.

end_message(message: Message)

Called when a message ends.

By default, calls end_body_item() which, by default, does nothing.

end_return(return_: Return)

Called when a RETURN element ends.

By default, calls end_body_item() which, by default, does nothing.

end_suite(suite: TestSuite)

Called when a suite ends. Default implementation does nothing.

end_test(test: TestCase)

Called when a test ends. Default implementation does nothing.

end_try(try_: Try)

Called when a TRY/EXCEPT structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_try_branch(branch: TryBranch)

Called when TRY, EXCEPT, ELSE and FINALLY branches end.

By default, calls end_body_item() which, by default, does nothing.

end_while(while_: While)

Called when a WHILE loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_while_iteration(iteration: WhileIteration)

Called when a WHILE loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

start_body_item(item: BodyItem) → bool|None

Called, by default, when keywords, messages or control structures start.

More specific start_keyword(), start_message(), :meth:`start_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Can return explicit False to stop visiting. Default implementation does nothing.

start_break(break_: Break) → bool|None

Called when a BREAK element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_continue(continue_: Continue) → bool|None

Called when a CONTINUE element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_error(error: Error) → bool|None

Called when a ERROR element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for(for_: For) → bool|None

Called when a FOR loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration: ForIteration) → bool|None

Called when a FOR loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if(if_: If) → bool|None

Called when an IF/ELSE structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch: IfBranch) → bool|None

Called when an IF/ELSE branch starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword: Keyword) → bool|None

Called when a keyword starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_message(message: Message) → bool|None

Called when a message starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_return(return_: Return) → bool|None

Called when a RETURN element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_test(test: TestCase) → bool|None

Called when a test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_try(try_: Try) → bool|None

Called when a TRY/EXCEPT structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_try_branch(branch: TryBranch) → bool|None

Called when TRY, EXCEPT, ELSE or FINALLY branches start.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while(while_: While) → bool|None

Called when a WHILE loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while_iteration(iteration: WhileIteration) → bool|None

Called when a WHILE loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

visit_break(break_: Break)

Visits BREAK elements.

visit_continue(continue_: Continue)

Visits CONTINUE elements.

visit_error(error: Error)

Visits body items resulting from invalid syntax.

Examples include syntax like END or ELSE in wrong place and invalid setting like [Invalid].

visit_for(for_: For)

Implements traversing through FOR loops.

Can be overridden to allow modifying the passed in for_ without calling start_for() or end_for() nor visiting body.

visit_for_iteration(iteration: ForIteration)

Implements traversing through single FOR loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_for_iteration() or end_for_iteration() nor visiting body.

visit_if(if_: If)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and they are visited separately using visit_if_branch().

Can be overridden to allow modifying the passed in if_ without calling start_if() or end_if() nor visiting branches.

visit_if_branch(branch: IfBranch)

Implements traversing through single IF/ELSE branch.

Can be overridden to allow modifying the passed in branch without calling start_if_branch() or end_if_branch() nor visiting body.

visit_message(message: Message)

Implements visiting messages.

Can be overridden to allow modifying the passed in msg without calling start_message() or end_message().

visit_return(return_: Return)

Visits a RETURN elements.

visit_suite(suite: TestSuite)

Implements traversing through suites.

Can be overridden to allow modifying the passed in suite without calling start_suite() or end_suite() nor visiting child suites, tests or setup and teardown at all.

visit_try(try_: Try)

Implements traversing through TRY/EXCEPT structures.

This method is used with the TRY/EXCEPT root element. Actual TRY, EXCEPT, ELSE and FINALLY branches are visited separately using visit_try_branch().

visit_try_branch(branch: TryBranch)

Visits individual TRY, EXCEPT, ELSE and FINALLY branches.

visit_while(while_: While)

Implements traversing through WHILE loops.

Can be overridden to allow modifying the passed in while_ without calling start_while() or end_while() nor visiting body.

visit_while_iteration(iteration: WhileIteration)

Implements traversing through single WHILE loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_while_iteration() or end_while_iteration() nor visiting body.

robot.model.tagstatistics module

class robot.model.tagstatistics.TagStatistics(combined_stats)[source]

Bases: object

Container for tag statistics.

tags = None

Dictionary, where key is the name of the tag as a string and value is an instance of TagStat.

combined = None

List of CombinedTagStat objects.

visit(visitor)[source]
class robot.model.tagstatistics.TagStatisticsBuilder(included=None, excluded=None, combined=None, docs=None, links=None)[source]

Bases: object

add_test(test)[source]
class robot.model.tagstatistics.TagStatInfo(docs=None, links=None)[source]

Bases: object

get_stat(tag)[source]
get_combined_stats(combined=None)[source]
get_doc(tag)[source]
class robot.model.tagstatistics.TagStatDoc(pattern, doc)[source]

Bases: object

match(tag)[source]

Bases: object

match(tag)[source]

robot.model.testcase module

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

Bases: robot.model.modelobject.ModelObject, typing.Generic

Base model for a single test case.

Extended by robot.running.model.TestCase and robot.result.model.TestCase.

body_class

alias of robot.model.body.Body

fixture_class

alias of robot.model.keyword.Keyword

repr_args = ('name',)
name
doc
timeout
lineno
parent
body

Test body as a Body object.

tags

Test tags as a Tags object.

setup

Test setup as a Keyword object.

This attribute is a Keyword object also when a test has no setup but in that case its truth value is False.

Setup can be modified by setting attributes directly:

test.setup.name = 'Example'
test.setup.args = ('First', 'Second')

Alternatively the config() method can be used to set multiple attributes in one call:

test.setup.config(name='Example', args=('First', 'Second'))

The easiest way to reset the whole setup is setting it to None. It will automatically recreate the underlying Keyword object:

test.setup = None

New in Robot Framework 4.0. Earlier setup was accessed like test.keywords.setup.

has_setup

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

A difference between using if test.has_setup: and if test.setup: is that accessing the setup attribute creates a Keyword object representing the setup even when the test actually does not have one. This typically does not matter, but with bigger suite structures containing a huge about of tests it can have an effect on memory usage.

New in Robot Framework 5.0.

teardown

Test teardown as a Keyword object.

See setup for more information.

has_teardown

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

See has_setup for more information.

New in Robot Framework 5.0.

keywords

Deprecated since Robot Framework 4.0

Use body, setup or teardown instead.

id

Test case id in format like s1-t3.

See TestSuite.id for more information.

longname

Test name prefixed with the long name of the parent suite.

source
visit(visitor: SuiteVisitor)[source]

Visitor interface entry-point.

config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

to_dict() → dict[source]

Serialize this object into a dictionary.

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

to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

class robot.model.testcase.TestCases(test_class: Type[TC] = <class 'robot.model.testcase.TestCase'>, parent: TestSuite|None = None, tests: Sequence[TC|DataDict] = ())[source]

Bases: robot.model.itemlist.ItemList

append(item: Union[T, Dict[str, Any]]) → T

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

clear() → None -- remove all items from S
count(value) → integer -- return number of occurrences of value
create(*args, **kwargs) → T

Create a new item using the provided arguments.

extend(items: Iterable[Union[T, Dict[str, Any]]])

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

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index: int, item: Union[T, Dict[str, Any]])

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

item_type

alias of builtins.type

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(**config)
to_dicts() → list

Return list of items converted to dictionaries.

Items are converted to dictionaries using the to_dict method, if they have it, or the built-in vars().

New in Robot Framework 6.1.

visit(visitor: SuiteVisitor)

robot.model.testsuite module

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

Bases: robot.model.modelobject.ModelObject, typing.Generic

Base model for single suite.

Extended by robot.running.model.TestSuite and robot.result.model.TestSuite.

fixture_class

alias of robot.model.keyword.Keyword

test_class

alias of robot.model.testcase.TestCase

repr_args = ('name',)
doc
parent
rpa
static name_from_source(source: pathlib.Path | str | None[pathlib.Path, str, None], extension: Sequence[str] = ()) → str[source]

Create suite name based on the given source.

This method is used by Robot Framework itself when it builds suites. External parsers and other tools that want to produce suites with names matching names created by Robot Framework can use this method as well. This method is also used if name is not set and someone accesses it.

The algorithm is as follows:

  • If the source is None or empty, return an empty string.
  • Get the base name of the source. Read more below.
  • Remove possible prefix separated with __.
  • Convert underscores to spaces.
  • If the name is all lower case, title case it.

The base name of files is got by calling Path.stem that drops the file extension. It typically works fine, but gives wrong result if the extension has multiple parts like in tests.robot.zip. That problem can be avoided by giving valid file extension or extensions as the optional extension argument.

Examples:

TestSuite.name_from_source(source)
TestSuite.name_from_source(source, extension='.robot.zip')
TestSuite.name_from_source(source, ('.robot', '.robot.zip'))
name

Suite name.

If name is not set, it is constructed from source. If source is not set, name is constructed from child suite names by concatenating them with `` & ``. If there are no child suites, name is an empty string.

source
adjust_source(relative_to: pathlib.Path | str | None[pathlib.Path, str, None] = None, root: pathlib.Path | str | None[pathlib.Path, str, None] = None)[source]

Adjust suite source and child suite sources, recursively.

Parameters:
  • relative_to – Make suite source relative to the given path. Calls pathlib.Path.relative_to() internally. Raises ValueError if creating a relative path is not possible.
  • root – Make given path a new root directory for the source. Raises ValueError if suite source is absolute.

Adjusting the source is especially useful when moving data around as JSON:

from robot.running import TestSuite

# Create a suite, adjust source and convert to JSON.
suite = TestSuite.from_file_system('/path/to/data')
suite.adjust_source(relative_to='/path/to')
suite.to_json('data.json')

# Recreate suite elsewhere and adjust source accordingly.
suite = TestSuite.from_json('data.json')
suite.adjust_source(root='/new/path/to')

New in Robot Framework 6.1.

longname

Suite name prefixed with the long name of the parent suite.

metadata

Free suite metadata as a Metadata object.

suites
tests
setup

Suite setup.

This attribute is a Keyword object also when a suite has no setup but in that case its truth value is False. The preferred way to check does a suite have a setup is using has_setup.

Setup can be modified by setting attributes directly:

suite.setup.name = 'Example'
suite.setup.args = ('First', 'Second')

Alternatively the config() method can be used to set multiple attributes in one call:

suite.setup.config(name='Example', args=('First', 'Second'))

The easiest way to reset the whole setup is setting it to None. It will automatically recreate the underlying Keyword object:

suite.setup = None

New in Robot Framework 4.0. Earlier setup was accessed like suite.keywords.setup.

has_setup

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

A difference between using if suite.has_setup: and if suite.setup: is that accessing the setup attribute creates a Keyword object representing the setup even when the suite actually does not have one. This typically does not matter, but with bigger suite structures it can have some effect on memory usage.

New in Robot Framework 5.0.

teardown

Suite teardown.

See setup for more information.

has_teardown

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

See has_setup for more information.

New in Robot Framework 5.0.

keywords

Deprecated since Robot Framework 4.0.

Use setup or teardown instead.

id

An automatically generated unique id.

The root suite has id s1, its child suites have ids s1-s1, s1-s2, …, their child suites get ids s1-s1-s1, s1-s1-s2, …, s1-s2-s1, …, and so on.

The first test in a suite has an id like s1-t1, the second has an id s1-t2, and so on. Similarly, keywords in suites (setup/teardown) and in tests get ids like s1-k1, s1-t1-k1, and s1-s4-t2-k5.

all_tests

Yields all tests this suite and its child suites contain.

New in Robot Framework 6.1.

test_count

Total number of the tests in this suite and in its child suites.

has_tests
set_tags(add: Sequence[str] = (), remove: Sequence[str] = (), persist: bool = False)[source]

Add and/or remove specified tags to the tests in this suite.

Parameters:
  • add – Tags to add as a list or, if adding only one, as a single string.
  • remove – Tags to remove as a list or as a single string. Can be given as patterns where * and ? work as wildcards.
  • persist – Add/remove specified tags also to new tests added to this suite in the future.
filter(included_suites: Optional[Sequence[str], None] = None, included_tests: Optional[Sequence[str], None] = None, included_tags: Optional[Sequence[str], None] = None, excluded_tags: Optional[Sequence[str], None] = None)[source]

Select test cases and remove others from this suite.

Parameters have the same semantics as --suite, --test, --include, and --exclude command line options. All of them can be given as a list of strings, or when selecting only one, as a single string.

Child suites that contain no tests after filtering are automatically removed.

Example:

suite.filter(included_tests=['Test 1', '* Example'],
             included_tags='priority-1')
config(**attributes) → T

Configure model object with given attributes.

obj.config(name='Example', doc='Something') is equivalent to setting obj.name = 'Example' and obj.doc = 'Something'.

New in Robot Framework 4.0.

configure(**options)[source]

A shortcut to configure a suite using one method call.

Can only be used with the root test suite.

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

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

copy(**attributes) → T

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.

deepcopy(**attributes) → T

Return a deep copy of this object.

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

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

classmethod from_dict(data: Dict[str, Any]) → T

Create this object based on data in a dictionary.

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

classmethod from_json(source: str | bytes | typing.TextIO | pathlib.Path[str, bytes, TextIO, pathlib.Path]) → T

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, 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.

to_json(file: None | typing.TextIO | pathlib.Path | str[None, TextIO, pathlib.Path, str] = None, *, ensure_ascii: bool = False, indent: int = 0, separators: tuple = (', ', ':')) → None | str[None, str]

Serialize this object into JSON.

The object is first converted to a Python dictionary using the to_dict() method and then the dictionary is converted to JSON.

The file parameter controls what to do with the resulting JSON data. It can be:

  • None (default) to return the data as a string,
  • an open file object where to write the data, or
  • a path (pathlib.Path or string) to a file where to write the data using UTF-8 encoding.

JSON formatting can be configured using optional parameters that are passed directly to the underlying json module. Notice that the defaults differ from what json uses.

remove_empty_suites(preserve_direct_children: bool = False)[source]

Removes all child suites not containing any tests, recursively.

visit(visitor: robot.model.visitor.SuiteVisitor)[source]

Visitor interface entry-point.

to_dict() → dict[source]

Serialize this object into a dictionary.

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

class robot.model.testsuite.TestSuites(suite_class: Type[TS] = <class 'robot.model.testsuite.TestSuite'>, parent: Optional[TS, None] = None, suites: Sequence[Union[TS, Dict[str, Any]]] = ())[source]

Bases: robot.model.itemlist.ItemList

append(item: Union[T, Dict[str, Any]]) → T

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

clear() → None -- remove all items from S
count(value) → integer -- return number of occurrences of value
create(*args, **kwargs) → T

Create a new item using the provided arguments.

extend(items: Iterable[Union[T, Dict[str, Any]]])

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

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index: int, item: Union[T, Dict[str, Any]])

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

item_type

alias of builtins.type

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort(**config)
to_dicts() → list

Return list of items converted to dictionaries.

Items are converted to dictionaries using the to_dict method, if they have it, or the built-in vars().

New in Robot Framework 6.1.

visit(visitor: SuiteVisitor)

robot.model.totalstatistics module

class robot.model.totalstatistics.TotalStatistics(rpa: bool = False)[source]

Bases: object

Container for total statistics.

visit(visitor)[source]
total
passed
skipped
failed
add_test(test)[source]
message

String representation of the statistics.

For example::
2 tests, 1 passed, 1 failed
class robot.model.totalstatistics.TotalStatisticsBuilder(suite=None, rpa=False)[source]

Bases: robot.model.visitor.SuiteVisitor

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

end_body_item(item: BodyItem)

Called, by default, when keywords, messages or control structures end.

More specific end_keyword(), end_message(), :meth:`end_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Default implementation does nothing.

end_break(break_: Break)

Called when a BREAK element ends.

By default, calls end_body_item() which, by default, does nothing.

end_continue(continue_: Continue)

Called when a CONTINUE element ends.

By default, calls end_body_item() which, by default, does nothing.

end_error(error: Error)

Called when a ERROR element ends.

By default, calls end_body_item() which, by default, does nothing.

end_for(for_: For)

Called when a FOR loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_for_iteration(iteration: ForIteration)

Called when a FOR loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

end_if(if_: If)

Called when an IF/ELSE structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_if_branch(branch: IfBranch)

Called when an IF/ELSE branch ends.

By default, calls end_body_item() which, by default, does nothing.

end_keyword(keyword: Keyword)

Called when a keyword ends.

By default, calls end_body_item() which, by default, does nothing.

end_message(message: Message)

Called when a message ends.

By default, calls end_body_item() which, by default, does nothing.

end_return(return_: Return)

Called when a RETURN element ends.

By default, calls end_body_item() which, by default, does nothing.

end_suite(suite: TestSuite)

Called when a suite ends. Default implementation does nothing.

end_test(test: TestCase)

Called when a test ends. Default implementation does nothing.

end_try(try_: Try)

Called when a TRY/EXCEPT structure ends.

By default, calls end_body_item() which, by default, does nothing.

end_try_branch(branch: TryBranch)

Called when TRY, EXCEPT, ELSE and FINALLY branches end.

By default, calls end_body_item() which, by default, does nothing.

end_while(while_: While)

Called when a WHILE loop ends.

By default, calls end_body_item() which, by default, does nothing.

end_while_iteration(iteration: WhileIteration)

Called when a WHILE loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

start_body_item(item: BodyItem) → bool|None

Called, by default, when keywords, messages or control structures start.

More specific start_keyword(), start_message(), :meth:`start_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Can return explicit False to stop visiting. Default implementation does nothing.

start_break(break_: Break) → bool|None

Called when a BREAK element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_continue(continue_: Continue) → bool|None

Called when a CONTINUE element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_error(error: Error) → bool|None

Called when a ERROR element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for(for_: For) → bool|None

Called when a FOR loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration: ForIteration) → bool|None

Called when a FOR loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if(if_: If) → bool|None

Called when an IF/ELSE structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch: IfBranch) → bool|None

Called when an IF/ELSE branch starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword: Keyword) → bool|None

Called when a keyword starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_message(message: Message) → bool|None

Called when a message starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_return(return_: Return) → bool|None

Called when a RETURN element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_suite(suite: TestSuite) → bool|None

Called when a suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test: TestCase) → bool|None

Called when a test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_try(try_: Try) → bool|None

Called when a TRY/EXCEPT structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_try_branch(branch: TryBranch) → bool|None

Called when TRY, EXCEPT, ELSE or FINALLY branches start.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while(while_: While) → bool|None

Called when a WHILE loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

start_while_iteration(iteration: WhileIteration) → bool|None

Called when a WHILE loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

visit_break(break_: Break)

Visits BREAK elements.

visit_continue(continue_: Continue)

Visits CONTINUE elements.

visit_error(error: Error)

Visits body items resulting from invalid syntax.

Examples include syntax like END or ELSE in wrong place and invalid setting like [Invalid].

visit_for(for_: For)

Implements traversing through FOR loops.

Can be overridden to allow modifying the passed in for_ without calling start_for() or end_for() nor visiting body.

visit_for_iteration(iteration: ForIteration)

Implements traversing through single FOR loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_for_iteration() or end_for_iteration() nor visiting body.

visit_if(if_: If)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and they are visited separately using visit_if_branch().

Can be overridden to allow modifying the passed in if_ without calling start_if() or end_if() nor visiting branches.

visit_if_branch(branch: IfBranch)

Implements traversing through single IF/ELSE branch.

Can be overridden to allow modifying the passed in branch without calling start_if_branch() or end_if_branch() nor visiting body.

visit_message(message: Message)

Implements visiting messages.

Can be overridden to allow modifying the passed in msg without calling start_message() or end_message().

visit_return(return_: Return)

Visits a RETURN elements.

visit_suite(suite: TestSuite)

Implements traversing through suites.

Can be overridden to allow modifying the passed in suite without calling start_suite() or end_suite() nor visiting child suites, tests or setup and teardown at all.

visit_try(try_: Try)

Implements traversing through TRY/EXCEPT structures.

This method is used with the TRY/EXCEPT root element. Actual TRY, EXCEPT, ELSE and FINALLY branches are visited separately using visit_try_branch().

visit_try_branch(branch: TryBranch)

Visits individual TRY, EXCEPT, ELSE and FINALLY branches.

visit_while(while_: While)

Implements traversing through WHILE loops.

Can be overridden to allow modifying the passed in while_ without calling start_while() or end_while() nor visiting body.

visit_while_iteration(iteration: WhileIteration)

Implements traversing through single WHILE loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_while_iteration() or end_while_iteration() nor visiting body.

robot.model.visitor module

Interface to ease traversing through a test suite structure.

Visitors make it easy to modify test suite structures or to collect information from them. They work both with the executable model and the result model, but the objects passed to the visitor methods are slightly different depending on the model they are used with. The main differences are that on the execution side keywords do not have child keywords nor messages, and that only the result objects have status related attributes like status and starttime.

This module contains SuiteVisitor that implements the core logic to visit a test suite structure, and the result package contains ResultVisitor that supports visiting the whole test execution result structure. Both of these visitors should be imported via the robot.api package when used by external code.

Visitor algorithm

All suite, test, keyword and message objects have a visit() method that accepts a visitor instance. These methods will then call the correct visitor method visit_suite(), visit_test(), visit_keyword() or visit_message(), depending on the instance where the visit() method exists.

The recommended and definitely the easiest way to implement a visitor is extending the SuiteVisitor base class. The default implementation of its visit_x() methods take care of traversing child elements of the object x recursively. A visit_x() method first calls a corresponding start_x() method (e.g. visit_suite() calls start_suite()), then calls visit() for all child objects of the x object, and finally calls the corresponding end_x() method. The default implementations of start_x() and end_x() do nothing.

All items that can appear inside tests have their own visit methods. These include visit_keyword(), visit_message() (only applicable with results, not with executable data), visit_for(), visit_if(), and so on, as well as their appropriate start/end methods like start_keyword() and end_for(). If there is a need to visit all these items, it is possible to implement only start_body_item() and end_body_item() methods that are, by default, called by the appropriate start/end methods. These generic methods are new in Robot Framework 5.0.

Visitors extending the SuiteVisitor can stop visiting at a certain level either by overriding suitable visit_x() method or by returning an explicit False from any start_x() method.

Examples

The following example visitor modifies the test suite structure it visits. It could be used, for example, with Robot Framework’s --prerunmodifier option to modify test data before execution.

"""Pre-run modifier that selects only every Xth test for execution.

Starts from the first test by default. Tests are selected per suite.
"""

from robot.api import SuiteVisitor


class SelectEveryXthTest(SuiteVisitor):

    def __init__(self, x: int, start: int = 0):
        self.x = x
        self.start = start

    def start_suite(self, suite):
        """Modify suite's tests to contain only every Xth."""
        suite.tests = suite.tests[self.start::self.x]

    def end_suite(self, suite):
        """Remove suites that are empty after removing tests."""
        suite.suites = [s for s in suite.suites if s.test_count > 0]

    def visit_test(self, test):
        """Avoid visiting tests and their keywords to save a little time."""
        pass

For more examples it is possible to look at the source code of visitors used internally by Robot Framework itself. Some good examples are TagSetter and keyword removers.

Type hints

Visitor methods have type hints to give more information about the model objects they receive to editors. Because visitors can be used with both running and result models, the types that are used are base classes from the robot.model module. Actual visitors may want to import appropriate types from robot.running.model or from robot.result.model modules instead. For example, this code that prints failed tests uses result side model objects:

from robot.api import SuiteVisitor
from robot.result.model import TestCase, TestSuite


class FailurePrinter(SuiteVisitor):

    def start_suite(self, suite: TestSuite):
        print(f"{suite.longname}: {suite.statistics.failed} failed")

    def visit_test(self, test: TestCase):
        if test.failed:
            print(f'- {test.name}: {test.message}')

Type hints were added in Robot Framework 6.1. They are optional and can be removed altogether if they get in the way.

class robot.model.visitor.SuiteVisitor[source]

Bases: object

Abstract class to ease traversing through the suite structure.

See the module level documentation for more information and an example.

visit_suite(suite: TestSuite)[source]

Implements traversing through suites.

Can be overridden to allow modifying the passed in suite without calling start_suite() or end_suite() nor visiting child suites, tests or setup and teardown at all.

start_suite(suite: TestSuite) → bool|None[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(test: 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.

start_test(test: TestCase) → bool|None[source]

Called when a test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_test(test: TestCase)[source]

Called when a test ends. Default implementation does nothing.

visit_keyword(keyword: Keyword)[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

start_keyword(keyword: Keyword) → bool|None[source]

Called when a keyword starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_keyword(keyword: Keyword)[source]

Called when a keyword ends.

By default, calls end_body_item() which, by default, does nothing.

visit_for(for_: For)[source]

Implements traversing through FOR loops.

Can be overridden to allow modifying the passed in for_ without calling start_for() or end_for() nor visiting body.

start_for(for_: For) → bool|None[source]

Called when a FOR loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_for(for_: For)[source]

Called when a FOR loop ends.

By default, calls end_body_item() which, by default, does nothing.

visit_for_iteration(iteration: ForIteration)[source]

Implements traversing through single FOR loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_for_iteration() or end_for_iteration() nor visiting body.

start_for_iteration(iteration: ForIteration) → bool|None[source]

Called when a FOR loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_for_iteration(iteration: ForIteration)[source]

Called when a FOR loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

visit_if(if_: If)[source]

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and they are visited separately using visit_if_branch().

Can be overridden to allow modifying the passed in if_ without calling start_if() or end_if() nor visiting branches.

start_if(if_: If) → bool|None[source]

Called when an IF/ELSE structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_if(if_: If)[source]

Called when an IF/ELSE structure ends.

By default, calls end_body_item() which, by default, does nothing.

visit_if_branch(branch: IfBranch)[source]

Implements traversing through single IF/ELSE branch.

Can be overridden to allow modifying the passed in branch without calling start_if_branch() or end_if_branch() nor visiting body.

start_if_branch(branch: IfBranch) → bool|None[source]

Called when an IF/ELSE branch starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_if_branch(branch: IfBranch)[source]

Called when an IF/ELSE branch ends.

By default, calls end_body_item() which, by default, does nothing.

visit_try(try_: Try)[source]

Implements traversing through TRY/EXCEPT structures.

This method is used with the TRY/EXCEPT root element. Actual TRY, EXCEPT, ELSE and FINALLY branches are visited separately using visit_try_branch().

start_try(try_: Try) → bool|None[source]

Called when a TRY/EXCEPT structure starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_try(try_: Try)[source]

Called when a TRY/EXCEPT structure ends.

By default, calls end_body_item() which, by default, does nothing.

visit_try_branch(branch: TryBranch)[source]

Visits individual TRY, EXCEPT, ELSE and FINALLY branches.

start_try_branch(branch: TryBranch) → bool|None[source]

Called when TRY, EXCEPT, ELSE or FINALLY branches start.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_try_branch(branch: TryBranch)[source]

Called when TRY, EXCEPT, ELSE and FINALLY branches end.

By default, calls end_body_item() which, by default, does nothing.

visit_while(while_: While)[source]

Implements traversing through WHILE loops.

Can be overridden to allow modifying the passed in while_ without calling start_while() or end_while() nor visiting body.

start_while(while_: While) → bool|None[source]

Called when a WHILE loop starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_while(while_: While)[source]

Called when a WHILE loop ends.

By default, calls end_body_item() which, by default, does nothing.

visit_while_iteration(iteration: WhileIteration)[source]

Implements traversing through single WHILE loop iteration.

This is only used with the result side model because on the running side there are no iterations.

Can be overridden to allow modifying the passed in iteration without calling start_while_iteration() or end_while_iteration() nor visiting body.

start_while_iteration(iteration: WhileIteration) → bool|None[source]

Called when a WHILE loop iteration starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_while_iteration(iteration: WhileIteration)[source]

Called when a WHILE loop iteration ends.

By default, calls end_body_item() which, by default, does nothing.

visit_return(return_: Return)[source]

Visits a RETURN elements.

start_return(return_: Return) → bool|None[source]

Called when a RETURN element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_return(return_: Return)[source]

Called when a RETURN element ends.

By default, calls end_body_item() which, by default, does nothing.

visit_continue(continue_: Continue)[source]

Visits CONTINUE elements.

start_continue(continue_: Continue) → bool|None[source]

Called when a CONTINUE element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_continue(continue_: Continue)[source]

Called when a CONTINUE element ends.

By default, calls end_body_item() which, by default, does nothing.

visit_break(break_: Break)[source]

Visits BREAK elements.

start_break(break_: Break) → bool|None[source]

Called when a BREAK element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_break(break_: Break)[source]

Called when a BREAK element ends.

By default, calls end_body_item() which, by default, does nothing.

visit_error(error: Error)[source]

Visits body items resulting from invalid syntax.

Examples include syntax like END or ELSE in wrong place and invalid setting like [Invalid].

start_error(error: Error) → bool|None[source]

Called when a ERROR element starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_error(error: Error)[source]

Called when a ERROR element ends.

By default, calls end_body_item() which, by default, does nothing.

visit_message(message: Message)[source]

Implements visiting messages.

Can be overridden to allow modifying the passed in msg without calling start_message() or end_message().

start_message(message: Message) → bool|None[source]

Called when a message starts.

By default, calls start_body_item() which, by default, does nothing.

Can return explicit False to stop visiting.

end_message(message: Message)[source]

Called when a message ends.

By default, calls end_body_item() which, by default, does nothing.

start_body_item(item: BodyItem) → bool|None[source]

Called, by default, when keywords, messages or control structures start.

More specific start_keyword(), start_message(), :meth:`start_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Can return explicit False to stop visiting. Default implementation does nothing.

end_body_item(item: BodyItem)[source]

Called, by default, when keywords, messages or control structures end.

More specific end_keyword(), end_message(), :meth:`end_for, etc. can be implemented to visit only keywords, messages or specific control structures.

Default implementation does nothing.