In practice this works the same way as when specifying types using the @keyword decorator with normal libraries. Additionally None or null values may not be allowed by the XML-RPC server, but an empty string can be used to indicate that certain argument does not have type information instead. Robot Framework creates instances of listener classes when the test execution starts and uses listeners implemented as modules directly.
During the test execution different listener methods are called when test suites, test cases and keywords start and end. Additional methods are called when a library or a resource or variable file is imported, when output files are ready, and finally when the whole test execution ends. A listener is not required to implement any official interface, and it only needs to have the methods it actually needs. Dynamic libraries have a special run_keyword method for executing their keywords. When a keyword from a dynamic library is used in the test data, Robot Framework uses the run_keywordmethod to get it executed. The first argument is a string containing the name of the keyword to be executed in the same format as returned by get_keyword_names.
The second argument is a list of positional arguments given to the keyword in the test data, and the optional third argument is a dictionary containing named arguments. If the third argument is missing, free named arguments and named-only arguments are not supported, and other named arguments are mapped to positional arguments. Can be used only by Robot Framework itself.WARNUsed to display warnings. They shown also in the console and in the Test Execution Errors section in log files, but they do not affect the test case status.INFOThe default level for normal messages. By default, messages below this level are not shown in the log file.DEBUGUsed for debugging purposes.
Useful, for example, for logging what libraries are doing internally. When a keyword fails, a traceback showing where in the code the failure occurred is logged using this level automatically.TRACEMore detailed debugging level. The keyword arguments and return values are automatically logged using this level.
In many ways, the overall user keyword syntax is identical to thetest case syntax. User keywords are created in Keyword sections which differ from Test Case sections only by the name that is used to identify them. User keyword names are in the first column similarly as test cases names. Also user keywords are created from keywords, either from keywords in test libraries or other user keywords. Keyword names are normally in the second column, but when setting variables from keyword return values, they are in the subsequent columns. Initialization files have the same structure and syntax as test case files, except that they cannot have test case sections and not all settings are supported.
Variables and keywords created or imported in initialization filesare not available in the lower level test suites. If you need to share variables or keywords, you can put them into resource files that can be imported both by initialization and test case files. With dynamic libraries types can be returned using the optionalget_keyword_types method . It can return types using a list or a dictionary exactly like types can be specified when using the @keyword decorator.
See the Supported conversions section for more information about supported types and how to specify them. Most of the content of output files comes from keywords and their log messages. When creating higher level reports, log files are not necessarily needed at all, and in that case keywords and their messages just take space unnecessarily. Log files themselves can also grow overly large, especially if they contain FOR loops or other constructs that repeat certain keywords multiple times.
They can be used in arguments to imported libraries and variable files, but library and variable file names themselves cannot be list variables. Also with setups and teardowns list variable can not be used as the name of the keyword, but can be used in arguments. Using scalar variables is possible in those places where list variables are not supported. Kwargs is optional.get_keyword_argumentsnameReturn keywords' argument specification.
Optional method.get_keyword_typesnameReturn keywords' argument type information. Optional method.get_keyword_documentationnameReturn keywords' and library's documentation. New in RF 3.2.A good example of using the dynamic API is Robot Framework's ownRemote library. Argument converters are functions or other callables that get arguments used in data and convert them to desired format before arguments are passed to keywords. Converters are registered for libraries by settingROBOT_LIBRARY_CONVERTERS attribute (case-sensitive) to a dictionary mapping desired types to converts.
When implementing a library as a module, this attribute must be set on the module level, and with class based libraries it must be a class attribute. With libraries implemented as classes, it is also possible to use the converters argument with the @library decorator. Both of these approaches are illustrated by examples in the following sections. Keywords that are used with Robot Framework are either library keywords or user keywords.
The former come from standard libraries or external libraries, and the latter are either created in the same file where they are used or then imported fromresource files. When many keywords are in use, it is quite common that some of them have the same name, and this section describes how to handle possible conflicts in these situations. The get_keyword_names method must return names of the keyword the server contains as a list of strings.
All these methods take the name of the keyword as an argument and what they must return is explained in the table below. Using the syntax works based on the argument names and default values got from the library using theget_keyword_arguments method. The user keywords and variables defined in a resource file are available in the file that takes that resource file into use.
Similarly available are also all keywords and variables from the libraries, resource files and variable files imported by the said resource file. The high level syntax for creating resource files is exactly the same as when creating test case files and supported file formats are the same as well. When creating user keywords, positional arguments are sufficient in most situations. It is, however, sometimes useful that keywords havedefault values for some or all of their arguments. Also user keywords support default values, and the needed new syntax does not add very much to the already discussed basic syntax. It supports same formatting, splitting to multiple lines, and other features as test case documentation.
It is also shown in a more formal keyword documentation, which the Libdoc tool can create from resource files. Finally, the first logical row of the documentation, until the first empty row, is shown as a keyword documentation in test logs. Test cases and user keywords have a local variable scope that is not seen by other tests or keywords. Local variables can be created usingreturn values from executed keywords and user keywords also get them as arguments. The most common source for variables are Variable sections in test case files and resource files. Variable sections are convenient, because they allow creating variables in the same place as the rest of the test data, and the needed syntax is very simple.
Their main disadvantages are that values are always strings and they cannot be created dynamically. If either of these is a problem, variable files can be used instead. Libraries can also support general library documentation via special __intro__ and__init__ values to the get_keyword_documentation method.
Warnings are shown also in the execution errors section of the normal log file.messageMessages are normally logged to the syslog. If this method is used while a keyword is executing, messages are logged to the normal log file.Other methodsMessages are only logged to the syslog. If the run_keyword method accepts three arguments, the second argument gets all positional arguments as a list and the last arguments gets all named arguments as a mapping. If it accepts only two arguments, named arguments are mapped to positional arguments. The syntax how to represent all these different variables is derived from how they are specified in Python and explained in the following table.
Exception messages are not the only way to give information to the users. Another, and often better, logging possibility is using the programmatic logging APIs. The basic syntax for using Rebot is exactly the same as whenstarting test execution and also most of the command line options are identical. The main difference is that arguments to Rebot areXML output files instead of test data files or directories.
Environment variables ROBOT_OPTIONS and REBOT_OPTIONS can be used to specify default options for test execution and result post-processing, respectively. The options and their values must be defined as a space separated list and they are placed in front of any explicit options on the command line. The main use case for these environment variables is setting global default values for certain options to avoid the need to repeat them every time tests are run or Rebot used. Embedded arguments do not support default values or variable number of arguments like normal arguments do. Using variables when calling these keywords is possible but that can reduce readability.
Notice also that embedded arguments only work with user keywords. When a keyword accepts several arguments with default values and only some of them needs to be overridden, it is often handy to use thenamed arguments syntax. When this syntax is used with user keywords, the arguments are specified without the $decoration. For example, the second keyword above could be used like below and $ would still get its default value. If you specify same individual variable multiple times, the one specified last will override earlier ones.
This allows setting default values for variables in a start-up script and overriding them from the command line. Notice, though, that if multiple variable files have same variables, the ones in the file specified first have the highest priority. In those cases where the library needs arguments, they are listed in the columns after the library name.
It is possible to use default values, variable number of arguments, and named arguments in test library imports similarly as with arguments to keywords. Trying to modify execution in end_suite or end_test methods does not work, simply because that suite or test has already been executed. Remote servers can implement the same methods as the dynamic library APIhas.
This means get_keyword_names method and optional get_keyword_arguments,get_keyword_types, get_keyword_tags and get_keyword_documentation methods. Notice that using "camel-case names" like getKeywordNames is not possible similarly as in the normal dynamic API. The robot.api.deco.keyword decorator allows an easy way to do this since it creates a custom 'robot_name' attribute on the decorated method. This allows generating the list of keywords just by checking for the robot_nameattribute on every method in the library during get_keyword_names. By default, everything written by a method into the standard output is written to the log file as a single entry with the log levelINFO.
Messages written into the standard error are handled similarly otherwise, but they are echoed back to the original stderr after the keyword execution has finished. It is thus possible to use the stderr if you need some messages to be visible on the console where tests are executed. This allows, for example, running tests initially with the TRACE level, and generating smaller log files for normal viewing later with the INFO level. By default all the messages included during execution will be included also with Rebot.
Report files contain an overview of the test execution results in HTML format. They have statistics based on tags and executed test suites, as well as a list of all executed test cases. When both reports and logs are generated, the report has links to the log file for easy navigation to more detailed information. It is easy to see the overall test execution status from report, because its background color is green, if all tests pass and bright red if any test fails. Background can also be yellow, which means that all tests were skipped. This section explains what different output files can be created and how to configure where they are created.
Output files are configured using command line options, which get the path to the output file in question as an argument. A special value NONE(case-insensitive) can be used to disable creating a certain output file. Failures caused by test cases themselves or by keywords they use can sometimes be hard to debug. The first place to look for more information is the execution errors section in the log file.
For example, an error about a failed test library import may well explain why a test has failed due to a missing keyword. Test cases are often executed automatically by a continuous integration system or some other mechanism. In such cases, there is a need to have a script for starting the test execution, and possibly also for post-processing outputs somehow. Similar scripts are also useful when running tests manually, especially if a large number of command line options are needed or setting up the test environment is complicated. Variables in variable files are not limited to having only strings or other base types as values like Variable sections. In the example below, the variable$ contains a Python dictionary and also has two variables created from a custom object implemented in the same file.
Variable files contain variables that can be used in the test data. Many standard Python objects, including strings and numbers, have methods that can be used with the extended variable syntax either explicitly or implicitly. Sometimes this can be really useful and reduce the need for setting temporary variables, but it is also easy to overuse it and create really cryptic test data. Keyword are available everywhere within the scope of the currently executed test suite. Setting variables with this keyword thus has the same effect as creating them using the Variable section in the test data file or importing them from variable files.
Other test suites, including possible child test suites, will not see variables set with this keyword. In some circumstances, for example when continuable failures are used, a test case can fail multiple times. In that case the final error message is got by combining the individual errors. The following example demonstrates using the named arguments syntax with library keywords, user keywords, and when importing the Telnet test library. When Robot Framework parses data, it first splits the data to lines and then lines to tokens such as keywords and arguments.
When using the space separated format, the separator between tokens is two or more spaces or alternatively one or more tab characters. In addition to the normal ASCII space, any Unicode character considered to be a space (e.g. no-break space) works as a separator. Test case files, test suite initialization files and resource files are all created using Robot Framework test data syntax. Test libraries and variable files are created using "real" programming languages, most often Python.
Base types can be used as arguments directly, but more complex types are converted to supported types. Robot Framework does automatic argument conversion also based on theargument default values. Earlier this did not work with the dynamic API because it was possible to specify arguments only as strings. Asdiscussed in the previous section, this was changed in Robot Framework 3.2 and nowadays default values returned like ('example', True) are automatically used for this purpose. With the static API, all this is done using reflection, but dynamic libraries have special methods that are used for these purposes. When start-up scripts gets more complicated, implementing them using shell scripts or batch files is not that convenient.
