String

Converts string to lower case.

Arguments

Argument	Type	Default value	Description
string		null

Uses Python's standard lower() method.

Examples:

${str1} =	Convert To Lower Case	ABC
${str2} =	Convert To Lower Case	1A2c3D
Should Be Equal	${str1}	abc
Should Be Equal	${str2}	1a2c3d

Converts string to title case.

Arguments

Argument	Type	Default value	Description
string		null
exclude		None

Uses the following algorithm:

• Split the string to words from whitespace characters (spaces, newlines, etc.).
• Exclude words that are not all lower case. This preserves, for example, "OK" and "iPhone".
• Exclude also words listed in the optional exclude argument.
• Title case the first alphabetical character of each word that has not been excluded.
• Join all words together so that original whitespace is preserved.

Explicitly excluded words can be given as a list or as a string with words separated by a comma and an optional space. Excluded words are actually considered to be regular expression patterns, so it is possible to use something like "example[.!?]?" to match the word "example" on it own and also if followed by ".", "!" or "?". See BuiltIn.Should Match Regexp for more information about Python regular expression syntax in general and how to use it in Robot Framework data in particular.

Examples:

${str1} =	Convert To Title Case	hello, world!
${str2} =	Convert To Title Case	it's an OK iPhone	exclude=a, an, the
${str3} =	Convert To Title Case	distance is 1 km.	exclude=is, km.?
Should Be Equal	${str1}	Hello, World!
Should Be Equal	${str2}	It's an OK iPhone
Should Be Equal	${str3}	Distance is 1 km.

The reason this keyword does not use Python's standard title() method is that it can yield undesired results, for example, if strings contain upper case letters or special characters like apostrophes. It would, for example, convert "it's an OK iPhone" to "It'S An Ok Iphone".

New in Robot Framework 3.2.

Converts string to upper case.

Arguments

Argument	Type	Default value	Description
string		null

Uses Python's standard upper() method.

Examples:

${str1} =	Convert To Upper Case	abc
${str2} =	Convert To Upper Case	1a2C3d
Should Be Equal	${str1}	ABC
Should Be Equal	${str2}	1A2C3D

Decodes the given bytes to a Unicode string using the given encoding.

Arguments

Argument	Type	Default value	Description
bytes		null
encoding		null
errors		strict

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:

• strict: fail if characters cannot be decoded (default)
• ignore: ignore characters that cannot be decoded
• replace: replace characters that cannot be decoded with a replacement character

Examples:

${string} =	Decode Bytes To String	${bytes}	UTF-8
${string} =	Decode Bytes To String	${bytes}	ASCII	errors=ignore

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.

Encodes the given Unicode string to bytes using the given encoding.

Arguments

Argument	Type	Default value	Description
string		null
encoding		null
errors		strict

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:

• strict: fail if characters cannot be encoded (default)
• ignore: ignore characters that cannot be encoded
• replace: replace characters that cannot be encoded with a replacement character

Examples:

${bytes} =	Encode String To Bytes	${string}	UTF-8
${bytes} =	Encode String To Bytes	${string}	ASCII	errors=ignore

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.

Returns contents of the string before the first occurrence of marker.

Arguments

Argument	Type	Default value	Description
string		null
marker		null

If the marker is not found, whole string is returned.

See also Fetch From Right, Split String and Split String From Right.

Returns contents of the string after the last occurrence of marker.

Arguments

Argument	Type	Default value	Description
string		null
marker		null

If the marker is not found, whole string is returned.

See also Fetch From Left, Split String and Split String From Right.

Formats a template using the given positional and named arguments.

Arguments

Argument	Type	Default value	Description
template		null
positional		null
named		null

The template can be either be a string or an absolute path to an existing file. In the latter case the file is read and its contents are used as the template. If the template file contains non-ASCII characters, it must be encoded using UTF-8.

The template is formatted using Python's format string syntax. Placeholders are marked using {} with possible field name and format specification inside. Literal curly braces can be inserted by doubling them like {{ and }}.

Examples:

${to} =	Format String	To: {} <{}>	${user}	${email}
${to} =	Format String	To: {name} <{email}>	name=${name}	email=${email}
${to} =	Format String	To: {user.name} <{user.email}>	user=${user}
${xx} =	Format String	{:*^30}	centered
${yy} =	Format String	{0:{width}{base}}	${42}	base=X	width=10
${zz} =	Format String	${CURDIR}/template.txt	positional	named=value

