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

Bases: robot.model.modelobject.ModelObject

KEYWORD = 'KEYWORD'

SETUP = 'SETUP'

TEARDOWN = 'TEARDOWN'

FOR = 'FOR'

FOR_ITERATION = 'FOR ITERATION'

IF_ELSE_ROOT = 'IF/ELSE ROOT'

IF = 'IF'

ELSE_IF = 'ELSE IF'

ELSE = 'ELSE'

MESSAGE = 'MESSAGE'

type = None

id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

config(**attributes)

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)

Return shallow copy of this object.

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

See also deepcopy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

deepcopy(**attributes)

Return deep copy of this object.

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

See also copy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

parent

repr_args = ()

class robot.model.body.Body(parent=None, items=None)

Bases: robot.model.itemlist.ItemList

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

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

keyword_class

alias of robot.model.keyword.Keyword

for_class

alias of robot.model.control.For

if_class

alias of robot.model.control.If

classmethod register(item_class)

create

create_keyword(*args, **kwargs)

create_for(*args, **kwargs)

create_if(*args, **kwargs)

filter(keywords=None, fors=None, ifs=None, predicate=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 FOR and IF constructs use body.filter(fors=False, ifs=False). Including and excluding by types at the same time is not supported.

Custom predicate is a calleble 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.

append(item)

clear()

count(item)

extend(items)

index(item, *start_and_end)

insert(index, item)

pop(*index)

remove(item)

reverse()

sort()

visit(visitor)

class robot.model.body.IfBranches(parent=None, items=None)

Bases: robot.model.body.Body

if_branch_class

alias of robot.model.control.IfBranch

keyword_class = None

for_class = None

if_class = None

create_branch(*args, **kwargs)

append(item)

clear()

count(item)

create

create_for(*args, **kwargs)

create_if(*args, **kwargs)

create_keyword(*args, **kwargs)

extend(items)

filter(keywords=None, fors=None, ifs=None, predicate=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 FOR and IF constructs use body.filter(fors=False, ifs=False). Including and excluding by types at the same time is not supported.

Custom predicate is a calleble 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.

index(item, *start_and_end)

insert(index, item)

pop(*index)

classmethod register(item_class)

remove(item)

reverse()

sort()

visit(visitor)

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)

Bases: robot.model.visitor.SuiteVisitor

add_tags

remove_tags

visit_suite(suite)

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 keywords (setup and teardown) at all.

end_for(for_)

Called when FOR loop ends. Default implementation does nothing.

end_for_iteration(iteration)

Called when FOR loop iteration ends. Default implementation does nothing.

end_if(if_)

Called when IF/ELSE structure ends. Default implementation does nothing.

end_if_branch(branch)

Called when IF/ELSE branch ends. Default implementation does nothing.

end_keyword(keyword)

Called when keyword ends. Default implementation does nothing.

end_message(msg)

Called when message ends. Default implementation does nothing.

end_suite(suite)

Called when suite ends. Default implementation does nothing.

end_test(test)

Called when test ends. Default implementation does nothing.

start_for(for_)

Called when FOR loop starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration)

Called when FOR loop iteration starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if(if_)

Called when IF/ELSE structure starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch)

Called when IF/ELSE branch starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword)

Called when keyword starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_message(msg)

Called when message starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_suite(suite)

Called when suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test)

Called when test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_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)

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_)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and visited 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)

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(kw)

Implements traversing through keywords.

Can be overridden to allow modifying the passed in kw without calling start_keyword() or end_keyword() nor visiting child keywords.

visit_message(msg)

Implements visiting messages.

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

visit_test(test)

Implements traversing through tests.

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

robot.model.control module

class robot.model.control.For(variables=(), flavor='IN', values=(), parent=None)

Bases: robot.model.body.BodyItem

type = 'FOR'

body_class

alias of robot.model.body.Body

repr_args = ('variables', 'flavor', 'values')

variables

flavor

values

parent

body

keywords

Deprecated since Robot Framework 4.0. Use body instead.

visit(visitor)

ELSE = 'ELSE'

ELSE_IF = 'ELSE IF'

FOR = 'FOR'

FOR_ITERATION = 'FOR ITERATION'

IF = 'IF'

IF_ELSE_ROOT = 'IF/ELSE ROOT'

KEYWORD = 'KEYWORD'

