| Library version: | 2.8.6 |
|---|---|
| Library scope: | global |
| Named arguments: | supported |
A test library for string manipulation and verification.
String is Robot Framework's standard library for manipulating strings (e.g. Replace String Using Regexp, Split To Lines) and verifying their contents (e.g. Should Be String).
Following keywords from BuiltIn library can also be used with strings:
| Keyword | Arguments | Documentation | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Convert To Lowercase | string | Converts string to lowercase. Examples:
New in Robot Framework 2.8.6. | ||||||||||||||||||||||||||||||
| Convert To Uppercase | string | Converts string to uppercase. Examples:
New in Robot Framework 2.8.6. | ||||||||||||||||||||||||||||||
| Decode Bytes To String | bytes, encoding, errors=strict | Decodes the given bytes to a Unicode string using the given encoding. errors argument controls what to do if decoding some bytes fails. All values accepted by decode method in Python are valid, but in practice the following values are most useful:
Examples:
Use Encode String To Bytes if you need to convert Unicode strings to byte strings, and Convert To String in BuiltIn if you need to convert arbitrary objects to Unicode strings. New in Robot Framework 2.7.7. | ||||||||||||||||||||||||||||||
| Encode String To Bytes | string, encoding, errors=strict | Encodes the given Unicode string to bytes using the given encoding. errors argument controls what to do if encoding some characters fails. All values accepted by encode method in Python are valid, but in practice the following values are most useful:
Examples:
Use Convert To Bytes in BuiltIn if you want to create bytes based on character or integer sequences. Use Decode Bytes To String if you need to convert byte strings to Unicode strings and Convert To String in BuiltIn if you need to convert arbitrary objects to Unicode. New in Robot Framework 2.7.7. | ||||||||||||||||||||||||||||||
| Fetch From Left | string, marker | Returns contents of the string before the first occurrence of marker. If the marker is not found, whole string is returned. See also Fetch From Right, Split String and Split String From Right. | ||||||||||||||||||||||||||||||
| Fetch From Right | string, marker | Returns contents of the string after the last occurrence of marker. If the marker is not found, whole string is returned. See also Fetch From Left, Split String and Split String From Right. | ||||||||||||||||||||||||||||||
| Generate Random String | length=8, chars=[LETTERS][NUMBERS] | Generates a string with a desired length from the given chars. The population sequence chars contains the characters to use when generating the random string. It can contain any characters, and it is possible to use special markers explained in the table below:
Examples:
| ||||||||||||||||||||||||||||||
| Get Line | string, line_number | Returns the specified line from the given string. Line numbering starts from 0 and it is possible to use negative indices to refer to lines from the end. The line is returned without the newline character. Examples:
| ||||||||||||||||||||||||||||||
| Get Line Count | string | Returns and logs the number of lines in the given string. | ||||||||||||||||||||||||||||||
| Get Lines Containing String | string, pattern, case_insensitive=False | Returns lines of the given string that contain the pattern. The pattern is always considered to be a normal string and a line matches if the pattern is found anywhere in it. By default the match is case-sensitive, but setting case_insensitive to any value makes it case-insensitive. Lines are returned as one string catenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged. Examples:
See Get Lines Matching Pattern and Get Lines Matching Regexp if you need more complex pattern matching. | ||||||||||||||||||||||||||||||
| Get Lines Matching Pattern | string, pattern, case_insensitive=False | Returns lines of the given string that match the pattern. The pattern is a glob pattern where:
A line matches only if it matches the pattern fully. By default the match is case-sensitive, but setting case_insensitive to any value makes it case-insensitive. Lines are returned as one string catenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged. Examples:
See Get Lines Matching Regexp if you need more complex patterns and Get Lines Containing String if searching literal strings is enough. | ||||||||||||||||||||||||||||||
| Get Lines Matching Regexp | string, pattern | Returns lines of the given string that match the regexp pattern. See BuiltIn.Should Match Regexp for more information about Python regular expression syntax in general and how to use it in Robot Framework test data in particular. A line matches only if it matches the pattern fully. Notice that to make the match case-insensitive, you need to embed case-insensitive flag into the pattern. Lines are returned as one string catenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged. Examples:
See Get Lines Matching Pattern and Get Lines Containing String if you do not need full regular expression powers (and complexity). | ||||||||||||||||||||||||||||||
| Get Substring | string, start, end=None | Returns a substring from start index to end index. The start index is inclusive and end is exclusive. Indexing starts from 0, and it is possible to use negative indices to refer to characters from the end. Examples:
| ||||||||||||||||||||||||||||||
| Remove String | string, *removables | Removes all removables from the given string. removables are used as literal strings. Each removable will be matched to a temporary string from which preceding removables have been already removed. See second example below. Use Remove String Using Regexp if more powerful pattern matching is needed. If only a certain number of matches should be removed, Replace String or Replace String Using Regexp can be used. A modified version of the string is returned and the original string is not altered. Examples:
New in Robot Framework 2.8.2. | ||||||||||||||||||||||||||||||
| Remove String Using Regexp | string, *patterns | Removes patterns from the given string. This keyword is otherwise identical to Remove String, but the patterns to search for are considered to be a regular expression. See Replace String Using Regexp for more information about the regular expression syntax. That keyword can also be used if there is a need to remove only a certain number of occurrences. New in Robot Framework 2.8.2. | ||||||||||||||||||||||||||||||
| Replace String | string, search_for, replace_with, count=-1 | Replaces search_for in the given string with replace_with. search_for is used as a literal string. See Replace String Using Regexp if more powerful pattern matching is needed. If you need to just remove a string see Remove String. If the optional argument count is given, only that many occurrences from left are replaced. Negative count means that all occurrences are replaced (default behaviour) and zero means that nothing is done. A modified version of the string is returned and the original string is not altered. Examples:
| ||||||||||||||||||||||||||||||
| Replace String Using Regexp | string, pattern, replace_with, count=-1 | Replaces pattern in the given string with replace_with. This keyword is otherwise identical to Replace String, but the pattern to search for is considered to be a regular expression. See BuiltIn.Should Match Regexp for more information about Python regular expression syntax in general and how to use it in Robot Framework test data in particular. If you need to just remove a string see Remove String Using Regexp. Examples:
| ||||||||||||||||||||||||||||||
| Should Be Byte String | item, msg=None | Fails if the given item is not a byte string. Use Should Be Unicode String if you want to verify the item is a Unicode string, or Should Be String if both Unicode and byte strings are fine. The default error message can be overridden with the optional msg argument. New in Robot Framework 2.7.7. | ||||||||||||||||||||||||||||||
| Should Be Lowercase | string, msg=None | Fails if the given string is not in lowercase. For example 'string' and 'with specials!' would pass, and 'String', '' and ' ' would fail. The default error message can be overridden with the optional msg argument. See also Should Be Uppercase and Should Be Titlecase. All these keywords were added in Robot Framework 2.1.2. | ||||||||||||||||||||||||||||||
| Should Be String | item, msg=None | Fails if the given item is not a string. This keyword passes regardless is the item is a Unicode string or a byte string. Use Should Be Unicode String or Should Be Byte String if you want to restrict the string type. The default error message can be overridden with the optional msg argument. | ||||||||||||||||||||||||||||||
| Should Be Titlecase | string, msg=None | Fails if given string is not title. string is a titlecased string if there is at least one character in it, uppercase characters only follow uncased characters and lowercase characters only cased ones. For example 'This Is Title' would pass, and 'Word In UPPER', 'Word In lower', '' and ' ' would fail. The default error message can be overridden with the optional msg argument. See also Should Be Uppercase and Should Be Lowercase. All theses keyword were added in Robot Framework 2.1.2. | ||||||||||||||||||||||||||||||
| Should Be Unicode String | item, msg=None | Fails if the given item is not a Unicode string. Use Should Be Byte String if you want to verify the item is a byte string, or Should Be String if both Unicode and byte strings are fine. The default error message can be overridden with the optional msg argument. New in Robot Framework 2.7.7. | ||||||||||||||||||||||||||||||
| Should Be Uppercase | string, msg=None | Fails if the given string is not in uppercase. For example 'STRING' and 'WITH SPECIALS!' would pass, and 'String', '' and ' ' would fail. The default error message can be overridden with the optional msg argument. See also Should Be Titlecase and Should Be Lowercase. All these keywords were added in Robot Framework 2.1.2. | ||||||||||||||||||||||||||||||
| Should Not Be String | item, msg=None | Fails if the given item is a string. The default error message can be overridden with the optional msg argument. | ||||||||||||||||||||||||||||||
| Split String | string, separator=None, max_split=-1 | Splits the string using separator as a delimiter string. If a separator is not given, any whitespace string is a separator. In that case also possible consecutive whitespace as well as leading and trailing whitespace is ignored. Split words are returned as a list. If the optional max_split is given, at most max_split splits are done, and the returned list will have maximum max_split + 1 elements. Examples:
See Split String From Right if you want to start splitting from right, and Fetch From Left and Fetch From Right if you only want to get first/last part of the string. | ||||||||||||||||||||||||||||||
| Split String From Right | string, separator=None, max_split=-1 | Splits the string using separator starting from right. Same as Split String, but splitting is started from right. This has an effect only when max_split is given. Examples:
| ||||||||||||||||||||||||||||||
| Split String To Characters | string | Splits the given string to characters. Example:
New in Robot Framework 2.7. | ||||||||||||||||||||||||||||||
| Split To Lines | string, start=0, end=None | Converts the string into a list of lines. It is possible to get only a selection of lines from start to end so that start index is inclusive and end is exclusive. Line numbering starts from 0, and it is possible to use negative indices to refer to lines from the end. Lines are returned without the newlines. The number of returned lines is automatically logged. Examples:
Use Get Line if you only need to get a single line. |