Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit e24ffd9

Browse files
aaltataaltat
committed
Variable type defintion documentation -m Fixes:
1 parent ebcd593 commit e24ffd9

File tree

2 files changed

+224
-1
lines changed

2 files changed

+224
-1
lines changed

‎doc/userguide/src/CreatingTestData/CreatingUserKeywords.rst

+36
Original file line numberDiff line numberDiff line change
@@ -480,6 +480,42 @@ with and without default values is not important.
480480
[Arguments] @{} ${optional}=default ${mandatory} ${mandatory 2} ${optional 2}=default 2 ${mandatory 3}
481481
Log Many ${optional} ${mandatory} ${mandatory 2} ${optional 2} ${mandatory 3}
482482

483+
Variable type in user keywords
484+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
485+
486+
Arguments in user keywords support optional type definition syntax, as it
487+
is explained in `Variable type definition`_ chapter. The type definition
488+
syntax starts with a colon, contains a space and is followed by the type
489+
name, then variable must be closed with closing curly brace. The type
490+
definition is stripped from the variable name and variable must be used
491+
without it in the keyword body. In the example below, the `${arg: int}`,
492+
contains type int, the type definition `: int` is stripped from the
493+
variable name and the variable is used as `${arg}` in the keyword body.
494+
495+
.. sourcecode:: robotframework
496+
497+
*** Keywords ***
498+
Default
499+
[Arguments] ${arg: int}=1
500+
Should be equal ${arg} 1 type=int
501+
502+
Free named arguments can also have type definitions, but the argument
503+
does not support type definition for keys. Only type for value(s) can be
504+
defined. In Python the key is always string. In the example below, the
505+
`${named: `int|float`}` contains type `int|float`. All the keys are
506+
strings and values are converted either to int or float.
507+
508+
.. sourcecode:: robotframework
509+
510+
*** Test Cases ***
511+
Test
512+
Type With Free Names Only a=1 b=2.3
513+
514+
*** Keywords ***
515+
Type With Free Names Only
516+
[Arguments] ${named: `int|float`}
517+
Should be equal ${named} {"a":1, "b":2.3} type=dict
518+
483519
__ https://www.python.org/dev/peps/pep-3102
484520
__ `Variable number of arguments with user keywords`_
485521
__ `Positional arguments with user keywords`_

‎doc/userguide/src/CreatingTestData/Variables.rst

+188-1
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,8 @@ test cases or user keywords (for example, `${my var}`). Much more
7474
importantly, though, case should be used consistently.
7575

7676
Variable name consists of the variable type identifier (`$`, `@`, `&`, `%`),
77-
curly braces (`{`, `}`) and the actual variable name between the braces.
77+
curly braces (`{`, `}`) and the actual variable name between the braces,
78+
excluding the possible variable type definition.
7879
Unlike in some programming languages where similar variable syntax is
7980
used, curly braces are always mandatory. Variable names can basically have
8081
any characters between the curly braces. However, using only alphabetic
@@ -1519,6 +1520,192 @@ __ `Setting variables in command line`_
15191520
__ `Return values from keywords`_
15201521
__ `User keyword arguments`_
15211522