MESSAGE = 'MESSAGE'

SETUP = 'SETUP'

TEARDOWN = 'TEARDOWN'

config(**attributes)

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)

Return shallow copy of this object.

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

See also deepcopy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

deepcopy(**attributes)

Return deep copy of this object.

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

See also copy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

class robot.model.control.If(parent=None)

Bases: robot.model.body.BodyItem

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

type = 'IF/ELSE ROOT'

body_class

alias of robot.model.body.IfBranches

parent

body

id

Root IF/ELSE id is always None.

visit(visitor)

ELSE = 'ELSE'

ELSE_IF = 'ELSE IF'

FOR = 'FOR'

FOR_ITERATION = 'FOR ITERATION'

IF = 'IF'

IF_ELSE_ROOT = 'IF/ELSE ROOT'

KEYWORD = 'KEYWORD'

MESSAGE = 'MESSAGE'

SETUP = 'SETUP'

TEARDOWN = 'TEARDOWN'

config(**attributes)

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)

Return shallow copy of this object.

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

See also deepcopy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

deepcopy(**attributes)

Return deep copy of this object.

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

See also copy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

repr_args = ()

class robot.model.control.IfBranch(type='IF', condition=None, parent=None)

Bases: robot.model.body.BodyItem

body_class

alias of robot.model.body.Body

repr_args = ('type', 'condition')

type

condition

parent

ELSE = 'ELSE'

ELSE_IF = 'ELSE IF'

FOR = 'FOR'

FOR_ITERATION = 'FOR ITERATION'

IF = 'IF'

IF_ELSE_ROOT = 'IF/ELSE ROOT'

KEYWORD = 'KEYWORD'

MESSAGE = 'MESSAGE'

SETUP = 'SETUP'

TEARDOWN = 'TEARDOWN'

body

config(**attributes)

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)

Return shallow copy of this object.

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

See also deepcopy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

deepcopy(**attributes)

Return deep copy of this object.

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

See also copy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

id

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

visit(visitor)

robot.model.filter module

class robot.model.filter.EmptySuiteRemover(preserve_direct_children=False)

Bases: robot.model.visitor.SuiteVisitor

end_suite(suite)

Called when suite ends. Default implementation does nothing.

visit_test(test)

Implements traversing through tests.

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

visit_keyword(kw)

Implements traversing through keywords.

Can be overridden to allow modifying the passed in kw without calling start_keyword() or end_keyword() nor visiting child keywords.

end_for(for_)

Called when FOR loop ends. Default implementation does nothing.

end_for_iteration(iteration)

Called when FOR loop iteration ends. Default implementation does nothing.

end_if(if_)

Called when IF/ELSE structure ends. Default implementation does nothing.

end_if_branch(branch)

Called when IF/ELSE branch ends. Default implementation does nothing.

end_keyword(keyword)

Called when keyword ends. Default implementation does nothing.

end_message(msg)

Called when message ends. Default implementation does nothing.

end_test(test)

Called when test ends. Default implementation does nothing.

start_for(for_)

Called when FOR loop starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration)

Called when FOR loop iteration starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if(if_)

Called when IF/ELSE structure starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch)

Called when IF/ELSE branch starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword)

Called when keyword starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_message(msg)

Called when message starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_suite(suite)

Called when suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test)

Called when test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_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)

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_)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and visited 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)

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(msg)

Implements visiting messages.

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

visit_suite(suite)

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 keywords (setup and teardown) at all.

class robot.model.filter.Filter(include_suites=None, include_tests=None, include_tags=None, exclude_tags=None)

Bases: robot.model.filter.EmptySuiteRemover

include_suites

include_tests

include_tags

exclude_tags

start_suite(suite)

Called when suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_for(for_)

Called when FOR loop ends. Default implementation does nothing.

end_for_iteration(iteration)

Called when FOR loop iteration ends. Default implementation does nothing.

end_if(if_)

Called when IF/ELSE structure ends. Default implementation does nothing.

end_if_branch(branch)

Called when IF/ELSE branch ends. Default implementation does nothing.

end_keyword(keyword)

Called when keyword ends. Default implementation does nothing.

end_message(msg)

Called when message ends. Default implementation does nothing.

end_suite(suite)

Called when suite ends. Default implementation does nothing.

end_test(test)

Called when test ends. Default implementation does nothing.

