Skip to content

Latest commit

 

History

History
841 lines (726 loc) · 35.8 KB

rf-6.0.rst

File metadata and controls

841 lines (726 loc) · 35.8 KB
Raw

Robot Framework 6.0

Robot Framework 6.0 is a new major release that starts Robot Framework's localization efforts. In addition to that, it contains several nice enhancements related to, for example, automatic argument conversion, keyword namespaces and using embedded arguments. It was initially considered a feature release and had version 5.1, but it grew so big that we considered flipping the major number more appropriate.

Questions and comments related to the release can be sent to the robotframework-users mailing list or to Robot Framework Slack, and possible bugs submitted to the issue tracker.

If you have pip installed, just run

pip install --upgrade robotframework

to install the latest available release or use

pip install robotframework==6.0

to install exactly this version. Alternatively, you can download the source distribution from PyPI and install it manually. For more details and other installation approaches, see the installation instructions.

Robot Framework 6.0 was released on Wednesday October 19, 2022. It was superseded by Robot Framework 6.0.1 and Robot Framework 6.0.2.

Most important enhancements

Localization

Robot Framework 6.0 starts our localization efforts by making it possible to translate various markers used in the data. It is possible to translate headers (e.g. Test Cases) and settings (e.g. Documentation) (#4096), Given/When/Then prefixes used in BDD (#519), as well as true and false strings used in Boolean argument conversion (#4400). Future versions may allow translating syntax like IF and FOR, contents of logs and reports, error messages, and so on.

Languages to use are specified when starting execution using the --language command line option. With languages supported by Robot Framework out-of-the-box, it is possible to use just a language code or name like --language fi or --language Finnish. It is also possible to create a custom language file and use it like --language MyLang.py. If there is a need to support multiple languages, the --language option can be used multiple times like --language de --language uk.

In addition to specifying the language from the command line, it is possible to specify it in the data file itself using language: <lang> syntax, where <lang> is a language code or name, before the first section:

language: fi

*** Asetukset ***
Dokumentaatio        Example using Finnish.

Due to technical reasons this per-file language configuration affects also parsing subsequent files, but that behavior is likely to change and should not be dependent on. Either use language: <lang> in each parsed file or specify the language to use from the command line.

Robot Framework 6.0 contains built-in support for these languages in addition to English that is automatically supported. Exact translations used by different languages are listed in the User Guide.

  • Bulgarian (bg)
  • Bosnian (bs)
  • Czech (cs)
  • German (de)
  • Spanish (es)
  • Finnish (fi)
  • French (fr)
  • Hindi (hi)
  • Italian (it)
  • Dutch (nl)
  • Polish (pl)
  • Portuguese (pt)
  • Brazilian Portuguese (pt-BR)
  • Romanian (ro)
  • Russian (ru)
  • Swedish (sv)
  • Thai (th)
  • Turkish (tr)
  • Ukrainian (uk)
  • Chinese Simplified (zh-CN)
  • Chinese Traditional (zh-TW)

All these translations have been provided by our awesome community and we hope to get more community contributed translations in future releases. If you are interested to help, head to Crowdin that we use for collaboration. For more instructions see the Localization project and for general discussion and questions join the #localization channel on our Slack.

Enhancements to using keywords with embedded arguments

When using keywords with embedded arguments, it is pretty common that a keyword that is used matches multiple keyword implementations. For example, Execute "ls" with "-lh" in this example matches both of the keywords:

*** Test Cases ***
Automatic conflict resolution
    Execute "ls"
    Execute "ls" with "-lh"

*** Keywords ***
Execute "${cmd}"
    Log    Running command '${cmd}'.

Execute "${cmd}" with "${opts}"
    Log    Running command '${cmd}' with options '${opts}'.

Earlier when such conflicts occurred, execution failed due to there being multiple matching keywords. Nowadays, if there is a match that is better than others, it will be used and the conflict is resolved. In the above example, Execute "${cmd}" with "${opts}" is considered to be a better match than the more generic Execute "${cmd}" and the example thus succeeds. (#4454)

There can, however, be cases where it is not possible to find a single best match. In such cases conflicts cannot be resolved automatically and execution fails as earlier.

Another nice enhancement related to keywords using embedded arguments is that if they are used with Run Keyword or its variants, arguments are not anymore always converted to strings. That allows passing arguments containing other values than strings as variables also in this context. (#1595)

Enhancements to keyword namespaces

It is possible to mark keywords in resource files as private by adding robot:private tag to them (#430). If such a keyword is used by keywords outside that resource file, there will be a warning. These keywords are also excluded from HTML library documentation generated by Libdoc.

If a keyword exists in the same resource file as a keyword using it, it will be used even if there would be keyword with the same name in another resource file (#4366). Earlier this situation caused a conflict.

If a keyword exists in the same resource file as a keyword using it and there is a keyword with the same name in the test case file, the keyword in the test case file will be used as it has been used earlier. This behavior is nowadays deprecated, though, and in the future local keywords will have precedence also in these cases.

Enhancements to automatic argument conversion

Automatic argument conversion makes it possible for library authors to specify what types certain arguments have and then Robot Framework automatically converts used arguments accordingly. This support has been enhanced in various ways.

Nowadays, if a container type like list is used with parameters like list[int], arguments are not only converted to the container type, but items they contain are also converted to specified nested types (#4433). This works with all containers Robot Framework's argument conversion works in general. Most important examples are the already mentioned lists, dictionaries like dict[str, int], tuples like tuple[str, int, bool] and heterogeneous tuples like tuple[int, ...]. Notice that using parameters with Python's standard types requires Python 3.9. With earlier versions it is possible to use List, Dict and other such types available in the typing module.

Another container type that is nowadays handled better is TypedDict. Earlier, when TypedDicts were used as type hints, arguments were only converted to dictionaries, but nowadays items are converted according to the specified types. In addition to that, Robot Framework validates that all required items are present. (#4477)

Another nice enhancement is that automatic conversion nowadays works also with pathlib.Path. (#4461)

Enhancements for setting keyword and test tags

It is now possible to set tags for all keywords in a certain file by using the new Keyword Tags setting (#4373). It works in resource files and also in test case and suite initialization files. When used in initialization files, it only affects keywords in that file and does not propagate to lower level suites.

The Force Tags setting has been renamed to Test Tags (#4368). The motivation is to make settings related to tests more consistent (Test Setup, Test Timeout, Test Tags, ...) and to better separate settings for specifying test and keyword tags. Consistent naming also easies translations. The old Force Tags setting still works, but it will be deprecated in the future. When creating tasks, it is possible to use Task Tags alias instead of Test Tags.

To simplify setting tags, the Default Tags setting will also be deprecated. The functionality it provides, setting tags that some but no all tests get, will be enabled in the future by using -tag syntax with the [Tags] setting to indicate that a test should not get tag tag. This syntax will then work also in combination with the new Keyword Tags. For more details see #4374.

Possibility to disable continue-on-failure mode

Robot Framework generally stops executing a keyword or a test case if there is a failure. Exceptions to this rule include teardowns, templates and cases where the continue-on-failure mode has been explicitly enabled with robot:continue-on-failure or robot:recursive-continue-on-failure tags. Robot Framework 6.0 makes it possible to disable the implicit or explicit continue-on-failure mode when needed by using robot:stop-on-failure and robot:recursive-stop-on-failure tags (#4303).

start/end_keyword listener methods get more information about control structures

When using the listener API v2, start_keyword and end_keyword methods are not only used with keywords but also with all control structures. Earlier these methods always got exactly the same information, but nowadays there is additional context specific details with control structures. (#4335)

Libdoc enhancements

Libdoc can now generate keyword documentation not only for libraries and resource files, but also for suite files (e.g. tests.robot) and for suite initialization files (__init__.robot). The primary use case was making it possible for editors to show HTML documentation for keywords regardless the file user is editing, but naturally such HTML documentation can be useful also otherwise. (#4493)

Libdoc has also got new --theme option that can be used to enforce dark or light theme. The theme used by the browser is used by default as earlier. External tools can control the theme also programmatically when generating documentation and by calling the setTheme() Javascript function. (#4497)

Performance enhancements for executing user keywords

The overhead in executing user keywords has been reduced. The difference can be seen especially if user keywords fail often, for example, when using Wait Until Keyword Succeeds or a loop with TRY/EXCEPT. (#4388)

Python 3.11 support

Robot Framework 6.0 officially supports the new Python 3.11 release (#4401). Incompatibilities were pretty small, so also earlier versions work fairly well. Python 3.11 is 10-60% faster than Python 3.10 (which is also faster than earlier versions), so upgrading to it is a good idea even if you were not interested in new features it provides.

At the other end of the spectrum, Python 3.6 is deprecated and will not anymore be supported by Robot Framework 7.0 (#4295).

Backwards incompatible changes

  • Space is required after Given/When/Then prefixes used with BDD scenarios. (#4379)
  • Dictionary related keywords in Collections require dictionaries to inherit Mapping. (#4413)
  • Dictionary Should Contain Item from the Collections library does not anymore convert values to strings before comparison. (#4408)
  • Automatic TypedDict conversion can cause problems if a keyword expects to get any dictionary. Nowadays dictionaries that do not match the type spec cause failures and the keyword is not called at all. (#4477)
  • Generation time in XML and JSON spec files generated by Libdoc has been changed to 2022-05-27T19:07:15+00:00. With XML specs the format used to be 2022-05-27T19:07:15Z that is equivalent with the new format. JSON spec files did not include the timezone information at all and the format was 2022-05-27 19:07:15. (#4262)
  • BuiltIn.run_keyword() nowadays resolves variables in the name of the keyword to execute when earlier they were resolved by Robot Framework before calling the keyword. This affects programmatic usage if the used name contains variables or backslashes. The change was done when enhancing how keywords with embedded arguments work with BuiltIn.run_keyword(). (#1595)

Deprecated features

Force Tags and Default Tags settings

As discussed earlier, new Test Tags setting has been added to replace Force Tags and there is a plan to remove Default Tags altogether. Both of these settings still work but they are considered deprecated. There is no visible deprecation warning yet, but such a warning will be emitted starting from Robot Framework 7.0 and eventually these settings will be removed. (#4368)

The plan is to add new -tag syntax that can be used with the [Tags] setting to enable similar functionality that the Default Tags setting provides. Because of that, using tags starting with a hyphen with the [Tags] setting is now deprecated. If such literal values are needed, it is possible to use escaped format like \-tag. (#4380)

Keywords in test case files having precedence over local keywords in resource files

Keywords in test cases files currently always have the highest precedence. They are used even when a keyword in a resource file uses a keyword that would exist also in the same resource file. This will change so that local keywords always have highest precedence and the current behavior is deprecated. (#4366)

WITH NAME in favor of AS when giving alias to imported library

WITH NAME marker that is used when giving an alias to an imported library will be renamed to AS (#4371). The motivation is to be consistent with Python that uses as for similar purpose. We also already use AS with TRY/EXCEPT and reusing the same marker and internally used token simplifies the syntax. Having less markers will also ease translations (but these markers cannot yet be translated).

In Robot Framework 6.0 both AS and WITH NAME work when setting an alias for a library. WITH NAME is considered deprecated, but there will not be visible deprecation warnings until Robot Framework 7.0.

Singular section headers like Test Case

Robot Framework has earlier accepted both plural (e.g. Test Cases) and singular (e.g. Test Case) section headers. The singular variants are now deprecated and their support will eventually be removed (#4431). The is no visible deprecation warning yet, but they will most likely be emitted starting from Robot Framework 7.0.

Using variables with embedded arguments so that value does not match custom pattern

When keywords accepting embedded arguments are used so that arguments are passed as variables, variable values are not checked against possible custom regular expressions. Keywords being called with arguments they explicitly do not accept is problematic and this behavior will be changed. Due to the backwards compatibility it is now only deprecated, but validation will be more strict in the future. (#4462)

Custom patterns have often been used to avoid conflicts when using embedded arguments. That need is nowadays smaller because Robot Framework 6.0 can typically resolve conflicts automatically. (#4454)

robot.utils.TRUE_STRINGS and robot.utils.FALSE_STRINGS

These constants were earlier sometimes needed by libraries when converting arguments passed to keywords to Boolean values. Nowadays automatic argument conversion takes care of that and these constants do not have any real usage. They can still be used and there is not even a deprecation warning yet, but they will be loudly deprecated in the future and eventually removed. (#4500)

These constants are internally used by is_truthy and is_falsy utility functions that some of Robot Framework standard libraries still use. Also these utils are likely to be deprecated in the future, and users are advised to use the automatic argument conversion instead of them.

Python 3.6 support

Python 3.6 reached end-of-life in December 2021. It will be still supported by all future Robot Framework 6.x releases, but not anymore by Robot Framework 7.0 (#4295). Users are recommended to upgrade to newer versions already now.

The reason we still support Python 3.6 is that although its official support has ended, it is supported by various long-term support Linux distributions. It is, for example, the default Python version in RHEL 8 that is supported until 2029.

Acknowledgements

Robot Framework development is sponsored by the Robot Framework Foundation and its ~50 member organizations. Robot Framework 6.0 team funded by the foundation consisted of Pekka Klärck and Janne Härkönen (part time). In addition to that, the wider open source community has provided several great contributions:

Thanks also to all community members who have submitted bug reports, helped debugging problems, or otherwise helped to make Robot Framework 6.0 our best release so far!

Robot Framework Creator

Full list of fixes and enhancements

ID Type Priority Summary
#4096 enhancement critical Multilanguage support for markers used in data
#4390 enhancement critical Add and document translations
#519 enhancement critical Given/When/Then should support other languages than English
#1595 bug high Embedded arguments are not passed as objects when executed with Run Keyword or its variants
#4348 bug high Invalid IF or WHILE conditions should not cause errors that don't allow continuation
#4483 bug high BREAK and CONTINUE hide continuable errors with WHILE loops
#4295 enhancement high Deprecate Python 3.6
#430 enhancement high Keyword visibility modifiers for resource files
#4303 enhancement high Support disabling continue-on-failure mode using robot:stop-on-failure and robot:recursive-stop-on-failure tags
#4335 enhancement high Pass more information about control structures to start/end_keyword listener methods
#4366 enhancement high Give local keywords precedence over imported keywords in resource files
#4368 enhancement high New Test Tags setting as an alias for Force Tags
#4373 enhancement high Support adding tags for all keywords using Keyword Tags setting
#4380 enhancement high Deprecate setting tags starting with a hyphen like -tag using the [Tags] setting
#4388 enhancement high Enhance performance of executing user keywords especially when they fail
#4400 enhancement high Allow translating True and False words used in Boolean argument conversion
#4401 enhancement high Python 3.11 compatibility
#4433 enhancement high Convert and validate collection contents when using generics in type hints
#4454 enhancement high Automatically select "best" match if there is conflict with keywords using embedded arguments
#4477 enhancement high Convert and validate TypedDict items
#4493 enhancement high Libdoc: Support generating keyword documentation for suite files
#4351 bug medium Libdoc can give bad error message if library argument has extension matching resource files
#4355 bug medium Continuable failures terminate WHILE loops
#4357 bug medium Parsing model: Creating TRY and WHILE statements using from_params is not possible
#4359 bug medium Parsing model: Variable.from_params doesn't handle list values properly
#4364 bug medium @{list} used as embedded argument not anymore expanded if keyword accepts varargs
#4381 bug medium Parsing errors are recognized as EmptyLines
#4384 bug medium RPA aliases for settings do not work in suite initialization files
#4387 bug medium Libdoc: Fix storing information about deprecated keywords to spec files
#4408 bug medium Collection: Dictionary Should Contain Item incorrectly casts values to strings before comparison
#4418 bug medium Dictionaries insider lists in YAML variable files not converted to DotDict objects
#4438 bug medium Get Time returns current time if it is given input time that matches epoch
#4441 bug medium Regression: Empty --include/--exclude/--test/--suite are not ignored
#4447 bug medium Evaluating expressions that modify evaluation namespace (locals) fail
#4455 bug medium Standard libraries don't support pathlib.Path objects
#4464 bug medium Libdoc: Type hints aren't shown for types with same name as Javascript variables available in browser namespace
#4476 bug medium BuiltIn: Call Method loses traceback if calling the method fails
#4480 bug medium Creating log and report fails if WHILE loop has no condition
#4482 bug medium WHILE and FOR loop contents not shown in log if running them fails due to errors
#4484 bug medium Invalid TRY/EXCEPT structure causes normal error, not syntax error
#4262 enhancement medium Honor SOURCE_DATE_EPOCH environment variable when generating library documentation
#4312 enhancement medium Add project URLs to PyPI
#4353 enhancement medium Performance enhancements to parsing
#4354 enhancement medium When merging suites with Rebot, copy documentation and metadata from merged suites
#4371 enhancement medium Add AS alias for WITH NAME in library imports
#4379 enhancement medium Require space after Given/When/Then prefixes
#4398 enhancement medium Collections: Get From Dictionary should accept a default value
#4404 enhancement medium Document that failing test setup stops execution even if continue-on-failure mode is active
#4413 enhancement medium Dictionary related keywords in Collections are more script about accepted values
#4429 enhancement medium Allow passing flags to regexp related keywords using explicit flags argument
#4431 enhancement medium Deprecate using singular section headers
#4440 enhancement medium Allow using None as custom argument converter to enable strict type validation
#4461 enhancement medium Automatic argument conversion for pathlib.Path
#4462 enhancement medium Deprecate using embedded arguments using variables that do not match custom regexp
#4470 enhancement medium Enhance Keyword Should Exist performance by not looking for possible recommendations
#4490 enhancement medium Time string parsing for micro and nanoseconds
#4497 enhancement medium Libdoc: Support setting dark or light mode explicitly
#4349 bug low User Guide: Example related to YAML variable files is buggy
#4358 bug low User Guide: Errors in examples related to TRY/EXCEPT
#4453 bug low Run Keywords: Execution is not continued in teardown if keyword name contains non-existing variable
#4471 bug low Libdoc: If keyword and type have same case-insensitive name, opening type info opens keyword documentation
#4481 bug low Invalid BREAK and CONTINUE cause errros even when not actually executed
#4346 enhancement low Enhance documentation of the --timestampoutputs option
#4372 enhancement low Document how to import resource files bundled into Python packages
#4485 enhancement low Explain the default value of Sleep keyword better in its documentation
#4500 enhancement low Deprecate robot.utils.TRUE/FALSE_STRINGS
#4511 enhancement low Support custom converter with more than one argument as long as they are not mandatory
#4394 bug --- Error when --doc or --metadata value matches an existing directory

Altogether 68 issues. View on the issue tracker.