A test library providing keywords for handling lists and dictionaries.

Collections is Robot Framework's standard library that provides a set of keywords for handling Python lists and dictionaries. This library has keywords, for example, for modifying and getting values from lists and dictionaries (e.g. Append To List, Get From Dictionary) and for verifying their contents (e.g. Lists Should Be Equal, Dictionary Should Contain Value).

Table of contents

Following keywords in the BuiltIn library can also be used with lists and dictionaries:

Keyword Name Applicable With Comment
Create List lists
Create Dictionary dicts Was in Collections until RF 2.9.
Get Length both
Length Should Be both
Should Be Empty both
Should Not Be Empty both
Should Contain both
Should Not Contain both
Should Contain X Times lists
Should Not Contain X Times lists
Get Count lists

Using with list-like and dictionary-like objects

List keywords that do not alter the given list can also be used with tuples, and to some extend also with other iterables. Convert To List can be used to convert tuples and other iterables to Python list objects.

Similarly dictionary keywords can, for most parts, be used with other mappings. Convert To Dictionary can be used if real Python dict objects are needed.

Boolean arguments

Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is an empty string or equal to FALSE, NONE, NO, OFF or 0, case-insensitively. Keywords verifying something that allow dropping actual and expected values from the possible error message also consider string no values to be false. Other strings are considered true regardless their value, and other argument types are tested using the same rules as in Python.

True examples:

Should Contain Match ${list} ${pattern} case_insensitive=True # Strings are generally true.
Should Contain Match ${list} ${pattern} case_insensitive=yes # Same as the above.
Should Contain Match ${list} ${pattern} case_insensitive=${TRUE} # Python True is true.
Should Contain Match ${list} ${pattern} case_insensitive=${42} # Numbers other than 0 are true.

False examples:

Should Contain Match ${list} ${pattern} case_insensitive=False # String false is false.
Should Contain Match ${list} ${pattern} case_insensitive=no # Also string no is false.
Should Contain Match ${list} ${pattern} case_insensitive=${EMPTY} # Empty string is false.
Should Contain Match ${list} ${pattern} case_insensitive=${FALSE} # Python False is false.
Lists Should Be Equal ${x} ${y} Custom error values=no values # no values works with values argument

Considering string NONE false is new in Robot Framework 3.0.3 and considering also OFF and 0 false is new in Robot Framework 3.1.

Data in examples

List related keywords use variables in format ${Lx} in their examples. They mean lists with as many alphabetic characters as specified by x. For example, ${L1} means ['a'] and ${L3} means ['a', 'b', 'c'].

Dictionary keywords use similar ${Dx} variables. For example, ${D1} means {'a': 1} and ${D3} means {'a': 1, 'b': 2, 'c': 3}.