start_for(for_)

Called when FOR loop starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration)

Called when FOR loop iteration starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if(if_)

Called when IF/ELSE structure starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch)

Called when IF/ELSE branch starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword)

Called when keyword starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_message(msg)

Called when message starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test)

Called when test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_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)

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_)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and visited 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)

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(kw)

Implements traversing through keywords.

Can be overridden to allow modifying the passed in kw without calling start_keyword() or end_keyword() nor visiting child keywords.

visit_message(msg)

Implements visiting messages.

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

visit_suite(suite)

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 keywords (setup and teardown) at all.

visit_test(test)

Implements traversing through tests.

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

robot.model.fixture module

robot.model.fixture.create_fixture(fixture, parent, type)

robot.model.itemlist module

class robot.model.itemlist.ItemList(item_class, common_attrs=None, items=None)

Bases: object

create(*args, **kwargs)

append(item)

extend(items)

insert(index, item)

pop(*index)

remove(item)

index(item, *start_and_end)

clear()

visit(visitor)

count(item)

sort()

reverse()

robot.model.keyword module

class robot.model.keyword.Keyword(name='', doc='', args=(), assign=(), tags=(), timeout=None, type='KEYWORD', parent=None)

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')

doc

args

assign

timeout

type

parent

name

teardown

Keyword teardown as a Keyword object.

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

Teardown can be modified by setting attributes directly:

keyword.teardown.name = 'Example'
keyword.teardown.args = ('First', 'Second')

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

keyword.teardown.config(name='Example', args=('First', 'Second'))

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

keyword.teardown = None

New in Robot Framework 4.0. Earlier teardown was accessed like keyword.keywords.teardown.

tags

Keyword tags as a Tags object.

visit(visitor)

Visitor interface entry-point.

ELSE = 'ELSE'

ELSE_IF = 'ELSE IF'

FOR = 'FOR'

FOR_ITERATION = 'FOR ITERATION'

IF = 'IF'

IF_ELSE_ROOT = 'IF/ELSE ROOT'

KEYWORD = 'KEYWORD'

MESSAGE = 'MESSAGE'

SETUP = 'SETUP'

TEARDOWN = 'TEARDOWN'

config(**attributes)

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)

Return shallow copy of this object.

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

See also deepcopy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

deepcopy(**attributes)

Return deep copy of this object.

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

See also copy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

id

Item id in format like s1-t3-k1.

See TestSuite.id for more information.

class robot.model.keyword.Keywords(parent=None, keywords=None)

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)

teardown

create_teardown(*args, **kwargs)

all

Iterates over all keywords, including setup and teardown.

normal

Iterates over normal keywords, omitting setup and teardown.

create(*args, **kwargs)

append(item)

extend(items)

insert(index, item)

pop(*index)

remove(item)

clear()

count(item)

index(item, *start_and_end)

visit(visitor)

sort()

reverse()

classmethod raise_deprecation_error()

robot.model.message module

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

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

visit(visitor)

Visitor interface entry-point.

ELSE = 'ELSE'

ELSE_IF = 'ELSE IF'

FOR = 'FOR'

FOR_ITERATION = 'FOR ITERATION'

IF = 'IF'

IF_ELSE_ROOT = 'IF/ELSE ROOT'

KEYWORD = 'KEYWORD'

MESSAGE = 'MESSAGE'

SETUP = 'SETUP'

TEARDOWN = 'TEARDOWN'

config(**attributes)

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)

Return shallow copy of this object.

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

See also deepcopy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

deepcopy(**attributes)

Return deep copy of this object.

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

See also copy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

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

Bases: robot.model.itemlist.ItemList

append(item)

clear()

count(item)

create(*args, **kwargs)

extend(items)

index(item, *start_and_end)

insert(index, item)

pop(*index)

remove(item)

reverse()

sort()

visit(visitor)

robot.model.metadata module

class robot.model.metadata.Metadata(initial=None)

Bases: robot.utils.normalizing.NormalizedDict

clear() → None. Remove all items from D.

copy()

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

items() → list of D's (key, value) pairs, as 2-tuples

iteritems() → an iterator over the (key, value) items of D

iterkeys() → an iterator over the keys of D

itervalues() → an iterator over the values of D

keys() → list of D's 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() → list of D's values

robot.model.modelobject module