New in Robot Framework 3.1.

Generates a string with a desired length from the given chars.

Arguments

Argument	Type	Default value	Description
length		8
chars		[LETTERS][NUMBERS]

length can be given as a number, a string representation of a number, or as a range of numbers, such as 5-10. When a range of values is given the range will be selected by random within the range.

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:

Marker	Explanation
[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
${rnd} =	Generate Random String	5-10	# Generates a string 5 to 10 characters long

Giving length as a range of values is new in Robot Framework 5.0.

Returns the specified line from the given string.

Arguments

Argument	Type	Default value	Description
string		null
line_number		null

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

Use Split To Lines if all lines are needed.

Returns and logs the number of lines in the given string.

Arguments

Argument	Type	Default value	Description
string		null

Returns lines of the given string that contain the pattern.

Arguments

Argument	Type	Default value	Description
string		null
pattern		null
case_insensitive		False

The pattern is always considered to be a normal string, not a glob or regexp pattern. A line matches if the pattern is found anywhere on it.

The match is case-sensitive by default, but giving case_insensitive a true value makes it case-insensitive. The value is considered true if it is a non-empty string that is not equal to false, none or no. If the value is not a string, its truth value is got directly in Python.

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.

Returns lines of the given string that match the pattern.

Arguments

Argument	Type	Default value	Description
string		null
pattern		null
case_insensitive		False

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.

The match is case-sensitive by default, but giving case_insensitive a true value makes it case-insensitive. The value is considered true if it is a non-empty string that is not equal to false, none or no. If the value is not a string, its truth value is got directly in Python.

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=true

See Get Lines Matching Regexp if you need more complex patterns and Get Lines Containing String if searching literal strings is enough.

Returns lines of the given string that match the regexp pattern.

Arguments

Argument	Type	Default value	Description
string		null
pattern		null
partial_match		False

See BuiltIn.Should Match Regexp for more information about Python regular expression syntax in general and how to use it in Robot Framework data in particular.

By default lines match only if they match the pattern fully, but partial matching can be enabled by giving the partial_match argument a true value. The value is considered true if it is a non-empty string that is not equal to false, none or no. If the value is not a string, its truth value is got directly in Python.

If the pattern is empty, it matches only empty lines by default. When partial matching is enabled, empty pattern matches all lines.

Notice that to make the match case-insensitive, you need to prefix the pattern with case-insensitive flag (?i).

Lines are returned as one string concatenated 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
${lines} =	Get Lines Matching Regexp	${result}	Reg\\w{3} example	partial_match=true
${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).

Returns a list of all non-overlapping matches in the given string.

Arguments

Argument	Type	Default value	Description
string		null
pattern		null
groups		null

string is the string to find matches from and pattern is the 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 data in particular.

If no groups are used, the returned list contains full matches. If one group is used, the list contains only contents of that group. If multiple groups are used, the list contains tuples that contain individual group contents. All groups can be given as indexes (starting from 1) and named groups also as names.

Examples:

${no match} =	Get Regexp Matches	the string	xxx
${matches} =	Get Regexp Matches	the string	t..
${one group} =	Get Regexp Matches	the string	t(..)	1
${named group} =	Get Regexp Matches	the string	t(?P<name>..)	name
${two groups} =	Get Regexp Matches	the string	t(.)(.)	1	2

=>

${no match} = []
${matches} = ['the', 'tri']
${one group} = ['he', 'ri']
${named group} = ['he', 'ri']
${two groups} = [('h', 'e'), ('r', 'i')]

Returns a substring from start index to end index.

Arguments

Argument	Type	Default value	Description
string		null
start		null
end		None

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

Removes all removables from the given string.

Arguments

Argument	Type	Default value	Description
string		null
removables		null

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:

${str} =	Remove String	Robot Framework	work
Should Be Equal	${str}	Robot Frame
${str} =	Remove String	Robot Framework	o	bt
Should Be Equal	${str}	R Framewrk

Removes patterns from the given string.

Arguments

Argument	Type	Default value	Description
string		null
patterns		null

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.

Replaces search_for in the given string with replace_with.

Arguments

Argument	Type	Default value	Description
string		null
search_for		null
replace_with		null
count		-1

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:

${str} =	Replace String	Hello, world!	world	tellus
Should Be Equal	${str}	Hello, tellus!
${str} =	Replace String	Hello, world!	l	${EMPTY}	count=1
Should Be Equal	${str}	Helo, world!

Replaces pattern in the given string with replace_with.

Arguments

Argument	Type	Default value	Description
string		null
pattern		null
replace_with		null
count		-1

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 data in particular.

If you need to just remove a string see Remove String Using Regexp.

Examples:

${str} =	Replace String Using Regexp	${str}	20\\d\\d-\\d\\d-\\d\\d	<DATE>
${str} =	Replace String Using Regexp	${str}	(Hello|Hi)	${EMPTY}	count=1

Fails if the given item is not a byte string.

Arguments

Argument	Type	Default value	Description
item		null
msg		None

Use Should Be String if you want to verify the item is a string.

The default error message can be overridden with the optional msg argument.

Fails if the given string is not in lower case.

Arguments

Argument	Type	Default value	Description
string		null
msg		None

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 Upper Case and Should Be Title Case.

Fails if the given item is not a string.

Arguments

Argument	Type	Default value	Description
item		null
msg		None

The default error message can be overridden with the optional msg argument.

Fails if given string is not title.

Arguments

Argument	Type	Default value	Description
string		null
msg		None
exclude		None

string is a title cased string if there is at least one upper case letter in each word.

For example, 'This Is Title' and 'OK, Give Me My iPhone' would pass. 'all words lower' and 'Word In lower' would fail.

This logic changed in Robot Framework 4.0 to be compatible with Convert to Title Case. See Convert to Title Case for title case algorithm and reasoning.

The default error message can be overridden with the optional msg argument.

Words can be explicitly excluded with the optional exclude argument.

Explicitly excluded words can be given as a list or as a string with words separated by a comma and an optional space. Excluded words are actually considered to be regular expression patterns, so it is possible to use something like "example[.!?]?" to match the word "example" on it own and also if followed by ".", "!" or "?". See BuiltIn.Should Match Regexp for more information about Python regular expression syntax in general and how to use it in Robot Framework data in particular.

See also Should Be Upper Case and Should Be Lower Case.

Fails if the given item is not a Unicode string.

Arguments

Argument	Type	Default value	Description
item		null
msg		None

On Python 3 this keyword behaves exactly the same way Should Be String. That keyword should be used instead and this keyword will be deprecated.

Fails if the given string is not in upper case.

Arguments

Argument	Type	Default value	Description
string		null
msg		None

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 Title Case and Should Be Lower Case.

Fails if the given item is a string.

Arguments

Argument	Type	Default value	Description
item		null
msg		None

The default error message can be overridden with the optional msg argument.

Splits the string using separator as a delimiter string.

Arguments

Argument	Type	Default value	Description
string		null
separator		None
max_split		-1

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 Left and Fetch From Right if you only want to get first/last part of the string.

Splits the string using separator starting from right.

Arguments

Argument	Type	Default value	Description
string		null
separator		None
max_split		-1

Same as Split String, but splitting is started from right. This has an effect only when max_split is given.

Examples:

${first}	${rest} =	Split String	${string}	-	1
${rest}	${last} =	Split String From Right	${string}	-	1

Splits the given string to characters.

Arguments

Argument	Type	Default value	Description
string		null

Examples

@{characters} =

Split String To Characters

${string}

Splits the given string to lines.

Arguments

Argument	Type	Default value	Description
string		null
start		0
end		None

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.

Remove leading and/or trailing whitespaces from the given string.

Arguments

Argument	Type	Default value	Description
string		null
mode		both
characters		None

mode is either left to remove leading characters, right to remove trailing characters, both (default) to remove the characters from both sides of the string or none to return the unmodified string.

If the optional characters is given, it must be a string and the characters in the string will be stripped in the string. Please note, that this is not a substring to be removed but a list of characters, see the example below.

Examples:

${stripped}=	Strip String	${SPACE}Hello${SPACE}
Should Be Equal	${stripped}	Hello
${stripped}=	Strip String	${SPACE}Hello${SPACE}	mode=left
Should Be Equal	${stripped}	Hello${SPACE}
${stripped}=	Strip String	aabaHelloeee	characters=abe
Should Be Equal	${stripped}	Hello