String - Documentation

Version: 2.1

Introduction

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 the BuiltIn library can also be used with strings:
- Catenate
- Get Length
- Length Should Be
- Should (Not) Match (Regexp)
- Should (Not) Be Empty
- Should (Not) Be Equal (As Strings/Integers/Numbers)
- Should (Not) Contain
- Should (Not) Start With
- Should (Not) End With

Shortcuts

Keywords

Keyword Arguments Documentation
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:

[LOWER] Lowercase ASCII characters from 'a' to 'z'.
[UPPER] Uppercase ASCII characters from 'A' to 'Z'.
[LETTERS] Lowercase and uppercase ASCII characters.
[NUMBERS] Numbers from 0 to 9.

Examples:
${ret} = Generate Random String
${low} = Generate Random String 12 [LOWER]
${bin} = Generate Random String 8 01
${hex} = Generate Random String 4 [NUMBERS]abcdef
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:
${first} = Get Line ${string} 0
${2nd last} = Get Line ${string} -2
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:
${lines} = Get Lines Containing String ${result} An example
${ret} = Get Lines Containing String ${ret} FAIL case-insensitive

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:
* matches everything
? matches any single character
[chars] matches any character inside square brackets (e.g. '[abc]' matches either 'a', 'b' or 'c')
[!chars] matches any character not inside square brackets

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:
${lines} = Get Lines Matching Pattern ${result} Wild???? example
${ret} = Get Lines Matching Pattern ${ret} FAIL: * case-insensitive

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:
${lines} = Get Lines Matching Regexp ${result} Reg\\w{3} example
${ret} = Get Lines Matching Regexp ${ret} (?i)FAIL: .*

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:
${ignore first} = Get Substring ${string} 1
${ignore last} = Get Substring ${string} -1
${5th to 10th} = Get Substring ${string} 4 10
${first two} = Get Substring ${string} 1
${last two} = Get Substring ${string} -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 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:
${str} = Replace String ${str} Hello Hi
${str} = Replace String ${str} world tellus 1
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.

Examples:
${str} = Replace String Using Regexp ${str} (Hello|Hi) Hei
${str} = Replace String Using Regexp ${str} 20\\d\\d-\\d\\d-\\d\\d <DATE> 2
Should Be String item, msg=None Fails if the given item is not a string.

The default error message can be overridden with the optional msg argument.
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:
@{words} = Split String ${string}
@{words} = Split String ${string} ,${SPACE}
${pre} ${post} = Split String ${string} :: 1

See Split String From Right if you want to start splitting from right, and Fetch From Right 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:
${first} ${others} = Split String ${string} - 1
${others} ${last} = Split String From Right ${string} - 1
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:
@{lines} = Split To Lines ${manylines}
@{ignore first} = Split To Lines ${manylines} 1
@{ignore last} = Split To Lines ${manylines} -1
@{5th to 10th} = Split To Lines ${manylines} 4 10
@{first two} = Split To Lines ${manylines} 1
@{last two} = Split To Lines ${manylines} -2

Use Get Line if you only need to get a single line.