class robot.model.modelobject.ModelObject

Bases: object

repr_args = ()

config(**attributes)

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)

Return shallow copy of this object.

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

See also deepcopy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

deepcopy(**attributes)

Return deep copy of this object.

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

See also copy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

robot.model.modifier module

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

Bases: robot.model.visitor.SuiteVisitor

visit_suite(suite)

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 keywords (setup and teardown) at all.

end_for(for_)

Called when FOR loop ends. Default implementation does nothing.

end_for_iteration(iteration)

Called when FOR loop iteration ends. Default implementation does nothing.

end_if(if_)

Called when IF/ELSE structure ends. Default implementation does nothing.

end_if_branch(branch)

Called when IF/ELSE branch ends. Default implementation does nothing.

end_keyword(keyword)

Called when keyword ends. Default implementation does nothing.

end_message(msg)

Called when message ends. Default implementation does nothing.

end_suite(suite)

Called when suite ends. Default implementation does nothing.

end_test(test)

Called when test ends. Default implementation does nothing.

start_for(for_)

Called when FOR loop starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration)

Called when FOR loop iteration starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if(if_)

Called when IF/ELSE structure starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch)

Called when IF/ELSE branch starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword)

Called when keyword starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_message(msg)

Called when message starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_suite(suite)

Called when suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test)

Called when test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_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)

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_)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and visited 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)

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(kw)

Implements traversing through keywords.

Can be overridden to allow modifying the passed in kw without calling start_keyword() or end_keyword() nor visiting child keywords.

visit_message(msg)

Implements visiting messages.

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

visit_test(test)

Implements traversing through tests.

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

robot.model.namepatterns module

class robot.model.namepatterns.SuiteNamePatterns(patterns=None)

Bases: robot.model.namepatterns._NamePatterns

match(name, longname=None)

class robot.model.namepatterns.TestNamePatterns(patterns=None)

Bases: robot.model.namepatterns._NamePatterns

match(name, longname=None)

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)

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)

class robot.model.statistics.StatisticsBuilder(total_builder, suite_builder, tag_builder)

Bases: robot.model.visitor.SuiteVisitor

start_suite(suite)

Called when suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_suite(suite)

Called when suite ends. Default implementation does nothing.

visit_test(test)

Implements traversing through tests.

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

visit_keyword(kw)

Implements traversing through keywords.

Can be overridden to allow modifying the passed in kw without calling start_keyword() or end_keyword() nor visiting child keywords.

end_for(for_)

Called when FOR loop ends. Default implementation does nothing.

end_for_iteration(iteration)

Called when FOR loop iteration ends. Default implementation does nothing.

end_if(if_)

Called when IF/ELSE structure ends. Default implementation does nothing.

end_if_branch(branch)

Called when IF/ELSE branch ends. Default implementation does nothing.

end_keyword(keyword)

Called when keyword ends. Default implementation does nothing.

end_message(msg)

Called when message ends. Default implementation does nothing.

end_test(test)

Called when test ends. Default implementation does nothing.

start_for(for_)

Called when FOR loop starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration)

Called when FOR loop iteration starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if(if_)

Called when IF/ELSE structure starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch)

Called when IF/ELSE branch starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword)

Called when keyword starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_message(msg)

Called when message starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test)

Called when test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_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)

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_)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and visited 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)

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(msg)

Implements visiting messages.

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

visit_suite(suite)

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 keywords (setup and teardown) at all.

robot.model.stats module

class robot.model.stats.Stat(name)

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)

total

add_test(test)

visit(visitor)

class robot.model.stats.TotalStat(name)

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)

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)

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)

Bases: robot.model.stats.Stat

Stores statistic values for a single tag.

type = 'tag'

doc = None

Documentation of tag as a string.

links = None

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)

Bases: robot.model.stats.TagStat

match(tags)

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)

Bases: object

Container for suite statistics.

stat = None

Instance of SuiteStat.

suites = None

List of TestSuite objects.

visit(visitor)

class robot.model.suitestatistics.SuiteStatisticsBuilder(suite_stat_level)

Bases: object

current

start_suite(suite)

add_test(test)

end_suite()

robot.model.tags module

class robot.model.tags.Tags(tags=None)

Bases: object

add(tags)

remove(tags)

match(tags)

class robot.model.tags.TagPatterns(patterns)

Bases: object

