Version: 2.1.2
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).
Following keywords from the BuiltIn library can also be used with lists and dictionaries:
| Keyword Name | Applicable With |
| Create List | lists |
| Get Length | both |
| Length Should Be | both |
| Should Be Empty | both |
| Should Not Be Empty | both |
| Should Contain | lists |
| Should Not Contain | lists |
| Should Contain X Times | lists |
| Should Not Contain X Times | lists |
| Get Count | lists |
| Keyword | Arguments | Documentation | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Append To List | list, *values | Adds values to the end of list. Example:
- ${L1} = ['a', 'xxx'] - ${L2} = ['a', 'b', 'x', 'y', 'z'] |
||||||||||||||||||
| Combine Lists | *lists | Combines the given lists together and returns the result. The given lists are never altered by this keyword. Example:
- ${x} = ['a', 'a', 'b'] - ${y} = ['a', 'a', 'b', 'a'] - ${L1} and ${L2} are not changed. |
||||||||||||||||||
| Convert To List | item | Converts the given item to a list. Mainly useful for converting tuples and other iterable to lists. Use Create List from the BuiltIn library for constructing new lists. |
||||||||||||||||||
| Copy Dictionary | dictionary | Returns a copy of the given dictionary. The given dictionary is never altered by this keyword. |
||||||||||||||||||
| Copy List | list | Returns a copy of the given list. The given list is never altered by this keyword. |
||||||||||||||||||
| Count Values In List | list, value, start=0, end=None | Returns the number of occurrences of the given value in list. The search can be narrowed to the selected sublist by the start and end indexes having the same semantics as in the Get Slice From List keyword. The given list is never altered by this keyword. Example:
- ${x} = 1 - ${L3} is not changed |
||||||||||||||||||
| Create Dictionary | *key_value_pairs | Creates and returns a dictionary from the given key_value_pairs. Examples:
- ${x} = {'name': 'value'} - ${y} = {'a': '1', 'b': '2'} - ${z} = {'a': 1, 'b': 2} |
||||||||||||||||||
| Dictionaries Should Be Equal | dict1, dict2, msg=None, values=True | Fails if the given dictionaries are not equal. First the equality of dictionaries' keys is checked and after that all the key value pairs. If there are differences between the values, those are listed in the error message. See Lists Should Be Equal for an explanation of msg. The given dictionaries are never altered by this keyword. |
||||||||||||||||||
| Dictionary Should Contain Key | dictionary, key, msg=None | Fails if key is not found from dictionary. See List Should Contain Value for an explanation of msg. The given dictionary is never altered by this keyword. |
||||||||||||||||||
| Dictionary Should Contain Sub Dictionary | dict1, dict2, msg=None, values=True | Fails unless all items in dict2 are found from dict1. See Lists Should Be Equal for an explanation of msg. The given dictionaries are never altered by this keyword. |
||||||||||||||||||
| Dictionary Should Contain Value | dictionary, value, msg=None | Fails if value is not found from dictionary. See List Should Contain Value for an explanation of msg. The given dictionary is never altered by this keyword. |
||||||||||||||||||
| Dictionary Should Not Contain Key | dictionary, key, msg=None | Fails if key is found from dictionary. See List Should Contain Value for an explanation of msg. The given dictionary is never altered by this keyword. |
||||||||||||||||||
| Dictionary Should Not Contain Value | dictionary, value, msg=None | Fails if value is found from dictionary. See List Should Contain Value for an explanation of msg. The given dictionary is never altered by this keyword. |
||||||||||||||||||
| Get Dictionary Items | dictionary | Returns items of the given dictionary. Items are returned sorted by keys. The given dictionary is never altered by this keyword. Example:
- ${items} = ['a', 1, 'b', 2, 'c', 3] |
||||||||||||||||||
| Get Dictionary Keys | dictionary | Returns keys of the given dictionary. Keys are returned in sorted order. The given dictionary is never altered by this keyword. Example:
- ${keys} = ['a', 'b', 'c'] |
||||||||||||||||||
| Get Dictionary Values | dictionary | Returns values of the given dictionary. Values are returned sorted according to keys. The given dictionary is never altered by this keyword. Example:
- ${values} = [1, 2, 3] |
||||||||||||||||||
| Get From Dictionary | dictionary, key | Returns a value from the given dictionary based on the given key. If the given key cannot be found from the dictionary, this keyword fails. The given dictionary is never altered by this keyword. Example:
- ${value} = 2 |
||||||||||||||||||
| Get From List | list, index | Returns the value specified with an index from list. The given list is never altered by this keyword. Index '0' means the first position, '1' the second, and so on. Similarly, '-1' is the last position, '-2' the second last, and so on. Using an index that does not exist on the list causes an error. The index can be either an integer or a string that can be converted to an integer. Examples (including Python equivalents in comments):
- ${x} = 'a' - ${y} = 'd' - ${L5} is not changed |
||||||||||||||||||
| Get Index From List | list, value, start=0, end=None | Returns the index of the first occurrence of the value on the list. The search can be narrowed to the selected sublist by the start and end indexes having the same semantics as in the Get Slice From List keyword. In case the value is not found, -1 is returned. The given list is never altered by this keyword. Example:
- ${x} = 3 - ${L5} is not changed |
||||||||||||||||||
| Get Slice From List | list, start=0, end=None | Returns a slice of the given list between start and end indexes. The given list is never altered by this keyword. If both start and end are given, a sublist containing values from start to end is returned. This is the same as 'list[start:end]' in Python. To get all items from the beginning, use 0 as the start value, and to get all items until the end, use 'None' as the end value. 'None' is also a default value, so in this case, it is enough to give only start. If only end is given, start gets the value 0. Using start or end not found on the list is the same as using the largest (or smallest) available index. Examples (incl. Python equivelants in comments):
- ${x} = ['c', 'd'] - ${y} = ['b', 'c', 'd', 'e'] - ${z} = ['a', 'b', 'c'] - ${L5} is not changed |
||||||||||||||||||
| Insert Into List | list, index, value | Inserts value into list to the position specified with index. Index '0' adds the value into the first position, '1' to the second, and so on. Inserting from right works with negative indices so that '-1' is the second last position, '-2' third last, and so on. Use Append To List to add items to the end of the list. If the absolute value of the index is greater than the length of the list, the value is added at the end (positive index) or the beginning (negative index). An index can be given either as an integer or a string that can be converted to an integer. Example:
- ${L1} = ['xxx', 'a'] - ${L2} = ['a', 'xxx', 'b'] |
||||||||||||||||||
| Keep In Dictionary | dictionary, *keys | Keeps the given keys in the dictionary and removes all other. If the given key cannot be found from the dictionary, it is ignored. Example:
- ${D5} = {'b': 2, 'd': 4} |
||||||||||||||||||
| List Should Contain Sub List | list1, list2, msg=None, values=True | Fails if not all of the elements in list2 are found in list1. The order of values and the number of values are not taken into account. See the use of msg and values from the Lists Should Be Equal keyword. |
||||||||||||||||||
| List Should Contain Value | list, value, msg=None | Fails if the value is not found from list. If msg is not given, the default error message "[ a | b | c ] does not contain the value 'x'" is shown in case of a failure. Otherwise, the given msg is used in case of a failure. |
||||||||||||||||||
| List Should Not Contain Duplicates | list, msg=None | Fails if any element in the list is found from it more than once. The default error message lists all the elements that were found from the list multiple times, but it can be overridded by giving a custom msg. All multiple times found items and their counts are also logged. This keyword works with all iterables that can be converted to a list. The original iterable is never altered. |
||||||||||||||||||
| List Should Not Contain Value | list, value, msg=None | Fails if the value is not found from list. See List Should Contain Value for an explanation of msg. |
||||||||||||||||||
| Lists Should Be Equal | list1, list2, msg=None, values=True | Fails if given lists are unequal. The keyword first verifies that the lists have equal lengths, and then it checks are all the values equal. Possible differences between the values are listed in the default error message. - If msg is not given, the default error message is used. - If msg is given and values is either Boolean False or a string 'False' or 'No Values', the error message is simply msg. - Otherwise the error message is msg + 'new line' + default. |
||||||||||||||||||
| Log Dictionary | dictionary, level=INFO | Logs the size and contents of the dictionary using given level. Valid levels are TRACE, DEBUG, INFO (default), and WARN. If you only want to log the size, use keyword Get Length from the BuiltIn library. |
||||||||||||||||||
| Log List | list, level=INFO | Logs the length and contents of the list using given level. Valid levels are TRACE, DEBUG, INFO (default), and WARN. If you only want to the length, use keyword Get Length from the BuiltIn library. |
||||||||||||||||||
| Remove From Dictionary | dictionary, *keys | Removes the given keys from the dictionary. If the given key cannot be found from the dictionary, it is ignored. Example:
- ${D3} = {'a': 1, 'c': 3} |
||||||||||||||||||
| Remove From List | list, index | Removes and returns the value specified with an index from list. Index '0' means the first position, '1' the second and so on. Similarly, '-1' is the last position, '-2' the second last, and so on. Using an index that does not exist on the list causes an error. The index can be either an integer or a string that can be converted to an integer. Example:
- ${x} = 'a' - ${L2} = ['b'] |
||||||||||||||||||
| Remove Values From List | list, *values | Removes all occurences of given values from list. It is not an error is a value does not exist in the list at all. Example:
- ${L4} = ['b', 'd'] |
||||||||||||||||||
| Reverse List | list | Reverses the given list in place. Note that the given list is changed and nothing is returned. Use Copy List first, if you need to keep also the original order.
- ${L3} = ['c', 'b', 'a'] |
||||||||||||||||||
| Set List Value | list, index, value | Sets the value of list specified by index to the given value. Index '0' means the first position, '1' the second and so on. Similarly, '-1' is the last position, '-2' second last, and so on. Using an index that does not exist on the list causes an error. The index can be either an integer or a string that can be converted to an integer. Example:
- ${L3} = ['a', 'xxx', 'yyy'] |
||||||||||||||||||
| Set To Dictionary | dictionary, *key_value_pairs | Adds the given key_value_pairs to the dictionary. Example:
- ${D1} = {'a': 1, 'key': 'value'} |
||||||||||||||||||
| Sort List | list | Sorts the given list in place. The strings are sorted alphabetically and the numbers numerically. Note that the given list is changed and nothing is returned. Use Copy List first, if you need to keep also the original order. ${L} = [2,1,'a','c','b']
- ${L} = [1, 2, 'a', 'b', 'c'] |