1523+
Variable type definition
1524+
------------------------
1525+
1526+
As explained earlier, by default variables are unicode strings. But
1527+
variables can have optional type definition, which is part of variable
1528+
name inside of the curly brackets. Type definition comes after the
1529+
variable name and is started with a colon, continued with space and then
1530+
defining a type. After the type definition, variable must be closed with
1531+
the closing curly bracket. When the test data is parsed, the type is
1532+
checked and saved internally for conversion usage. The type definition is
1533+
removed from the variable name and the variable must be used without the
1534+
type definition.
1535+
1536+
In example below, variable `${value: int}` is created with type `int` and
1537+
string `123` is converted to integer. The type definition `: int` is
1538+
stripped from the variable name and the variable must be used with the
1539+
name `${value}`.
1540+
1541+
.. sourcecode:: robotframework
1542+
1543+
*** Test Cases ***
1544+
Integer
1545+
VAR ${value: int} 123
1546+
Should be equal ${value} 123 type=int
1547+
1548+
If type conversion fails, then the test case fails and defined variable is
1549+
not created. Conversion can fail if the type is not one of the library API
1550+
`supported conversions`_ types or if the value can not be converted to the
1551+
defined type. In the examples below, the `Invalid type` test case has type
1552+
which is not one of supported types and therefore the test case fails. The
1553+
`Invalid value` test case has string value which can not be converted to
1554+
the integer type and therefore the test case fails. The variables are not
1555+
created in either case.
1556+
1557+
.. sourcecode:: robotframework
1558+
1559+
*** Test Cases ***
1560+
Invalid type
1561+
VAR ${value: invalid} 123.45
1562+
1563+
Invalid value
1564+
VAR ${value: int} bad
1565+
1566+
1567+
Although variable name can be created dynamically in Robot Framework,
1568+
variable type can not be created dynamically by a another variable. If type
1569+
definition is defined by variable, in this case the type definition is not
1570+
removed and variable is created with colon, space and type in the name.
1571+
Therefore type definition must be static in the variable name when
1572+
variable is created. If just the type, like `int`, without the colon and
1573+
space, is defined by a variable, then test case fails and variable is not
1574+
created.
1575+
1576+
.. sourcecode:: robotframework
1577+
1578+
*** Test Cases ***
1579+
Dynamic types not supported
1580+
VAR ${type} : int
1581+
VAR ${value${int} 123
1582+
Should be equal ${value: int} 123 type=str
1583+
Variable should not exist ${value}
1584+
1585+
Type in variable fails
1586+
VAR ${type} int
1587+
VAR ${value: ${int} 123 # Fails on: Unrecognized type '${type}'.
1588+
1589+
Type definition is supported when variable is assigned a value, example in
1590+
the `variable section`_, `var syntax`_ or `return values from keywords`_.
1591+
Variable type definition is not supported when variable is used, example
1592+
when variable is given as keyword argument. In the example below, at the
1593+
variable table variable `${VALUE}` is created because value `123` is
1594+
assigned to the variable. The `Assign value` test case passes because the
1595+
`Set Variable` keyword is used to assign the value `2025-04-30` to the
1596+
variable `${date}`. The `Using variable` test case fails because type can
1597+
not be defined when variable is used.
1598+
1599+
.. sourcecode:: robotframework
1600+
1601+
*** Variables ***
1602+
${VALUE: int} 123
1603+
1604+
*** Test Cases ***
1605+
Assign value
1606+
${date: date} Set Variable 2025-04-30
1607+
Should be equal ${date} 2025-04-30 type=date
1608+
1609+
Using fails
1610+
Should be equal ${VALUE: str} 123 # This fails on syntax error.
1611+
1612+
.. note:: The exception to variable type definition usage on assignment
1613+
are the `Set Local/Test/Suite/Global Variable` keywords. These
1614+
keywords do not support type definition in the variable name.
1615+
Instead use the `var syntax`_ for defining variable type and
1616+
scope.
1617+
1618+
Variable types in scalars
1619+
~~~~~~~~~~~~~~~~~~~~~~~~~
1620+
1621+
When creating scalar variables, the syntax is familiar to the Python
1622+
`function annotations`_ and it is possible to do conversion to same
1623+
types that are supported by the library API `supported conversions`_.
1624+
Using customer converters or other types than ones listed in the
1625+
supported conversions table are not supported.
1626+
1627+
1628+
Variable types in lists
1629+
~~~~~~~~~~~~~~~~~~~~~~~
1630+
1631+
List variable types are defined using the same syntax as scalar variables,
1632+
a colon, space and type definition. Because in Robot Framework test data,
1633+
list variable starts explicitly with `@`, therefore in test data type
1634+
definition only supports type definition for item(s) inside of the list.
1635+
In the example in below `@{list_of_int: int}` is created with type
1636+
definition `int` and the list items are converted to integers. The type
1637+
definition is stripped from the variable name and the variable can be used
1638+
with the name `@{list_of_int}`.
1639+
1640+
.. sourcecode:: robotframework
1641+
1642+
*** Test Cases ***
1643+
List
1644+
VAR @{list_of_int: int} 1 2 3
1645+
Should be equal ${list_of_int} [1, 2, 3] type=list
1646+
1647+
Although Robot Framework type conversion is versatile and supports many
1648+
different type of conversions, not all possible combination are possible
1649+
with list. In example below, the `Not a list` fails because Robot
1650+
Framework can not convert ["1", "2", "3"] to a float. To fix the test
1651+
case, replace `$` with `@` sing and then conversion works as expected.
1652+
The `This is a list` and `List here` test cases passes because the scalar
1653+
variable has correct type `list[float]`. In the `This is a list` test,
1654+
list items are converted to floats. In the `List here` test case,
1655+
value is converted to list and then items are converted to floats.
1656+
1657+
.. sourcecode:: robotframework
1658+
1659+
*** Test Cases ***
1660+
Not a list
1661+
${x: float} = Create List 1 2 3
1662+
1663+
This is a list
1664+
${x: list[float]} = Create List 1 2 3
1665+
Should be equal ${x} [1.0, 2.0, 3.0] type=list
1666+
1667+
List here
1668+
VAR ${x: list[float]} [1, "2", 3]
1669+
Should be equal ${x} [1.0, 2.0, 3.0] type=list
1670+
1671+
Variable types in dictionaries
1672+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1673+
1674+
Dictionary variable types are defined using the same syntax as scalar or
1675+
list variables, a colon, space and type definition, closed by a closing
1676+
curly brace. But because dictionary contains key value pairs, the type
1677+
definition can contain type for both key and value or only the value. In
1678+
later case the key type is set to `Python Any`_. When defining type for
1679+
both key and value, the type defintion is consists two types separated
1680+
with a equal sing. As with scalar and list variables, the type definition
1681+
is stripped from the variable name. The dictionary key(s) can not be
1682+
converted to all types found from `supported conversions`_, instead key
1683+
must be Python immutable type, see more details from the
1684+
`Python documentation`_.
1685+
1686+
In the example below, `&{dict_of_str: int=str}` is created with type
1687+
`int=str` and the dictionary keys are converted to integers and the
1688+
values are converted to strings. The type definition, `: int=str` is
1689+
stripped from the variable name and the variable can be used with the
1690+
name `&{dict_of_str}`. The `&{dict_of_int: int}` is created with type
1691+
definition `Any=int` and the dictionary keys are kept as is (`Any` in
1692+
practice means no conversion) and the values are converted to integers.
1693+
The type definition `: int` is stripped from the variable name and the
1694+
variable can be used with the name `&{dict_of_int}`.
1695+
1696+
.. sourcecode:: robotframework
1697+
1698+
*** Test Cases ***
1699+
Dictionary
1700+
VAR &{dict_of_str: int=str} 1=2 3=4 5=6
1701+
Should be equal ${dict_of_str} {1: '2', 3: '4', 5: '6'} type=dict
1702+
VAR &{dict_of_int: int} 7=8 9=10
1703+
Should be equal ${dict_of_int} {'7': 8, '9': 10} type=dict
1704+
1705+
.. _function annotations: https://www.python.org/dev/peps/pep-3107/
1706+
.. _Python Any: https://docs.python.org/3/library/typing.html#the-any-type
1707+
.. _Python documentation: https://docs.python.org/3/reference/datamodel.html
1708+
15221709
Advanced variable features
15231710
--------------------------
15241711

0 commit comments

Comments
 (0)