match(tags)

robot.model.tags.TagPattern(pattern)

class robot.model.tags.SingleTagPattern(pattern)

Bases: object

match(tags)

class robot.model.tags.AndTagPattern(patterns)

Bases: object

match(tags)

class robot.model.tags.OrTagPattern(patterns)

Bases: object

match(tags)

class robot.model.tags.NotTagPattern(must_match, *must_not_match)

Bases: object

match(tags)

robot.model.tagsetter module

class robot.model.tagsetter.TagSetter(add=None, remove=None)

Bases: robot.model.visitor.SuiteVisitor

start_suite(suite)

Called when suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_test(test)

Implements traversing through tests.

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

visit_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 child keywords.

end_for(for_)

Called when FOR loop ends. Default implementation does nothing.

end_for_iteration(iteration)

Called when FOR loop iteration ends. Default implementation does nothing.

end_if(if_)

Called when IF/ELSE structure ends. Default implementation does nothing.

end_if_branch(branch)

Called when IF/ELSE branch ends. Default implementation does nothing.

end_keyword(keyword)

Called when keyword ends. Default implementation does nothing.

end_message(msg)

Called when message ends. Default implementation does nothing.

end_suite(suite)

Called when suite ends. Default implementation does nothing.

end_test(test)

Called when test ends. Default implementation does nothing.

start_for(for_)

Called when FOR loop starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration)

Called when FOR loop iteration starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if(if_)

Called when IF/ELSE structure starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch)

Called when IF/ELSE branch starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword)

Called when keyword starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_message(msg)

Called when message starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test)

Called when test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_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)

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_)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and visited 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)

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(msg)

Implements visiting messages.

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

visit_suite(suite)

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 keywords (setup and teardown) at all.

robot.model.tagstatistics module

class robot.model.tagstatistics.TagStatistics(combined_stats)

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)

class robot.model.tagstatistics.TagStatisticsBuilder(included=None, excluded=None, combined=None, docs=None, links=None)

Bases: object

add_test(test)

class robot.model.tagstatistics.TagStatInfo(docs=None, links=None)

Bases: object

get_stat(tag)

get_combined_stats(combined=None)

get_doc(tag)

get_links(tag)

class robot.model.tagstatistics.TagStatDoc(pattern, doc)

Bases: object

match(tag)

class robot.model.tagstatistics.TagStatLink(pattern, link, title)

Bases: object

match(tag)

get_link(tag)

robot.model.testcase module

class robot.model.testcase.TestCase(name='', doc='', tags=None, timeout=None, parent=None)

Bases: robot.model.modelobject.ModelObject

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

parent

body

Test case 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.

teardown

Test teardown as a Keyword object.

See setup for more information.

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)

Visitor interface entry-point.

config(**attributes)

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)

Return shallow copy of this object.

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

See also deepcopy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

deepcopy(**attributes)

Return deep copy of this object.

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

See also copy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

class robot.model.testcase.TestCases(test_class=<class 'robot.model.testcase.TestCase'>, parent=None, tests=None)

Bases: robot.model.itemlist.ItemList

append(item)

clear()

count(item)

create(*args, **kwargs)

extend(items)

index(item, *start_and_end)

insert(index, item)

pop(*index)

remove(item)

reverse()

sort()

visit(visitor)

robot.model.testsuite module

class robot.model.testsuite.TestSuite(name='', doc='', metadata=None, source=None, rpa=False, parent=None)

Bases: robot.model.modelobject.ModelObject

Base model for single suite.

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

test_class

alias of robot.model.testcase.TestCase

fixture_class

alias of robot.model.keyword.Keyword

repr_args = ('name',)

doc

source

Path to the source file or directory.

parent

Parent suite. None with the root suite.

rpa

True when RPA mode is enabled.

name

Test suite name. If not set, constructed from child suite names.

longname

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

metadata

Free test suite metadata as a dictionary.

suites

Child suites as a TestSuites object.

tests

Tests as a TestCases object.

setup

Suite setup as a Keyword object.

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

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.

teardown

Suite teardown as a Keyword object.

See setup for more information.

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.

test_count

Number of the tests in this suite, recursively.

has_tests

set_tags(add=None, remove=None, persist=False)

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=None, included_tests=None, included_tags=None, excluded_tags=None)

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)

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)

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)

Return shallow copy of this object.

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

