2.5 Keyword Interface and Documentation
Understand the structure of keyword interfaces and how to interpret keyword documentation.
Library Keywords and User Keywords that are defined in a resource file should have a documentation text that describes what the keyword does and how it should be used.
Robot Framework is capable of generating a Keyword Documentation files that contains a library- or resource-documentation, all keywords, their argument interfaces, and their documentation texts.
This documentation file can be generated with the libdoc command and can be used to provide a reference for users who want to use the keywords.
Basically all standard and external 3rd party libraries offer these Keyword Documentations as online available HTML pages.
Robot Framework offers the Keyword Documentation of its Standard Libraries at https://robotframework.org/robotframework .
2.5.1 Documented Keyword Information
Recall the information that can be found in a keyword documentation.
The Keyword Documentation is structured so, that it contains first the library or resource documentation, followed by a list of all keywords that are available in that library or resource file.
Each library or resource documentation can contain the following information sections for keywords:
- Name: The name of the keyword as it is called.
- Arguments (opt.): The argument interface that the keyword expects/offers its types and default values.
- Return Type (opt.): The type of the return value of the keyword.
- (*) Tags (opt.): The tags that are assigned to the keyword to categorize keywords.
- Documentation (opt.): The documentation text that describes what the keyword does and how it should be used.
(*) Understanding keyword tags is not part of the syllabus.
The following keywords are part of the Standard Libraries of Robot Framework.
Their documentation has been generated by the Robot Framework tool libdoc which is included in Robot Framework.
2.5.1.1 Example Keyword Should Be Equal
Documentation of Should Be Equal from BuiltIn library
Should Be Equal is part of the BuiltIn library and is documented as follows:
This keyword has 2 "Mandatory Arguments" and 6 "Optional Arguments". All of them can be called positionally or by name.
2.5.1.2 Example Keyword Run Process
Documentation of Run Process from Process library
Run Process is part of the Process library and is documented as follows:
This keyword has one "Mandatory Arguments" command which can be called positionally or by name.
The latter two arguments are optional.
The argument arguments is a "Variable Number of Positional Arguments" and can only be set by position.
Therefore, if it shall be set, all preceding arguments must be set by position as well.
See 2.5.2.5 Variable Number of Positional Arguments for more information about this kind of argument.
The argument configuration is a "Free Named Argument" and can only be set by names.
See 2.5.2.7 Free Named Arguments for more information about this kind of argument.
2.5.1.3 Example Keyword Get Regexp Matches
Documentation of Get Regexp Matches from String library
Get Regexp Matches is part of the String library and is documented as follows:
This keyword has 2 "Mandatory Arguments" that can be called positionally or by name. The last two arguments are optional.
The argument groups is a "Variable Number of Positional Arguments" and can only be set by position.
Therefore, if it shall be set, all preceding arguments must be set by position as well.
See 2.5.2.5 Variable Number of Positional Arguments for more information about this kind of argument.
The argument flags is a "Named-Only Argument" and can only be set by name.
See 2.5.2.6 Named-Only Arguments for more information about this kind of argument.
2.5.2 Keyword Arguments
Understand the difference between argument kinds.
Most library keywords can be parameterized with arguments that are passed to the keyword when it is called to customize its behavior. The more business oriented keywords are the less arguments they typically have.
Keyword arguments can be grouped into different argument kinds. On the one hand you can group them by their definition attributes and on the other hand by their usage kind.
The relevant distinction of usage kinds is between using Positional Arguments, Named Arguments, or Embedded Arguments. How to use them is described in 2.6 Writing Test|Task and Calling Keywords.
Another important information is if an argument is mandatory or optional. See the next two sections for more information about these two kinds of arguments.
Most arguments can either be set by their position or by their name. But there are some kinds of arguments that can only be set positional, like Variable Number of Positional Arguments, or only be set named, like Named-Only Arguments or Free Named Arguments.
The order is as follows:
- Positional or Named Arguments (can be mandatory or optional)
- Variable Number of Positional Arguments (optional)
- Named-Only Arguments (can be mandatory or optional)
- Free Named Arguments (optional)
2.5.2.1 Mandatory Arguments
Understand the concept of mandatory arguments and how they are documented.
Arguments that do not have a default value, must be set when the keyword is called. These arguments have to be before arguments with default values in the argument interface of the keywords.
See the argument named first and second in the Should Be Equal keyword documentation in the beginning of this section.
If too few arguments are provided, the keyword call will fail with an error message.
Example:
*** Test Cases ***
Tests Will Pass
Should Be Equal One One
Test Will Fail
Should Be Equal One Two
Test Will Fail Due to Missing Args
Should Be Equal One
The first Test will pass, because both argument values are equal.
The second Test will fail, because the argument values are not equal.
The third Test will fail before the keyword Should Be Equal is actually being executed, because the keyword expects at least two arguments.
The Error Message would be: Keyword 'BuiltIn.Should Be Equal' expected 2 to 8 arguments, got 1.
Two arguments are mandatory and additional six arguments are optional in the Should Be Equal keyword.
2.5.2.2 Optional Arguments
Understand the concept of optional arguments and how they are documented.
Arguments that have a default value can be omitted when the keyword is called, causing these arguments to be set to their default value.
These arguments are listed after the mandatory arguments in the argument interface.
Default values are defined and represented in the docs by the equal sign = after the argument name and a value after that.
Also "Variable Number of Positional Arguments", represented with a single star (*) prefix, and "Free Named Arguments", represented with a double star (**) prefix are optional arguments.
E.g. the argument msg in the Should Be Equal keyword documentation has the default value None and ignore_case has the default value False.
In that particular keyword these optional arguments can be used to activate some special features like ignoring the case of the compared strings or to provide a custom error message.
Omitting some optional arguments but still using others is possible independent of their order by setting these arguments by their name. See 2.6 Writing Test|Task and Calling Keywords.
2.5.2.3 Embedded Arguments
Recall the concept of keywords with embedded arguments used in Behavior-Driven Specification and how they are documented.
Keywords can include arguments embedded directly into their names, a feature primarily used for Behavior-Driven Development (BDD). Embedded arguments are mandatory and must be provided in the exact position defined within the keyword name.
Keyword names include arguments defined using the scalar variable syntax with dollar and curly braces (${var_name}).
This syntax explicitly defines these as arguments, distinguishing them from the rest of the keyword name.
Example keyword names are:
"${url}" is openthe user clicks the "${button}" buttonthe page title should be ${exp_title}the url should be ${exp_url}
Example Test Case:
*** Test Cases ***
Foundation Page should be Accessible
Given "robotframework.org" is open
When the user clicks the "FOUNDATION" button
Then the page title should be Foundation | Robot Framework
And the url should be https://robotframework.org/foundation
The optional prefixes Given, When, Then, And and But are basically ignored by Robot Framework if a keyword is found matching the rest of the name including the embedded arguments.
In the example test case some keywords are designed so that the arguments are surrounded by double quotes (") for better visibility.
A mix of embedded arguments and "normal" arguments is possible to fully support BDD.
In the keyword documentation the embedded arguments are written in variable syntax with dollar-curly-braces (${var_name}) to indicate that they are not part of the keyword name but are arguments.
They can also be defined using regular expressions to allow for more complex argument structures, which is not part of this syllabus.
2.5.2.4 Positional or Named Arguments
Recall how "Positional or Named Arguments" are marked in the documentation and their use case.
Except of "Positional-Only Arguments", that are not part of this syllabus, all arguments that are positioned before "Variable Number of Positional Arguments", "Named-Only Arguments", or "Free Named Arguments" in the argument interface of keywords are "Positional or Named Arguments". As their name states, they can be set either by their position or by their name, but not by both at the same time for one argument. If an argument shall be set by its position, all preceding arguments must be set by their position as well.
These arguments can either be mandatory or optional with a default value.
They are not specially marked in the keyword documentation with any prefix, because they are the default kind of arguments in Robot Framework.
2.5.2.5 Variable Number of Positional Arguments
Recall how "Variable Number of Positional Arguments" are marked in the documentation and their use case.
A special case of optional arguments that can only be set by their position are "Variable Number of Positional Arguments".
These are also referred to as *args or *varargs in Python.
Some keywords need to collect a variable amount of values into one argument, because it is not possible to define the amount of values in advance.
One example for this kind of keyword is 2.5.1.2 Example Keyword Run Process from the Process library.
This keyword executes a command with variable amount of arguments and waits for the process to finish.
Depending on the command to be executed different amount of arguments are needed for that command.
This variable argument is marked with a single asterisk * before the argument name in the keyword documentation.
When calling this keyword, the first positional argument is assigned to command, while all subsequent positional arguments are collected into the arguments. Because of this behavior, no additional positional arguments can be used after these "Variable Number of Positional Arguments". As a result, any arguments following these "Variable Number of Positional Arguments" must be named arguments, regardless of whether they are mandatory or optional with default.
Also see 2.5.1.3 Example Keyword Get Regexp Matches.
2.5.2.6 Named-Only Arguments
Recall what properties "Named-Only Arguments" have and how they are documented.
All arguments that are defined after a "Variable Number of Positional Arguments" (*varargs) are "Named-Only Arguments".
However it is also possible to create "Named-Only Arguments without a preceding "Variable Number of Positional Arguments".
"Named-Only Arguments" are marked with a "LABEL" sign 🏷 before the argument name in the keyword documentation.
Those arguments can not be set positionally. All positional values would be consumed by the "Variable Number of Positional Arguments".
So they must be called by their name followed by an equal sign = and the value of the argument.
"Named-Only Arguments" can be mandatory or optional with a default value.
2.5.2.7 Free Named Arguments
Recall how free named arguments are marked in documentation.
Another special case of "Named-Only Arguments" is "Free Named Arguments."
These arguments are similar to the "Variable Number of Positional Arguments" in that they can collect multiple values.
However, instead of collecting positional values, they gather all named values that are not explicitly defined as argument names.
In this case all values given to the keyword as arguments, that do contain an unescaped equal sign (=) are considered as named arguments.
Free named arguments are marked with two asterisks ** before the argument name in the keyword documentation.
The example of the Run Process keyword also has a free named argument ** configuration.
When calling this keyword all named arguments that are not explicitly defined as argument names are collected into the configuration argument and will be available as a dictionary in the keyword implementation.
They are optional and can be omitted.
With this configuration it is possible to e.g. redirect the output of the process to a file or to set the working directory of the process.
Example redirecting stdout and stderr to a file:
*** Test Cases ***
Send 5 IPv4 Pings On Windows
Run Process ping -n 5 -4 localhost stdout=ping_output.txt stderr=ping_error.txt
2.5.2.8 Argument Types
Understand the concept of argument types and automatic type conversion.
Library Keywords may define the expected types of their argument values. Robot Framework specification is mostly done as a string-based language, therefore most statically defined argument values are strings. However, the actual implementation of the keyword may expect a different type of argument, like an integer.
If an argument type is defined and Robot Framework has a matching converter function available, that can convert the given type to the expected type, the conversion is tried automatically. If the conversion fails, the keyword call will fail with an error message before the actual keyword code is executed. Robot Framework brings some built-in converters for common types like integer, float, boolean, list, dictionary, etc. Library developers can also register their own converters for not-supported types.
Defining types for arguments is nowadays the recommended way to let Robot Framework convert the given arguments to the expected type, however it is optional.
Lets imagine a keyword that clicks on a specific coordinate on the screen, i.e. Click On Coordinates.
This keyword would expect two integer arguments, one for the x-coordinate and one for the y-coordinate.
That keyword can now claim that it expects two integer arguments by defining type hints for these arguments. Type hints are show in the keyword documentation at the argument after the optional default value.
Robot Framework in that case tries to convert the given string arguments to the integer type.
Example:
*** Test Cases ***
Test Conversion
Click On Coordinates 10 20 # This will work
Click On Coordinates 10 Not_A_Number # This will fail
In the first call the keyword will be called with the integer values 10 and 20 and will work as expected.
The second keyword call will fail, because the second argument is not a number and cannot be converted to an integer.
The error message would be: ValueError: Argument 'y' got value 'Not_A_Number' that cannot be converted to integer.
The advantage of using type hints is that the user get more information about what kind of values are expected and the keyword implementation can be simpler, because it can rely on the arguments being of the expected type.
2.5.2.9 Return Types
Understand the concept of return type hints.
Keywords may gather information and return these to the caller of that keyword to be stored in a variable and used in further keyword calls.
So, a keyword can RETURN values to the caller as functions do in programming languages.
If the keyword implementation offers a type hint for the return value, this is documented in the keyword documentation. Similar to the argument types, return types are optional and a more recent feature of Robot Framework and therefore not widely used, yet.
It is important to know that keywords without a return type hint are often still returning values! This is typically documented in the Documentation part of the keyword documentation.
2.5.3 Keyword Documentation & Examples
Understand how to read keyword documentation and how to interpret the examples.
Keyword documentation is an important part of the keyword implementation. Good keyword names that clearly communicate what a keyword is doing is even more important, but doing that should not give the impression that a descriptive documentation is not needed.
Documentation is sometimes lean and sometimes extensive, depending on the complexity of the keyword. The documentation should describe what the keyword does, how it should be used, and what the expected arguments are. Depending on the complexity it may also be useful to provide examples of how the keyword can be used.
User Keywords do typically have less extensive documentation, because they are typically used in a more narrower context and can not be configured by arguments that much compared to library keywords of generic external libraries.
Examples in the documentation is commonly either written in table format or as code blocks.
Table Example of Should Be Equal:
| Should Be Equal | ${x} | expected | ||
| Should Be Equal | ${x} | expected | Custom error message | |
| Should Be Equal | ${x} | expected | Custom message | values=False |
| Should Be Equal | ${x} | expected | ignore_case=True | formatter=repr |
Code block example:
Should Be Equal ${x} expected
Should Be Equal ${x} expected Custom error message
Should Be Equal ${x} expected Custom message values=False
Should Be Equal ${x} expected ignore_case=True formatter=repr