See also deepcopy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

deepcopy(**attributes)

Return deep copy of this object.

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

See also copy(). The difference between these two is the same as with the standard copy.copy and copy.deepcopy functions that these methods also use internally.

remove_empty_suites(preserve_direct_children=False)

Removes all child suites not containing any tests, recursively.

visit(visitor)

Visitor interface entry-point.

class robot.model.testsuite.TestSuites(suite_class=<class 'robot.model.testsuite.TestSuite'>, parent=None, suites=None)

Bases: robot.model.itemlist.ItemList

append(item)

clear()

count(item)

create(*args, **kwargs)

extend(items)

index(item, *start_and_end)

insert(index, item)

pop(*index)

remove(item)

reverse()

sort()

visit(visitor)

robot.model.totalstatistics module

class robot.model.totalstatistics.TotalStatistics(rpa=False)

Bases: object

Container for total statistics.

visit(visitor)

total

passed

skipped

failed

add_test(test)

message

String representation of the statistics.

For example::

2 tests, 1 passed, 1 failed

class robot.model.totalstatistics.TotalStatisticsBuilder(suite=None, rpa=False)

Bases: robot.model.visitor.SuiteVisitor

add_test(test)

visit_test(test)

Implements traversing through tests.

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

visit_keyword(kw)

Implements traversing through keywords.

Can be overridden to allow modifying the passed in kw without calling start_keyword() or end_keyword() nor visiting child keywords.

end_for(for_)

Called when FOR loop ends. Default implementation does nothing.

end_for_iteration(iteration)

Called when FOR loop iteration ends. Default implementation does nothing.

end_if(if_)

Called when IF/ELSE structure ends. Default implementation does nothing.

end_if_branch(branch)

Called when IF/ELSE branch ends. Default implementation does nothing.

end_keyword(keyword)

Called when keyword ends. Default implementation does nothing.

end_message(msg)

Called when message ends. Default implementation does nothing.

end_suite(suite)

Called when suite ends. Default implementation does nothing.

end_test(test)

Called when test ends. Default implementation does nothing.

start_for(for_)

Called when FOR loop starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_for_iteration(iteration)

Called when FOR loop iteration starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if(if_)

Called when IF/ELSE structure starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_if_branch(branch)

Called when IF/ELSE branch starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_keyword(keyword)

Called when keyword starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_message(msg)

Called when message starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_suite(suite)

Called when suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

start_test(test)

Called when test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

visit_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)

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_)

Implements traversing through IF/ELSE structures.

Notice that if_ does not have any data directly. Actual IF/ELSE branches are in its body and visited 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)

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(msg)

Implements visiting messages.

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

visit_suite(suite)

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 keywords (setup and teardown) at all.

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

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.

class robot.model.visitor.SuiteVisitor

Bases: object

Abstract class to ease traversing through the test suite structure.

See the module level documentation for more information and an example.

visit_suite(suite)

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 keywords (setup and teardown) at all.

start_suite(suite)

Called when suite starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_suite(suite)

Called when suite ends. Default implementation does nothing.

visit_test(test)

Implements traversing through tests.

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

start_test(test)

Called when test starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_test(test)

Called when test ends. Default implementation does nothing.

visit_keyword(kw)

Implements traversing through keywords.

Can be overridden to allow modifying the passed in kw without calling start_keyword() or end_keyword() nor visiting child keywords.

start_keyword(keyword)

Called when keyword starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_keyword(keyword)

Called when keyword ends. Default implementation does nothing.

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

start_for(for_)

Called when FOR loop starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_for(for_)

Called when FOR loop ends. Default implementation does nothing.

visit_for_iteration(iteration)

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)

Called when FOR loop iteration starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_for_iteration(iteration)

Called when FOR loop iteration ends. Default implementation does nothing.

visit_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 visited 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_)

Called when IF/ELSE structure starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_if(if_)

Called when IF/ELSE structure ends. Default implementation does nothing.

visit_if_branch(branch)

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)

Called when IF/ELSE branch starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_if_branch(branch)

Called when IF/ELSE branch ends. Default implementation does nothing.

visit_message(msg)

Implements visiting messages.

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

start_message(msg)

Called when message starts. Default implementation does nothing.

Can return explicit False to stop visiting.

end_message(msg)

Called when message ends. Default implementation does nothing.